STORYBOARD_FILES           2011.04.14:


General
-------
A STORYBOARD_FILE is a textfile that can be used to
assemble many audiofiles, videoclips, single images and frame sequences 
to one resulting video.

The images and frame sequences may be located in different directories,
and can contain frame_images of any imagefiletype
(.jpg, .xcf, .gif ...) that is readable by GIMP.
You may also use parts from videofiles.
(.avi, .mpg ... see chapter supported video input)

all frames are converted and scaled to the desired
video master size on the fly at encoding time.

All frame sequences and videoclips are played at the desired
master framerate. This will result in speed up or
slow down in all non rate-matching sequences.
You can compensate this effect by dropping/duplicating
the input frames or by using individual stepsize parameters
on your input videoclips.

The built in audio processing has support for
uncompressed audio in the RIFF WAVE format,
but you can use any other Audioformat if you
have installed an external converter tool.

sox and lame are configured as default
converter tools, so it is possible
to use many different audio formats
(including mp3). Recoding and resampling
is done automatically where needed.





Syntax:
-------
The STORYBOARD_FILE is organized in textlines with blank
separated items. The 1.st item is a Keyword that describes
the RECORD Type of the line.
The other items depend on the RECORD Type.
Lines starting with # are Comments, Blanklines are allowed and will be ignored.

You may join 2 or more Lines to one logical Line
if you set the backslash '\' as last character 
(immediate before newline)


item values may be specified using a parametername key prefix
in the style:

   key:value

if no parametername key prefix is specified the fixed order of items
is assumed. items must not contain blanks. (except blanks in "quoted strings")

Note: you should not use this style without key that is just supported
for backwards compatibility with old GIMP-GAP versions)


Overview of supported RECORD TYPES:
----------------------------------

STORYBOARDFILE    version:1.0   # comments


VID_MASTER_FRAMERATE    frames_per_sec:24.0
VID_MASTER_FRAME_ASPECT width:16 height:9
VID_MASTER_SIZE         width:320  height:200
VID_PREFERRED_DECODER   libavformat
VID_MASTER_LAYERSTACK   track1:Background
VID_MASTER_INSERT_ALPHA format:"/path/file_%s_%06d.xcf"

AUD_MASTER_VOLUME      volume:1.0
AUD_MASTER_SAMPLERATE  samples_per_sec:44100

# video clip descriptions
VID_PLAY_MOVIE     track:1  file:"movie_filename"     from:0001  to:0099 \
                             mode:{pingpong|normal}\
                             nloops:1 \
	                     seltrack:1 \
                             exactseek:0 \
                             deinterlace:1.0 \
			     stepsize:1.0 \
                             macro:"macro_filename" \
                             flip:n \
			     mask_name:"maskname" \
			     mask_anchor:clip \
			     mask_stepsize:1.0 \
			     mask_disable:n \
			     macsteps:1 \
			     macaccel

VID_PLAY_ANIMIMAGE track:1  file:"image_filename"     from:0001 to:0099  \
                             mode:{pingpong|normal} \
                             nloops:1 \
			     stepsize:1.0 \
			     macro:"macro_filename"
                             flip:n \
			     mask_name:"maskname" \
			     mask_anchor:clip \
			     mask_stepsize:1.0 \
			     mask_disable:n \
			     macsteps:1 \
			     macaccel

VID_PLAY_FRAMES    track:1  base:"basename" ext:.jpg  from:0001 to:0099  \
                             mode:{pingpong|normal} \
                             nloops:1 \
			     stepsize:1.0 \
			     macro:"macro_filename"
                             flip:n \
			     mask_name:"maskname" \
			     mask_anchor:clip \
			     mask_stepsize:1.0 \
			     mask_disable:n \
			     macsteps:1 \
			     macaccel

VID_PLAY_IMAGE     track:1  file:"image_filename"    nloops:1 \
                             macro:"macro_filename"
                             flip:n \
			     mask_name:"maskname" \
			     mask_anchor:clip \
			     mask_stepsize:1.0 \
			     mask_disable:n \
			     macsteps:1 \
			     macaccel

VID_PLAY_COLOR     track:1  red:0.0 green:1.0 blue:0.0 alpha:1.0   nloops:1 \
                             flip:n \
			     mask_name:"maskname" \
			     mask_anchor:clip \
			     mask_stepsize:1.0 \
			     mask_disable:n \
			     macsteps:1 \
			     macaccel

VID_SILENCE        track:1                                         nloops:1  wait_until_sec:0.0

# video attributes
VID_ROTATE         track:1  rotate_from:0.0      rotate_to:360.0    nframes:10
VID_OPACITY        track:1  opacity_from:0.0     opacity_to:1.0     nframes:10
VID_ZOOM_X         track:1  zoom_x_from:0.1      zoom_x_to:10.0     nframes:10
VID_ZOOM_Y         track:1  zoom_y_from:0.1      zoom_y_to:10.0     nframes:10
VID_MOVE_X         track:1  move_x_from:-1.0     move_x_to:1.0      nframes:10
VID_MOVE_Y         track:1  move_y_from:-1.0     move_y_to:1.0      nframes:10
VID_FIT_SIZE       track:1  mode:{both|none|width|height}  proportions:{keep_proportions|change_proportions}
VID_OVERLAP        track:1  nframes:0


# mask definitions
MASK_IMAGE        mask_name:"m1" file:"mask_filename"
MASK_ANIMIMAGE    mask_name:"m2" file:"mask_filename"     from:0001 to:0099
MASK_FRAMES       mask_name:"m3" base:"basename" ext:.jpg from:0001 to:0099
MASK_MOVIE        mask_name:"m4" file:"mask_filename"     from:0001 to:0099


# audio clip descriptions
AUD_PLAY_SOUND     track:1  file:"audiofile" start_sec:0.0 end_sec:10.2 \
                             volume:1.0 \
                             start_vol:0.0 fade_in_time:1.0  \
                             end_vol:0.0   fade_out_time:1.0 \
                             nloops:1
AUD_PLAY_MOVIE     track:1  file:"videofile" start_sec:0.0 end_sec:10.2 \
                             volume:1.0 
                             volume:1.0 \
                             start_vol:0.0 fade_in_time:1.0  \
                             end_vol:0.0   fade_out_time:1.0 \
                             nloops:1 \
                             1=selecttrack
AUD_SILENCE        track:1  duration_sec:0.0  wait_until_sec:10.2




RECORD Types Details:
---------------------

Here is the detailed description of the items for the
supported RECORD Types. optional items have internal defaults
and can be omitted.

  required item numbers (1)
  optional item numbers [7]
  

