



                     !FFplay : A simple audio/video player


             "FFplay Control" front-end version 2.00 (31 May 2015)
        incorporating a customised "ffplay" player version 2.6.1-iyonix
      built on 27 April 2015 with GCCSDK GCC 4.7.4 Release 1 Development.


  ARMv7 users, please note: Some formats need alignment exceptions turned off.



FFplay is a simple media player built from FFmpeg and SDL. It is mostly  used by
the FFmpeg development team as a testbed for the various FFmpeg APIs.  It is not
intended to be a high-gloss  high-performance player, but it will fill a  gap on
the RISCOS platform  until something better comes  along. !FFplay is a  RISC OS
application  that in  theory plays  any media  format decodable  by !FFmpeg.  In
practice,   many  formats   and  recordings  will   be  painfully   slow  and/or
unsynchronised. The player requires  at least 32K colours, a StrongARM or faster
CPU, and  14MB to even start.  It will require much additional  memory to buffer
files during playback.

The !FFplay  application is  actually a  simple front-end  for  the real  player
program, ffplay, which lives inside the application folder. !FFplay controls the
player by  setting a system  variable with  a few  command-line options for  the
player. These  options  are picked  up by  the player  when  it is  run from  an
obeyfile  which also  lives  inside  the application  folder.  !FFplay can  also
receive and display run-time status updates from the player.

After  the   Filer   has  "seen"   (i.e.   booted)  the   !FFplay   application,
double-clicking a  file of  type &FB2  (Quicktime,  AVI, etc.)  will launch  the
player. !FFplay does not need to be running for this to work.

Running !FFplay  will place an icon on the iconbar.  You can use the icon's menu
to  manage a few options  for the player as  explained further below. The player
has a great many options; !FFplay lets you manage only a few that may often need
adjustment. More  advanced player control  is possible but  beyond the scope  of
this application.

Dragging a file of  any type, not  just &FB2, from a  Filer window to  !FFplay's
iconbar icon will launch the  player. The file's location will be  remembered so
that clicking  SELECT on the  icon will re-play  the file.  Once the player  has
started, changing !FFplay's options will have no effect on it. But you may click
SELECT while a file is playing to re-start it with altered options.

One option,  "Status", will  cause a  run-time Status  window to  be opened  and
receive status updates each time the player is launched. Clicking  ADJUST on the
iconbar icon will have the same immediate effect at any time.

If !FFplay is quit, the currently  selected player options will not change.  But
if !FFplay is re-run, the options will be reset.


Player Controls
~~~~~~~~~~~~~~~

The key controls below require the player to have the input focus. If the player
has lost the input focus, a click with SELECT or MENU will regain it.

q, ESC              quit
f                   toggle full screen
p, SPC              pause
m                   toggle mute
9, 0                decrease and increase volume respectively
/, *                decrease and increase volume respectively
a                   cycle audio channel in the current program
v                   cycle video channel
t                   cycle subtitle channel in the current program
c                   cycle program
w                   cycle video filters or show modes
s                   activate frame-step mode
left/right          seek backward/forward 10 seconds
down/up             seek backward/forward 1 minute
page down/page up   seek backward/forward 10 minutes
right mouse click   seek to percentage in file corresponding to fraction of width
left double-click   toggle full screen


Iconbar Options
~~~~~~~~~~~~~~~

Audio  can  be  turned  on  or  off.  Note  that  audio  output  relies  on  the
DigitalRenderer module. This  should be installed on  your computer so that  the
player can find it as "System:Modules.DRenderer". If the  player cannot find it,
then playback will be silent.

For finer audio control, the size  of the audio buffer can be adjusted.  Smaller
buffers are better for synchronisation but can produce very choppy sound. Larger
buffers produce less choppy sound but poorer synchronisation.

When playing audio alone, the player can produce an FFT display of the audio. If
playing audio alone with the FFT display option turned off, a plain black window
will be shown.

Video can be turned on or off.

As an aid to synchronisation and normal-speed playback, you can choose  to allow
video frames to be  dropped. But note that  even with frame dropping turned  on,
video is likely to lag. (Though I have also seen the opposite case, in which the
video races  ahead of  the audio, when  the media  has been poorly  synchronised
during production.) And if the system still can't  keep up, the player will give
up trying to keep the streams synchronised and the video will lag.

When frame dropping isn't sufficient  for synchronised playback, you can  choose
to display keyframes only. When it  works, this will play the video more  like a
slideshow with synchronised soundtrack.  And it will greatly reduce the  load on
your system so  frame dropping may  not be required. This  will let you  see the
video sufficiently to decide whether to spend the time converting it to a format
more  suited to full-motion  playback on  your system.  (Note that  some formats
don't  use keyframes  and some  recordings make  poor use  of keyframes,  so the
results may not be what you were hoping for.)

When Fullscreen is turned on, the player will automatically start  in fullscreen
mode.

