mini tutorial for video playback, manipulation and recording in
pf. this tutorial uses a video file for input, but can also be
modified to use live video input or any other video source.

in the world of video codecs, there are two main variants: files that
can be accessed randomly (retreive any frame using an index) and files
that can only be accessed sequentially (get the next frame).

PF supports the former, which are usually called "production codecs"
in terms of quicktime files with frame based codecs like mjpeg or
photo jpeg, and the latter, which are called "distribution codecs" by
using ffmpeg or mencoder as subprocesses to do the encoding/decoding.


PRODUCTION: LIBQUICKTIME
------------------------

make sure quicktime support is loaded using 'load-lqt' this
will provide you with words like 'mov-player' and 'mov-recorder'

we will create a single player, calling it 'player'

   qt-player player


recommended codecs are jpeg photo (single frames) or raw, which are
frame indexable. mjpeg is better for (field indexed) interlaced video,
but there is no specific support in pf for processing interlaced video
frames.

to open a movie file we do

   "test.mov" player open

the word 'player' will modify the meaning of open so it refers to the
movie player we created above. once a movie file is loaded, the
'player' object now behaves as an indexable array, so we can grab
frames by performing.

    13 player @

where again 'player' modifies the meaning of '@'.

recording movis works similar. first we will create a recorder:

    qt-recorder recorder

to start writing to a movie file, it first has to be created by
issuing:

    "/tmp/test.mov" recorder create

the movie format is determined by the type of bitmap packet you write
to it first. all subsequent bitmap types need to be the same. writing
works like this:
    recorder write   # ( bitmap -- )


when done, the file needs to be properly closed:

    recorder close



DISTRIBUITION: FFMPEG/MENCODER
------------------------------

to directly record to a production codec, you'll need 'load-codecs'.
this creates some wrapper words around the external ffmpeg and
mencoder apps.

for example, recording to mpeg4 can be done using the 'mpeg4-recorder'
word, in exactly the same way as the 'qt-recorder' works. this word is
a shorthand for

    ` mpeg4 raw-ffmpeg-recorder recorder

you can replace 'mpeg4' with any other code that ffmpeg supports.

playback needs extra arguments: the dimensions of the desired bitmap,
and the encoding. for example

     320 240 ` i420 ff-player player

using mencoder instead of ffmpeg can be done using 'mp-player' instead
of 'ff-player'. once initialized, a file can be opend using

     player open   # ( filename -- )

bitmaps can be obtained as

     player read   # ( -- bitmap )

this operation will throw an 'e_eof' error when one tries to read
beyond the end of the movie file. use 'player rewind' to rewind to the
beginning of the file.