STORYBOARDFILE
  File Header. This Record mut be the 1.st Line in the file.

  (1) Record Key        ... STORYBOARDFILE
  (2) version           ... version string (1.0 for the current implementation)

VID_MASTER_FRAME_ASPECT
  Specifies the relation of width / height for playback of the resulting
  video output. This may result in automatic scaling to the specified
  aspect on playback.
  If nothing is specified, or one of the values width or height is 0,
  then playback will be done at the aspect derived from the original
  pixelsize.
  You can encode a video at 720 x 576 pixels, but specify aspect
  16:9
  Note: not all video encoders do support aspect settings.

  (1) Record Key        ... VID_MASTER_FRAME_ASPECT
  (2) width             ... the width aspect
                            (0: derive aspect from original pixelsize)
  (3) height            ... the height aspect
                            (0: derive aspect from original pixelsize)
  

VID_PREFERRED_DECODER
  (1) Record Key        ... VID_PREFERRED_DECODER
  (2) decoder           ... Name of the preferred Videodecoder
                            The Videodecoder is relevant for all Clips
			    specified with VID_PLAY_MOVIE or AUD_PLAY_MOVIE statements.
			    If you set a preferred Videodecoder this one tried first.
			    If it fails to open the videofile, all other decoders
			    are tried next.
                            Currently you may choose the following decoders:
			      libavformat
			      libmpeg3
                            DEFAULT: NULL (no preferred decoder)

VID_MASTER_LAYERSTACK   track1:[Top | Background]
  (1) Record Key        ... VID_PREFERRED_DECODER
  (2) track1            ... control order of videotracks in the layerstack
                            of the composite frame image.
                            If track1 is placed on Top of the layerstack
                            it appears in foreground. higher video track numbers
                            appears behind track1, and the highest video track
                            builds the background.
                            Background tracks are only visible when all other tracks
                            in the foreground have transparent areas,
                            or do not cover the full image size
                            (caused by ZOOM or MOVE operations)

                            You may choose the following options:
			      Top   ......... (track 1 is the foreground)
			      Background .... (track 1 is the background)
                            DEFAULT: Top 


VID_MASTER_INSERT_ALPHA
  Specifies a format string that refers to an image or to a series of frame images
  to provide transparency for the corresponding video frame.
  This format string shall contain placeholders
     %s    for the basename of videoclips and 
     %06d  for the 6 digit framenumber.
     
  This format string will be checked each time when storyboard processing
  fetches a video frame (from clip type VID_PLAY_MOVIE)
  and will be evaluated to a corresponding frame/image filename.
  If a frame image with this evaluated filename exists,
  that image will be automatically loaded,
  scaled to frame size and attached as alpha channel
  to the fetched frame.
  This feature offers individual transparency per video clip and frame.

  Example1:
    Have a Storyboard with:
      VID_MASTER_INSERT_ALPHA  format="/home/storyboards/video_alpha_frame/alpha_%s_%06d.png"
      VID_PLAY_MOVIE track=2 file=my_clip.AVI  from=12 to=20
    
    When processing fetches frame number 14 of my_clip.AVI
    it evaluates the alpha imagename by substitution
    where 
        %s    is replaced by "my_clip"
        %06d  is replaced by "000014"
    and checks if the resulting alpha imagename exists:
      
        /home/storyboards/video_alpha_frame/alpha_my_clip_000014.png
    
    If there is such an image it will be added as alpha channel
    to add transparency for the fetched video frame.

  Example2:
    Have a Storyboard with:
      VID_MASTER_INSERT_ALPHA  format="/home/storyboards/video_alpha_frame/alpha_%s.png"
      VID_PLAY_MOVIE track=2 file=my_clip.AVI  from=12 to=20
    
    In this case there is just the placeholder for the videofile but no
    placeholder for the framenumber.
    In this case the alpha imagename evaluates to

       /home/storyboards/video_alpha_frame/alpha_my_clip.png

    for all frames of this video clip. If such a file exists it
    is applied as alpha channel on all frames of my_clip.AVI
    


  (1) Record Key        ... VID_MASTER_INSERT_ALPHA
  (2) format            ... the format string
                            shall include 
                            %s     as placeholder for
                                   videofile basename and
                            %06d   as placeholder for the framenumber.
  


VID_PLAY_MOVIE
  fetch frames from a videofile. (such as MPEG, AVI, ...
  see GAP_VID_API description for Informations about 
  supported videoformats and codecs)


  (1) Record Key        ... VID_PLAY_MOVIE
  (2) track             ... integer tracknumer
  (3) file              ... filename of the video.
  (4) from              ... start of Range Framenumber (integer)  or seconds (float)
                            (where 1 is the first frame in the video)
  (5) to                ... end of Range Framenumber (integer) or seconds (float)
                            (see Range description for more information)
  [6] mode              ... optional keyword "pingpong" or "normal"
                            DEFAULT: "normal"
  [7] nloops            ... optional integer of Range repetitions
                            DEFAULT: 1
  [8] seltrack          ... Select input videotrack (for videos with more videotracks.
                            use 1 for the first track, or if the video has only one videotrack)
                            DEFAULT: 1
  [9] exactseek         ... 0 .. use faster videoindex based seek ops for Videoframe reads
                                 when available.
                            1 .. force sequential reads for exact positioning 
			         in the Video Read API (GVA) even if videoindex is available.
                                 In larger videos this will be very very slow.
                            DEFAULT: 0
 [10] deinterlace       ... 0.0 (up to 0.99)  read videoframes 1:1 without deinterlacing
                            1.0 up to 1.99  deinterlace videoframes keeping odd rows
                                where 1.0 does not interpolate the even rows (hard) 
                                and   1.99 does soft interpolation for the even rows.
                            2.0 up to 2.99    deinterlace videoframes keeping even rows
                            DEFAULT: 0.0
 [11] stepsize          ... 0.125 (up to 8.0) step size for fetching input frames
                            a value of 0.5 does fetch each input frame twice
			    a value of 2.0 does skip every 2.nd input frame
			    use a value of 1.0 to fetch all input frames step by step
                            DEFAULT: 1.0
 [12] macro             ... optional name of a filtermacro_file
                            that will be execute on each imported input_layer.
                            
                            If the macsteps parameter (see below) is set to a value
                            > 1 and the filtermacro_file has a pendant file that provides
                            alternative parameter sets, the filtermacro will be applied
                            with varying values until the number of defined
                            steps (parameter macsteps) is reached or all frames
                            of this clip are processed.
                            (for further details see also chapter about Macrofiles
                            below)
                 
 [13] decoder           ... optional name of preferred video decoder that should
                            be used for the videofile read access.
			    "libmpeg3"
			    "libavformat"
 [14] flip              ... h ... (Horizontal) mirror the input frames horizontally
                            v ... (Vertical) mirror the input frames vertically
			    b ... (Both) 
			    n ... (None) do not flip input frames.
                            DEFAULT: n (None)
 [15] mask_name         ... optional maskname refers to mask definitions.
                            the mask name is a unique identifier of
                            a mask clip that is applied to all frames of the clip.
                            mask definitions are mask clips that will be attached
                            as layermask to the input frames. This allows
                            modification of opacity for individual masked areas.
 [16] mask_anchor       ... Defines how to apply the layermask.
                            "clip" scale mask to resulting layer size.
                                   E.g. the mask scales and moves according
                                   to transformations of the input frame
                                   where it is attached to.
                                   (default)
                            "master" scale mask to master frame size and apply layer
                                   after clipping the layer to master frame image.
                                   In this mode the mask is fixed to the master frame.
                                   and does not follow transformations and movements
                                   of the input frame.
                            "xcolor" scale mask to resulting layer size.
                                   and apply as color mask.
                                   In this case the image that is referred via mask_name
                                   should be a color image.
                                   the mask scales and moves according
                                   to transformations of the input frame
                                   where it is attached to.
 [17] mask_stepsize:    ... stepsize factor for the mask-frames.
                            a value of 2.0 speeds up the mask effect (by skipping
                            every 2nd frame in the assigned mask clip)
                            a value of 0.5 will slow down the mask effect.
                            Default 1.0 (normal speed for mask effect)

 [18] mask_disable:     ... disable flag

 [19] macsteps:         ... an integer value greater or equal than 1.
                            Defines the (maximal) duration in number of frames
                            for applying filtermacros with varying values.
 [20] macaccel:         ... an integer value specifying acceleration characteristic
                            for applying filtermacros with varying values.
                            where 1 changes filtersettings with constant speed.
                            other positive values result in increasing speed, negative values
                            result in decreasing speed.

 [21] colormask_file:   ... a filename referring to a file with parameters for
                            applying a mask with the colormask filter.
                            the colormask filter makes pixels of the processed frame
                            transparent when they are equal or similar to the corresponding
                            pixel in the colormask.
                            typically the colormask represents the non-moving background
                            that can be set transparent while moving objects are opaque.