When Verbose is turned on, the  player will output several lines of  information
about the video played. But you  won't see any of this info until  playback ends
and a throwback window is opened.

When Status is  turned on, a run-time  Status window will  be opened to  receive
status updates each time the player is launched.


More about Fullscreen and Performance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When fullscreen playback is requested,  (either by pressing "f" during  windowed
playback, or by selecting Fullscreen on the iconbar menu) the screen mode chosen
will be the smallest one that  fits the video frame. The number of  colours will
be the same as that used by the desktop.

Despite appearances, fullscreen operation is not single-tasking.  Performance is
likely to be better in windowed mode. Performance will also be  better in screen
modes with 32 thousand colours (as opposed to 16 million colours).


More about the Status window
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As well as using the iconbar option to automatically activate the  Status window
when the  player is launched,  you can  open the  Status window at  any time  by
clicking ADJUST on FFplay's iconbar icon.

Generating and receiving run-time status updates does put additional load on the
CPU for  every  frame  displayed, so  you  might  want to  use  this  capability
sparingly. But if you  are intending to clip  videos with !FFmpeg, you  may find
the leftmost number in the Status window particularly  useful; it is the current
frame's timecode in seconds.

If you click  SELECT or ADJUST on the  text icon in the Status  window, the text
will  freeze. This  may also  be useful  if you  are planning  to do  some video
editing. To unfreeze the text, click on it again.


<redacted>
Frame dropping and Keyframes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have enabled frame  dropping but the video  falls behind the audio by  10
seconds or more,  the player will  automatically switch to displaying  keyframes
only. This will usually cause some frames to be displayed ahead of the audio.
</redacted>


Screensaver
~~~~~~~~~~~

While playing either windowed or fullscreen, the system screensaver is disabled.


Throwback
~~~~~~~~~

The player isn't a native RISC OS Desktop application. Originating in  the Linux
world, it likes  to output  text to a  console. On  RISC OS, this  text must  be
captured to a file or pipe. When the !FFplay application is running, any warning
and error messages from the  player will be displayed in a  throwback window. If
!FFplay isn't running, you won't see any text from the player.

This throwback  capability depends on  the DDEUtils  module. Also, bear  in mind
that  double-clicking  text in  the  throwback window  will  not  result in  any
sensible  action  because there  will  be  no text  file  to  throwback to.  The
throwback window will  instead be pointing to the movie  just played! This is an
unconventional use of throwback, but some users may find it useful.


Geminus
~~~~~~~

Interactions between the player and  Geminus are complicated. Testing on  Iyonix
suggests that on  systems with  Geminus installed, the  player can benefit  from
accelerated sprite  plotting. But  don't cache  the player's  sprites or  window
contents in off-screen video memory!  If you want to add the  player to Geminus'
list of  acceleration options for  specific applications, start a  movie playing
and then look to add application "ffplay" which is the player itself. (Take care
not to mistake the front-end "FFplay Command" for the player "ffplay".)