VID_PLAY_ANIMIMAGE
  fetch frames from layers of a multilayer image (such as GIF animations,
  or animations in GIMP native XCF fileformat)

  (1) Record Key        ... VID_PLAY_ANIMIMAGE
  (2) track             ... integer tracknumer
  (3) file              ... filename of the multilayer image.
  (4) from              ... start of range layernumber (integer)  or seconds (float)
                            (where 0 is the top layer in the multilayer image)
  (5) to                ... end of range layernumber (integer) or seconds (float)
                            (see range description for more information)
  [6] mode              ... optional keyword "pingpong" or "normal"
                            DEFAULT: "normal"
  [7] nloops            ... optional integer of Range repetitions
                            DEFAULT: 1
  [8] stepsize          ... 0.125 (up to 8.0) step size for fetching input frames
                            a value of 0.5 does fetch each input layer twice
			    a value of 2.0 does skip every 2.nd input layer
			    use a value of 1.0 to fetch all input layers step by step
                            DEFAULT: 1.0
  [9] macro             ... Same as described for VID_PLAY_MOVIE (see above)
 [10] flip              ... Same as described for VID_PLAY_MOVIE (see above)
 [11] mask_name         ... Same as described for VID_PLAY_MOVIE (see above)
 [12] mask_anchor       ... Same as described for VID_PLAY_MOVIE (see above)
 [13] mask_stepsize:    ... Same as described for VID_PLAY_MOVIE (see above)
 [14] mask_disable:     ... Same as described for VID_PLAY_MOVIE (see above)
 [15] macsteps:         ... Same as described for VID_PLAY_MOVIE (see above)
 [16] macaccel:         ... Same as described for VID_PLAY_MOVIE (see above)
 [17] colormask_file:   ... Same as described for VID_PLAY_MOVIE (see above)



VID_PLAY_FRAMES
  fetch frames from numbered imagefiles with names follow the convention
     - base_filename (may include directory path)
     - number
     - .
     - extension
  such as supported by GIMP Video Menu functions.

  
  (1) Record Key        ... VID_PLAY_FRAMES
  (2) track             ... integer tracknumer
  (3) base              ... filename prefix part before the framenumber.
  (4) ext               ... Extension (without '.'  jpg, gif xcf ...)
  (5) from              ... start of Range frame number (integer) or seconds (float) or keyword
  (6) to                ... end of Range frame number (integer) or seconds (float) or keyword
                            (see Range description for more information)
  [7] mode              ... optional keyword "pingpong" or "normal"
                            DEFAULT: "normal"
  [8] nloops            ... optional integer of Range repetitions
                            DEFAULT: 1
  [9] stepsize          ... 0.125 (up to 8.0) step size for fetching input frames
                            a value of 0.5 does fetch each input frame twice
			    a value of 2.0 does skip every 2.nd input frame
			    use a value of 1.0 to fetch all input frames step by step
                            DEFAULT: 1.0
 [10] macro             ... Same as described for VID_PLAY_MOVIE (see above)
 [11] flip              ... Same as described for VID_PLAY_MOVIE (see above)
 [12] mask_name         ... Same as described for VID_PLAY_MOVIE (see above)
 [13] mask_anchor       ... Same as described for VID_PLAY_MOVIE (see above)
 [14] mask_stepsize:    ... Same as described for VID_PLAY_MOVIE (see above)
 [15] mask_disable:     ... Same as described for VID_PLAY_MOVIE (see above)
 [16] macsteps:         ... Same as described for VID_PLAY_MOVIE (see above)
 [17] macaccel:         ... Same as described for VID_PLAY_MOVIE (see above)
 [18] colormask_file:   ... Same as described for VID_PLAY_MOVIE (see above)

VID_PLAY_IMAGE
  fetch frame from a single imagefile. (Multilayer Images are handled as
  one composite image. For animated GIF's you can use VID_PLAY_ANIMIMAGE
  to playback all the layers separately)
  
  (1) Record Key        ... VID_PLAY_IMAGE
  (2) track             ... integer tracknumber
  (3) file              ... filename of the image.
  [4] nloops            ... optional duration in number of frames (integer) or seconds (float)
                            DEFAULT: 1
  [5] macro             ... Same as described for VID_PLAY_MOVIE (see above)
  [6] flip              ... Same as described for VID_PLAY_MOVIE (see above)
  [7] mask_name         ... Same as described for VID_PLAY_MOVIE (see above)
  [8] mask_anchor       ... Same as described for VID_PLAY_MOVIE (see above)
  [9] mask_stepsize:    ... Same as described for VID_PLAY_MOVIE (see above)
 [10] mask_disable:     ... Same as described for VID_PLAY_MOVIE (see above)
 [11] macsteps:         ... Same as described for VID_PLAY_MOVIE (see above)
 [12] macaccel:         ... Same as described for VID_PLAY_MOVIE (see above)
 [13] colormask_file:   ... Same as described for VID_PLAY_MOVIE (see above)



VID_PLAY_COLOR
  create unicolored frame.
  
  (1) Record Key        ... VID_PLAY_COLOR
  (2) track             ... integer tracknumber
  (3) red               ... 0.0 up to 1.0 
  (4) green             ... 0.0 up to 1.0 
  (5) blue              ... 0.0 up to 1.0 
  (6) alpha             ... 0.0 up to 1.0  alphachannel 
                            (where 0.0 is full transparent and 1.0 is full opaque) 
  [7] nloops            ... duration in number of frames (integer) or seconds (float)
                            DEFAULT: 1
  [6] macro             ... Same as described for VID_PLAY_MOVIE (see above)
  [7] flip              ... Same as described for VID_PLAY_MOVIE (see above)
  [8] mask_name         ... Same as described for VID_PLAY_MOVIE (see above)
  [9] mask_anchor       ... Same as described for VID_PLAY_MOVIE (see above)
 [10] mask_stepsize:    ... Same as described for VID_PLAY_MOVIE (see above)
 [11] mask_disable:     ... Same as described for VID_PLAY_MOVIE (see above)
 [12] macsteps:         ... Same as described for VID_PLAY_MOVIE (see above)
 [13] macaccel:         ... Same as described for VID_PLAY_MOVIE (see above)
 [14] colormask_file:   ... Same as described for VID_PLAY_MOVIE (see above)

VID_SILENCE
  This record is used to define Pauses in a videotrack. 
  
  (1) Record Key        ... VID_SILENCE
  (2) track             ... integer tracknumber
  [3] nloops            ... duration of the silent pause in number of frames (integer) 
                            or seconds (float)
                            DEFAULT: 1
  [4] wait_until        ... wait until this timestamp is reached,
                            (then wait duration time)
                            timestamp can be a framenumber (integer) or seconds (float)
                            DEFAULT: 0

VID_ROTATE
  This record is used to define rotate transitions,
  by changing the rotation angle of the processed frames in the specified Videotrack slightly from one value
  to another.
  
  (1) Record Key        ... VID_ROTATE
  (2) track             ... integer tracknumber
  (3) rotate_from       ... Start rotation with this value
                            where 0.0 is and 360.0 is one full rotation
  [4] rotate_to         ... Change rotation to this value
                            DEFAULT: use same value as rotate_from
  [5] nframes           ... optional duration of the effect
                            in number of frames (integer) or seconds (float) 
                            The duration Value 0 applies the TO value immediate.
                            DEFAULT: 0
  [6] accel             ... an integer value specifying acceleration characteristic
                            for speed behavior of rotation changes.
                            where 1 (and 0) rotates the object with constant speed.
                            other positive values result in increasing rotation speed, negative values
                            result in decreasing speed.
                            DEFAULT: 0

VID_OPACITY
  This record is used to define Fade Effects,
  by changing the Opacity of the Videotrack slightly from one value
  to another.
  
  (1) Record Key        ... VID_OPACITY
  (2) track             ... integer tracknumber
  (3) opacity_from      ... Start opacity with this value
                            where 0.0 is full transparent and 1.0 is full opaque
  [4] opacity_to        ... Change opacity to this value
                            DEFAULT: use same value as opacity_from
  [5] nframes           ... optional duration of the effect
                            in number of frames (integer) or seconds (float) 
                            The duration Value 0 applies the TO value immediate.
                            DEFAULT: 0
  [6] accel             ... an integer value specifying acceleration characteristic
                            for speed behavior of opacity changes.
                            where 1 (and 0) changes opacity with constant speed.
                            other positive values result in increasing speed, negative values
                            result in decreasing speed.
                            DEFAULT: 0


VID_ZOOM_X and VID_ZOOM_Y
  These records are used to define Zooming Effects
  by scaling the Videotrack slightly from one value
  to another. Zooming can be defined independent for Width (VID_ZOOM_X)
  and Height (VID_ZOOM_Y).
  
  (1) Record Key        ... VID_ZOOM_X  (or VID_ZOOM_Y)
  (2) track             ... integer tracknumber
  (3) zoom_from         ... Start zoom with this value
                            where 0.0 is 1x1 Pixel, 1.0 is fit videosize, 2.0 is double videosize
  [4] zoom_to           ... Change zoom to this value
                            DEFAULT: use same value as zoom_from
  [5] nframes           ... optional duration of the effect 
                            in number of frames (integer 10) or seconds (float) 
                            The duration Value 0 applies the TO value immediate.
                            DEFAULT: 0
  [6] accel             ... an integer value specifying acceleration characteristic
                            for speed behavior of zoom changes.
                            where 1 (and 0) changes size with constant speed.
                            other positive values result in increasing speed, negative values
                            result in decreasing speed.
                            DEFAULT: 0