If you will be playing fullscreen  scaled-up video, it may also be beneficial to
have  Geminus accelerate sprite plotting for  `Other apps'. Even so, accelerated
sprite  plotting of  scaled-up video comes  at a  cost: audio stops  during each
frame  blit! This  isn't noticeable  with low-ish  bitrates due  to audio stream
buffering, but  plotting large  or  scaled-up frames  will result  in  seriously
chopped-up sound.

For those experienced at configuring RISC OS systems, there is  more information
in the obeyfile <!FFplay.!Configure>.


Advanced Capabilities and Customisation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This section is for experienced  RISC OS users. To access advanced  capabilities
of FFplay will require setting system variables or editing Obey scripts.

Inside the  !FFplay  application folder  are  Documents including  licences  and
information about the player's many options. You can also get a complete list of
options  by  running  this  command  in  a  taskwindow  with  a  14MB  wimpslot:
   *ffplay:ffplay --help

To auto-play MPEG  (filetype &BF8)  movies, edit obeyfile  <!FFplay.!Configure>;
though !KinoAmp is a far more capable MPEG 1/2 player.

To change the default player options,  first run !FFplay and select the  options
you prefer. Then in a taskwindow, run this command:
   *Show FFplay$opts
Then edit obeyfile <!FFplay.!Configure> so  that FFplay$opts is set to what  the
above command showed.

If your system has  another form of  accelerated sprite plotting, edit  obeyfile
<!FFplay.!Configure> to make use of it. I'd appreciate feedback on this so I can
cater for other graphics accelerators in future releases.

In addition to the default options controlled by !FFplay, you sometimes  want to
use additional arguments.  For example,  you may set  cut-in and cut-out  points
with arguments -ss <start> and -t <duration>.  Variable FFplay$args is available
for this purpose. Here is an example command:
   *Set FFplay$args -ss 90 -t 30
This will play videos for 30 seconds starting at 90 seconds in.

There are  potentially three  ways to  play a  480x360 video  at reduced  scale,
though it may make little difference to the playback speed:
   *Set FFplay$args -x 240 -y 180
   *Set FFplay$args -vf "scale=240:180"
   *Set FFplay$args -lowres 1
The first way is likely  to be fastest. The last  way may not work; some  codecs
support it, some don't. You could use this to shrink any video to quarter-size:
   *Set FFplay$args -vf "scale=iw/2:-1"

Another option is to crop rather than shrink:
   *Set FFplay$args -vf "crop=240:180:120:90"	(width:height:left:top)
   *Set FFplay$args -vf "crop=360:360:60:0"	(full vertical frame)
There is a trade-off between computing these transformations in real-time versus
reducing  the  amount   of  pixel  shunting   for  each  frame.  Computing   the
transformations can take less CPU bandwidth than pixel shunting, but not usually
by much. You may prefer to use FFmpeg to transform the video prior to playing.

To change what !FFplay does  with text output from  the player, you may want  to
edit obeyfile  <!FFplay.!FFplay>. This  obeyfile runs the  player directing  its
output to a pipe which !FFplay then forwards to a throwback window.

You may  also want to edit obeyfile <!FFplay.!AutoPlay>.  This obeyfile runs the
player when  the !FFplay application is  not running. Output from  the player is
directed  to the null: filing  system and is  not saved or  displayed. You might
prefer to save error output to a file in a RamDisc.

In theory, online streams can be  played. (Don't forget that FFmpeg can  capture
streams for processing and  repeated viewing without wasting  online bandwidth.)
You can initiate streaming by dropping a file of type  &B28 (URL) onto !FFplay's
iconbar icon. The URL must be one supported by FFmpeg.  For example, if you have
the URL  of a stream  on an MMS  server, you would  specify "mmsh://"  (MMS over
HTTP) or  "mmst://" (MMS  over TCP)  as the  protocol. For  a list  of supported
protocols, run this command:
   *ffplay:ffplay -protocols


Licences
~~~~~~~~

This release includes a RISC OS  port of ffplay embedded in !FFplay, a  combined
front-end application and resource  locator. All components of this  release are
distributed as open source freeware under public licences. The !FFplay front-end
is  Copyright ()  2008-2012 Christopher  Martin  <belles@internode.on.net>, all
rights reserved.

Permission is hereby granted, free of charge, to  any person obtaining a copy of
this software  and associated documentation  files (the "Software"),  to deal in
the  Software without  restriction, including  without limitation the  rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit  persons to whom the Software is furnished to do so,
subject  to all copyright  notices and this permission  notice being included in
all copies or substantial portions of the Software.

THE  SOFTWARE IS  PROVIDED "AS  IS", WITHOUT  WARRANTY OF  ANY KIND,  EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS  OR
COPYRIGHT HOLDERS BE LIABLE  FOR ANY CLAIM, DAMAGES OR OTHER  LIABILITY, WHETHER
IN AN  ACTION  OF CONTRACT,  TORT  OR  OTHERWISE, ARISING  FROM,  OUT OF  OR  IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The      !FFplay       front-end      is      constructed      using      DrWimp
<http://www.rayfavre.me.uk/drwimp.html>.  But  please  note  that  the  embedded
DrWimp library contains modifications specifically in support of !FFplay. Please
note  also that if  you redistribute the  !FFplay application  (or a substantial
portion thereof) in or with some other application, then you too will be obliged
to  honour  DrWimp's  Conditions of  Use.  The  conditions are  included  in the
Documents inside the application folder.

The embedded ffplay program is Copyright () 2000-2011 the FFmpeg developers. It
is based in part  on the work of the  Independent JPEG Group. It was  configured
for compilation and distribution under the GNU General  Public License version 2
or later.  Please note  that if  you redistribute  ffmpeg and/or  !FFmpeg (or  a
substantial portion  thereof) in or  with some  other application, then  you too
will be obliged to  honour the GPL. This licence is included  as file COPYING in
the Documents inside the application folder.

The  sources  for  ffplay  are  not  included  in  this  release.  A  sourcecode
distribution  of   ffplay   can   be   downloaded  from   the   FFmpeg   website
<http://ffmpeg.mplayerhq.hu>. To build ffplay for RISC OS, you will also need:

      !GCC 4 (on RISC OS) or GCCSDK (on Linux);
      Several libraries: Z, LAME, Ogg Vorbis and OSLib;
      My modifications to the ffplay and SDL 1.2.14 sources;
      My ffplay configuration files and build scripts (optional on Linux).

Configuring and building ffplay, while  no trivial matter, should be  reasonably
straightforward for any competent programmer with appropriate  tools. Contact me
for assistance  if  you want  to build  a  version of  ffplay  tailored to  your
requirements.


Copyright () 2008-2012 Christopher Martin <belles@internode.on.net>.
All rights reserved.