VID_MOVE_X and VID_MOVE_Y
  These records are used to define Scroll Effects
  by changing the Offset(s) of the Videotrack slightly from one value
  to another. Scrolling can be defined independent for X (VID_MOVE_X)
  and Y Directions (VID_MOVE_Y).
  
  (1) Record Key        ... VID_MOVE_X  (or VID_MOVE_Y)
  (2) track             ... integer tracknumber
  (3) move_x_from       ... Start move with this value
                            where -1.0 is left (or up) outside,
                                   0.0 is centered,
                                  +1.0 is right (or bottom) outside
  [4] move_x_to         ... Change offset to this value
                            DEFAULT: use same value as move_from
  [5] nframes           ... optional duration time of the effect 
                            in number of frames (integer 10) or seconds (float) 
                            The duration Value 0 applies the TO value immediate.
                            DEFAULT: 0
  [6] accel             ... an integer value specifying acceleration characteristic
                            for speed behavior of movements.
                            where 1 (and 0) changes positions with constant speed.
                            other positive values result in increasing speed, negative values
                            result in decreasing speed.
                            DEFAULT: 0

  Example:
    Assume we have video master size 320x200 pixels,
                			+-----------+
                			|master     |
                			|width: 320 |
                			|           |
                			+-----------+

    We use VID_ZOOM_X settings with a value of 2.0, 
    (also assume that automatic fit to master size is turned OFF
    using VID_FIT_SIZE  mode=none)
    
    The source is an image 400 x 200 that is scaled to 800 x 200
    (due to VID_ZOOM_X value of 2.0) that gives a tmp_width of 800 pixels.
    
    Without any VID_MOVE attributes the result will be centered The normal be

			    +-----------+===========+-----------+
			    |...........|...........|...........|
			    |...........|.....+.....|...........|
			    |...........|...........|...........|
			    +-----------+===========+-----------+
                                             320

                                        |<--------->|
					
					     800
                            |<--------------------------------->|


    We use VID_MOVE_X setting to place the image completely outside to the left border at the
    first handled frame,
    
    move_x_from = -1.0  
                                         
    +-----------------------------------+-----------+
    |.....tmp_width=800.................|master     |
    |.................+.................|width: 320 |
    |...................................|           |
    +-----------------------------------+-----------+
    ^                 ^   400           ^ 160 ^ 
    |         800     |<--------------->|<--->|
    |<--------------------------------->|



   
    the setting for the last handled frame places the image half outside the right border.
    move_x_to = 0.5 
       
                                  +-----+===========+-----------------+
                                  |.....|master.....|.................|
                                  |.....|width:.320.|.................|
                                  |.....|...........|.................|
                                  +-----+===========+-----------------+
                                  ^           ^     ^                 ^
                                  |           | 160 |     400         |
                                  |           |<--->|<--------------->|
                                  |<--------------------------------->|



VID_FIT_SIZE
  Define how to match input framesize with the target size.
  The target size is typically the size of the resulting video (VID_MASTER_SIZE).
  except in scenarios where a movepath transition is active.
  In this special case the input frame is processed as moving object
  of this transition and the target size refers to the scaled size 
  (preScaleWidth, preScaleHeight) of the recorded moving object.
  

  Notes:
  - The Input Frame is placed in the center of the 
    composite output frame.
    (unless VID_MOVE_X/Y define other offsets than 0.0)
  - Zooming may cause additional Scaling. The VID_FIT_SIZE record
    describes the normal Size (where zoom is set to 1.0)

  - In case the input Frame is processed by a movepath transition
    the target size depends on the size of the moving object and the framesize
    in the xml_paramfile and on the VID_MASTER_SIZE.
    (see VID_MOVE_PATH below)
        
    Example:
    in the xml_paramfile the frame size 640x400 pixels and the 
    moving object size was 320x240 pixels.
    
       <frame_description width="640" height="400"
       <moving_object     width="320" height="240" 

    The actual rendering shall be done at double frame size VID_MASTER_SIZE 1280 x 800 pixels.
    In this example the target size of the pre-scaled moving object is 640 x 480 pixels
    
    target size calculation:
       preScaleWidth  = recordedMovingObjWidth * masterWidth / recordedFrameWidth
           640        = 320  * 1280  / 640
       preScaleHeight = recordedMovingObjHeight * masterHeight / recordedFrameWidth
           480        = 240  * 800   / 400
    


  - WARNING: settings that disable scaling 
    (e.g. use fixed width or height at original source image size)
    do NOT follow changes of the resulting VID_MASTER_SIZE.
    In case you want to render videos in different sizes from the same storyboard
    by simply changing the VID_MASTER_SIZE sizes, you should NOT
    use such settings for your clips.
    
      VID_FIT_SIZE mode=none                                     # for fixed width and height
      VID_FIT_SIZE mode=width proportions=change_proportions     # fixed width
      VID_FIT_SIZE mode=height proportions=change_proportions    # fixed height
      
    Furthermore the fixed size also forces internal rendering for preview purpose
    to operate at full VID_MASTER_SIZE which may be very slow (especially for HD video)


  The described behavior is valid for all fetched Frames in the same track
  until the next VID_FIT_SIZE record (or until end of file if there is none)
  
  (1) Record Key        ... VID_FIT_SIZE
  (2) track             ... integer tracknumber
  [3] mode              ... One of the Keywords "width" "height" "none" or "both"
                            width:  Scale that only width does exactly
                                    fit to the resulting video,
                                    height is unchanged original input frame height,
                                    or adjusted to keep the proportions of the input frame
                                    (depends on the proportions setting)
                            height: Scale that only height does exactly
                                    fit to the resulting video,
                                    width  is unchanged original input frame width,
                                    or adjusted to keep the proportions of the input frame
                                    (depends on the proportions setting)
                            both:   Scale that both width and height do exactly
                                    fit to the resulting video 
                            none:   Do not Scale the input frame at all
                            DEFAULT "both"
                            
  [4] proportions           ... One of the Keywords "keep_proportions" "change_proportions"
                            keep_proportions:
                                    Keep proportions of the input frame at scaling.
                                    This can lead to stripes on top/bottom
                                    (or left/right).
                                    especially if the resulting video is LANDSCAPE oriented
                                    and the input frame is PORTRAIT oriented.
                                    The stripes are transparent and show the frames
                                    of lower video track numbers, or the black
                                    background if there no such frames.
                            change_proportions:
                                    allow proportion changes at scaling.
                                    
                            DEFAULT: "change_proportions"


   This Example shows how an Input Frame of size 400x400 pixel is automatically scaled
   to fit into a video at size 1280 x 800

       +------+
       |######|   Input Frame width:      400
       |######|   Input Frame height:     400
       |######|
       |######|
       +------+
 
 
  ==== scenarios that allow changing proportions of the moving object =====
 
  o) VID_FIT_SIZE mode=both proportions=change_proportions
 
    +-------------------------------------+
    |#####################################|  scaled copy of input frame:  1280 x 800
    |#####################################|  video size:                  1280 x 800                  
    |#####################################| 
    |#####################################|
    |#####################################|
    |#####################################|
    |#####################################|     
    |#####################################|
    |#####################################|
    |#####################################|
    |#####################################|
    |#####################################|
    +-------------------------------------+

  o) VID_FIT_SIZE mode=width proportions=change_proportions
 
    +-------------------------------------+
    |                                     |  scaled copy of input frame:  1280 x 400
    |                                     |  video size:                  1280 x 800                  
    |                                     | 
    +-------------------------------------+
    |#####################################|
    |#####################################|
    |#####################################|     
    |#####################################|
    +-------------------------------------+
    |                                     |
    |                                     |
    |                                     |
    +-------------------------------------+
 

  o) VID_FIT_SIZE mode=height proportions=change_proportions
 
    +--------------+------+---------------+
    |              |######|               |  scaled copy of input frame:   400 x 800
    |              |######|               |  video size:                  1280 x 800                  
    |              |######|               | 
    |              |######|               | 
    |              |######|               | 
    |              |######|               | 
    |              |######|               | 
    |              |######|               | 
    |              |######|               | 
    |              |######|               | 
    |              |######|               | 
    |              |######|               | 
    +--------------+------+---------------+

 
  ==== scenarios that keep proportions of the moving object =====
  
  o) VID_FIT_SIZE mode=both proportions=keep_proportions
  
     The input frame is scaled to fit into video size rectangle
     since the input frame has different proportions than the video size
     there will be transparent borders. (where the black background
     or clips of other tracks on lower stack position shows through)
 
    +-------+---------------------+-------+
    |       |#####################|       |  scaled copy of input frame:   800 x 800
    |       |#####################|       |  video size:                  1280 x 800                  
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    +-------+---------------------+-------+

 
  o) VID_FIT_SIZE mode=width proportions=keep_proportions
    
    The input frame is scaled to width 1280 pixels
    and height 1280 pixels to keep the proportions.
    But this cuts off the parts that do not fit into
    the video height of 800 pixels.
    


    +-------------------------------------+
    |.....................................| 
    |.....................................| 
    +-------------------------------------+
    |#####################################|  scaled copy of input frame:  1280 x 1280
    |#####################################|  video size:                  1280 x  800                  
    |#####################################| 
    |#####################################|
    |#####################################|
    |#####################################|
    |#####################################|     
    |#####################################|
    |#####################################|
    |#####################################|
    |#####################################|
    |#####################################|
    +-------------------------------------+
    |.....................................| 
    |.....................................| 
    +-------------------------------------+

  o) VID_FIT_SIZE mode=height proportions=keep_proportions

     The input frame is scaled to height 800 pixels.
     keeping the proportions of the input frame results in width of 800 pixels
     that gives transparent stripes left and right.
     
 
    +-------+---------------------+-------+
    |       |#####################|       |  scaled copy of input frame:   800 x 800
    |       |#####################|       |  video size:                  1280 x 800                  
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    |       |#####################|       | 
    +-------+---------------------+-------+



  o) VID_FIT_SIZE mode=none
   
    No automatic scaling is done to fit into video size.
    (the proportions setting is not relevant in this case)
 
    +-------------------------------------+
    |                                     |  scaled copy of input frame:   400 x 400
    |                                     |  video size:                  1280 x 800                  
    |                                     | 
    |              +------+               |
    |              |######|               |
    |              |######|               |
    |              |######|               |     
    |              |######|               |
    |              +------+               |
    |                                     |
    |                                     |
    |                                     |
    +-------------------------------------+
 

  





VID_OVERLAP
  Define overlapping frames within one track.
  The specified number of frames will overlap previous frames of the same track.


  (1) Record Key        ... VID_OVERLAP
  (2) track             ... integer tracknumber
  (3) nframes           ... Number of overlapping frames.

  The main use case is smooth blending from one scene to another.
  To achieve such effects, varying transparency must be set for the overlapping
  frames. This can be done either by modifying global opacity via VID_OPACITY
  instructions, or by assigning (layer)masks to the frames of the overlapping
  clips.

  Example: overlap specified with nframes:5.
  In this case the next 5 frames fetched from the
  following clip ("B.mpg" 1 up to 5) 
  in the same track 1 will not create a new frame in the resulting video,
  but will be placed as additional layer in the 5 previous frames.

  
  
  VID_PLAY_MOVIE track:1 file:"A.mpg" from:000001 to:000100
  VID_OVERLAP    track:1 nframes:5
  VID_OPACITY    track:1 opacity_from:0.0 opacity_to:1.0 nframes:5
  VID_PLAY_MOVIE track:1 file:"B.mpg" from:000001 to:000100
  
    
  FrameNr
  (Result)    |BG-Layer           
  --------    |------------------------------------> layer stack position (TOP)
  00001        A.mpg 000001
    ..
    
  00094        A.mpg 000094
  00095        A.mpg 000095              
  00096        A.mpg 000096  B.mpg 000001
  00097        A.mpg 000097  B.mpg 000002
  00098        A.mpg 000098  B.mpg 000003
  00099        A.mpg 000099  B.mpg 000004
  00100        A.mpg 000100  B.mpg 000005  
  00101        B.mpg 000006 
  00102        B.mpg 000007 
  ...
  00195        B.mpg 000100 


      
VID_MOVE_PATH
  This record is used to define a set of complex transformations on the current video track (layer)
  Those transformations can include movement along a path, scaling, rotation, perspective transformation,
  opacity changes ... (see the GIMP-GAP MovePath feature for more details)
  
  to another.
  
  (1) Record Key        ... VID_MOVE_PATH
  (2) track             ... integer tracknumber
  (3) frame_from        ... Start frame number specifies the phase
                            where to start in the move path (typically start at 1)
  (4) frame_to          ... End frame number  specifies the phase
                            where to end in the move path
  (5) nframes           ... duration of the effect
                            in number of frames (integer)
                            In case nframes is greater than total_frames
                            the transitions of the end
                            The duration Value 0 disables move transitions.
  (6) accel             ... an integer value specifying acceleration characteristic
                            DEFAULT: 0  ** other values are currently ignored 
                            
  (7) xml_paramfile     ... name of the parameterfile for the move path plugin.



AUD_PLAY_SOUND
  This record is used for playback of portions of an audiofile,
  with optional fade effects. Please note that all audiotracks
  are mixed to one composite audiotrack.

  (1) Record Key        ... AUD_PLAY_SOUND
  (2) track             ... integer tracknumber
  (3) file              ... filename of soundfile (.WAV and other types).
  (4) start_sec         ... start playback range at offest in seconds (float)
  (5) end_sec           ... end playback range at offest in seconds (float)
                            Alternative you can specify the time in frames
			    (see from and to parameters below)
  [6] volume            ... adjust the volume. (float)
                            A value of 1.0 keeps the original input volume for this track
                            value 0.5 results in half, value 2.0 in double volume.
                            (the result may be additional affected by the MASTER_VOLUME,
                            that is applied to the mixed composite audio)
                            DEFAULT = 1.0
  [7] start_volume      ... Start Value of the volume. (float)
                            DEFAULT: 1.0
  [8] fade_in_time      ... duration for the fade in. In this durationtime the input volume
                            changes slightly from start_volume --> to volume.
                            Duration can be specified in Seconds (float) or frames (int).
                            With value 0 the playback starts immediate with volume,
                            there will be no fade-in at all.
                            DEFAULT: 0
  [9] end_volume        ... End Value of the volume.. (float)
                            DEFAULT: 1.0
  [10]fade_out_time     ... duration for the fade out. In this durationtime the input volume
                            changes slightly from volume --> to end_volume.
                            Duration can be specified in Seconds (float) or frames (int).
                            With value 0 there will be no fade-out at all.
                            DEFAULT: 0
  [11] nloops           ... number of repeats
                            DEFAULT = 1
  [12] from             ... start playback range at offest in frames
  [13] to               ... end playback range at offest in frames
  [14] framerate        ... framerate that is used for transformation frames to seconds
                            (specify the original framerate of the video here
			     in case when it differs from the master framerate)
			    DEFAULT: the value specified by VID_MASTER_FRAMERATE
                            

AUD_PLAY_MOVIE
  This record is used for playback of portions of an audiotrack in an input videofile,
  with optional fade effects. Please note that all audiotracks
  are mixed to one composite audiotrack.

  (1) Record Key        ... AUD_PLAY_MOVIE
  (2) track             ... integer tracknumber
  (3) file              ... filename of a video (must contain the audiotrack).
  (4) start_sec         ... start playback range at offest in seconds (float)
  (5) end_sec           ... end playback range at offest in seconds (float)
  [6] volume            ... adjust the volume. (float)
                            A value of 1.0 keeps the original input volume for this track
                            value 0.5 results in half, value 2.0 in double volume.
                            (the result may be additional affected by the MASTER_VOLUME,
                            that is applied to the mixed composite audio)
                            DEFAULT = 1.0
  [7] start_volume      ... Start Value of the volume. (float)
                            DEFAULT: 1.0
  [8] fade_in_time      ... duration for the fade in. In this durationtime the input volume
                            changes slightly from start_volume --> to volume.
                            Duration can be specified in Seconds (float) or frames (int).
                            With value 0 the playback starts immediate with volume,
                            there will be no fade-in at all.
                            DEFAULT: 0
  [9] end_volume        ... End Value of the volume.. (float)
                            DEFAULT: 1.0
  [10]fade_out_time     ... duration for the fade out. In this durationtime the input volume
                            changes slightly from volume --> to end_volume.
                            Duration can be specified in Seconds (float) or frames (int).
                            With value 0 there will be no fade-out at all.
                            DEFAULT: 0
  [11] nloops           ... number of repeats
                            DEFAULT = 1
  [12] seltrack         ... Select input audiotrack (for videos with more audiotracks
                            such as multilingual DVDs.
                            use 1 for the first audiotrack, or if the video has only
                            one audiotrack)
                            DEFAULT: 1
  [13] decoder          ... optional name of preferred audio/video decoder that should
                            be used for the videofile read access.
			    "libmpeg3"
			    "libavformat"
                            

AUD_SILENCE
  This record is used to define Pauses in an audiotrack. 
  
  (1) Record Key        ... AUD_SILENCE
  (2) track             ... integer tracknumber
  [3] duration_sec      ... duration of the silent pause in seconds (float)
                            DEFAULT: 1
  [4] wait_until_sec    ... wait silently until this timestamp is reached,
                            (then do the unconditional pause for duration time)
                            timestamp in measured in seconds (float)
                            DEFAULT: 0

  Examples:
  
  a) play the the sound "hello.wav", 
     then wait silent until the total playtime has reached 60 secs.
     then start the sound "ringing.wav".
     if "hello.wav" is longer than 60 secs there will be no pause,
     (and a warning is reported)
  
  
  AUD_PLAY_SOUND track:1  hello.wav
  AUD_SILENCE    track:1  delay:0.0  wait_until_sec:60.0
  AUD_PLAY_SOUND track:1  ringing.wav
  
  b) play the sound "hello.wav", 
     then wait 4 seconds and start the sound "ringing.wav" exactly at sec. 60.0
  
  
  AUD_PLAY_SOUND track:1  hello.wav
  AUD_SILENCE    track:1  delay_sec:4.0  wait_until_sec:0.0
  AUD_PLAY_SOUND track:1  ringing.wav


Filenames:
----------
  Filenames can be prefixed by absolute pathnames,
  or by relative pathnames. Relative pathnames are relative
  to the location of the storyboard_file.

  Both / and \ are treated as directory Separator.


Videotracks:
------------
  The Videotracks in a Storyboard_file are Input tracks
  and will be merged internal to one composite Videotrack.

  The composite frame image for the output Videotrack is built
  as Layerstack, where each videotrack represents one Layer
  (except mask track 0 and tracks where the current frame is VID_SILENCE.
  in such cases no layer will be created in the composite frame image)

  The tracknumber of video tracks defines its position
  in the layerstack. Per default video track 1 is placed on
  top of the Layerstack.
   
  You can set VID_OPACITY to value 0.0 (or less than 1.0) to let
  other tracks shine through.

  If the Input Frame of a Video Track has an alpha channel,
  the layers below are visible at the transparent Regions
  of its alpha channel, even if VID_OPACITY is set to 1.0 (full opaque)
  If there is no layer below, black pixels are shown
  at full transparent regions.

  Notes:
   - Inverse order that places video tracknumber 1 in the background
     can be specified via VID_MASTER_LAYERSTACK
   - You can add a layermask to Input frames by using
     masks. (If the original frame already has an alpha channel
     only those pixels are visible that are enough opaque in both the mask
     and the original alpha channel)
   - video tracknumber 0 is reserved used for mask definitions.
     Clips with tracknumber 0 therefore are not placed
     as layers in the composite frame image.
     Those Mask clips can be referred in Video Clips (via mask_name)
     for adding a layermask to provide individual transparency areas.

Sections:
---------
  Storyboard files always have a main section, optionally indicated
  by the Record Key MAIN_SECTION and can have additional sub sections.

  For the output video rendering only the clips in the main section are processed.
  Sub sections are definitions of clip sequences that can be referred
  from the main section via VID_PLAY_SECTION as if the were a simple clip.
  
  Note that Clips in a SUB_SECTION not rendered in the output
  video if there is no reference via VID_PLAY_SECTION
  in the MAIN_SECTION.


  Both main section and sub sections can have multiple tracks.
  
  
  
  Example:
    creating a video with a complex intro scene built up
    
    SUB_SECTION section_name:"Intro"    (complex multitrack)
    SUB_SECTION section_name:"Finale"    (complex multitrack)
  




  A sub section starts with the Record Key SUB_SECTION.
  If there are no Records with Record Keys SUB_SECTION 
  or MAIN_SECTION all clips are implicitly placed in the main section.

  
  Mask definitions have global scope for all sections.

  audio tracks in SUB_SECTION are not supported,
  and will be ignored.

Framerange:
-----------
  A Framerange is the selected portion of Frames (or Layers).
  It is specified by two numbers, FROM and TO
  and the optional keywords {"pingpong" or "normal"}
  where both numbers are included in the Framerange.
  (example: from:3 to:6  results in playback 3,4,5,6)
  
  FROM and TO can be specified as integer numbers (10  ==> unit is frames or layers)

  If the FROM value is greater than the TO
  value, the Framerange is processed backwards.

  The "pingpong" mode extends the Framerange in the way that the frames
  are played in both directions.
  (example: from:1 to:4 pingpong results in playback 1,2,3,4,3,2)

  The repeatcount repeats the Framerange N times.
  (from:1 to:4 pingpong repeatcount:2 results in playback 1,2,3,4,3,2,  1,2,3,4,3,2)


Audiorange:
-----------
  A Audiorange is the selected portion of a soundfile (or audiotrack
  of a movie) that is to play.

  It can be specified by
    - two float numbers (1.0 = 1 second)


Macrofiles:
------------
  Macros can be used to perform a user defineable set of
  one or more gimp procedures (plug-ins), such as 
    - color correction
    - sharpen / blur
    - transformations
    - artistic effects
    -  ...... or whatever ..
  on the handled frames of an input framerange in a video track.
  The macro is performed before
  the frame is added to the composite frame.
  
  Apply Macrofiles with varying parameters:
  ----------------------------------------
  A single macrofile only allows applying an effect
  with constant settings to all processed frames.
  
  If an effect shall be applied with variable settings
  this can be done by using a 2nd macrofile that
  describes alternate parameter sets, and by defining
  the duration (e.g number of frames see macsteps parameter)
  that shall be used to vary the iterable parameters from the
  values defined in the 1st set to their final alternate value
  as defined in the 2nd macrofile.
  
  The 2nd macrofile is implicitly referenced by naming convention
  via the keyword .VARYING (as suffix or before the extension)
  
  example:
  VID_PLAY_MOVIE track:1 file:"/vol1/videos/A.mpg" from:000001 to:000500 \
              macro:"/vol1/fmac/my_blur_macro.fmac" \
              macsteps:200 \
              macaccel:10
              
  This example implicite refers to a second macrofile:
  
             "/vol1/fmac/my_blur_macro.VARYING.fmac"
  
  If such a file exists, it is used as provider of alternate
  parameter sets for correlating filtercalls.
  Filtercalls in the alternate (2nd) macrofile where filtername
  and occurrence count matches to filtername and occurrence count in 
  the first macrofile are correlating and will be used to build
  a mix of the iterable parameters.
  Processing for frame 000001 of the input video clip A.mpg 
  will apply the parameter values of the 1st macrofile.
  As processing continues, the influence of
  the values defined in the 2nd macrofile grows.
  At fame 000200 (macsteps:200) the final value, as defined in the 2nd macrofile
  is reached, and will be used for all further frames of this video clip too
  (201 up to 500).
  The speed of the change from settings in the 1st and the 2nd
  macrofile depends on the specified acceleration characteristic
  (macaccel:10) where 10 defines increasing speed.
  Use value 1 for constant speed (e.g linear changing settings)
  
  Filtercalls in the 2nd macrofile that have no correlating pendent
  in the 1st macrofile are ignored. Filtercalls of the 1st
  macrofile that have no pendent in the 2nd macrofile are executed
  with constant parameter values in all processed frames.

  example:
   *
   *   #  macrofile1:    len   filter parameter data      
   *   ---------------------------------------------
   *   1. plug_in_abc    3     00 01 02 
   *   2. plug_in_xy     2     00 00
   *   3. plug_in_abc    3     00 08 00 
   *   4. plug_in_xy     2     0A 0A
   *   5. plug_in_xy     2     02 02
   *   
   *   #  macrofile2:    len   filter parameter data      
   *   ---------------------------------------------
   *   1. plug_in_zzz    1     00
   *   2. plug_in_xy     2     00 20
   *   3. plug_in_xy     2     00 00
   *
   *   In this example the plug_in_zzz is ignored (because there is no correlating
   *   filtercall definition in macrofile1)
   *   macrofile2:line 2.) correlates with macrofile1:line 2.)
   *   macrofile2:line 3.) correlates with macrofile1:line 4.)

  RESTRICTION:
   - Applying filters (e.g plug-ins) with varying values is restricted
     to filters that provide the capability to access
     the filter specific parameter settings (typically stored as last values buffer in memory)
     by either implementing an iterator procedure or registering
     the structure of this last values buffer in the
     configuration file lastval_descriptions.txt
     
     This allows GIMP-GAP to handles the mix of filter specific parameter values.
     (see also Filter->Filter all Layers)
     
  
  
  Macrofiles for global usage:
  ---------------------------
  Another method allows performing of a macro with global scope
  (e.g. affecting all frames).
  This can be done by specifying the macro directly in the 
  "Master Encoder" dialog.
  In that case the macro is performed on the already
  flattened composite frames immediate before they are
  passed to the encoder engine.

  
  What are Macrofiles and how to create them ?
  --------------------------------------------
  GAP Filtermacro_files
       include a user defineable list of filtercalls,
       where each filtercall defines a set of filter specific parameters.
       
       You can Record any GIMP Filter Plug-In that works on a single
       drawable and is able to run with LAST VALUES in a
       filtermacro_file.
       (use the Menu  Filter->Filtermacro)
  
 
  NOTES:
   - gimp-gap filtermacro files are machine dependent,
     and GIMP / FILTER Version dependent.
     
     filtermacro support may be dropped in the future.


Supported video input
---------------------
  - libmpeg3 based MPEG1, MPEG2 (DVD) Video 
       libmpeg3 can read most videos from DVD.
       there is support for typical .vob and .ifo files
       and fast exact random access to the videoframes.
       (libmeg3 native tocfiles are used for access.
       GIMP-GAP API does create such tocfiles
       on demand when videoindex creation is done)
       
       See docs of libmpeg3 decoder for detailed list.

  - libavformat based MPEG1, MPEG2 (DVD), MPEG4 Video, AVI, WMV, Quicktime, ..
       libavformat can read many videofileformats and codecs
       but can not handle .ifo files.
       Exact random access is slower than libmpeg3,
       because it is handled in the GIMP-GAP API 
       (GIMP-GAP videoindex creation is handled 
        completely outside the library)
       
       See docs of ffmpeg decoder for detailed list of
       supported fileformats and codecs.



LIMITS:
-------
 - Video Tracknumbers are limited to integer numbers within 
   the range from 0 to 19.
 - Both / and \ are treated as directory Separator in filenames.
  
