STORYBOARD_FILES           2007.09.05:


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 Auidoformat if you
have installed an external converter tool.

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





Syntax:
-------
The STORYBOARD_FILE is organized in textlines with blank
seprated 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")



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

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

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

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

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

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

VID_SILENCE        track:1                                         nloops:1  wait_until_sec:0.0

# video attributes
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 automatical 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 specifiy 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 highst 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_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 viedeotracks.
                            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 (upto 0.99)  read videoframes 1:1 without deinterlacing
                            1.0 upto 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 upto 2.99    deinterlace videoframes keeping even rows
                            DEFAULT: 0.0
 [11] stepsize          ... 0.125 (upto 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 clippng 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.
 [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.
                            Default: 1





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 (upto 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)



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 (upto 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)

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 tracknumer
  (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)



VID_PLAY_COLOR
  create unicolored frame.
  
  (1) Record Key        ... VID_PLAY_COLOR
  (2) track             ... integer tracknumer
  (3) red               ... 0.0 upto 1.0 
  (4) green             ... 0.0 upto 1.0 
  (5) blue              ... 0.0 upto 1.0 
  (6) alpha             ... 0.0 upto 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)

VID_SILENCE
  This record is used to define Pauses in a videotrack. 
  
  (1) Record Key        ... VID_SILENCE
  (2) track             ... integer tracknumer
  [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_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 tracknumer
  (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

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 independet for Width (VID_ZOOM_X)
  and Height (VID_ZOOM_Y).
  
  (1) Record Key        ... VID_ZOOM_X  (or VID_ZOOM_Y)
  (2) track             ... integer tracknumer
  (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


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 independet for X (VID_MOVE_X)
  and Y Directions (VID_MOVE_Y).
  
  (1) Record Key        ... VID_MOVE_X  (or VID_MOVE_Y)
  (2) track             ... integer tracknumer
  (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

  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 automatical 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 size of
  the resulting video (VID_MASTER_SIZE).

  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
    describes the normal Size (where zoom is set to 1.0)


  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 tracknumer
  [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
                            height: Scale that only height does exactly
                                    fit to the resulting video, width  is unchanged
                            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.
                                    Stretch the image to fit the resulting
                                    video.
                                    
                            DEFAULT: "change_proportions"

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 tracknumer
  (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 upto 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 


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 tracknumer
  (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 tracknumer
  (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 tracknumer
  [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 loacation 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 euogh 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 refered 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 refered
  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 implicite 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, 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 implicite referenced by naming convetion
  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
              
  This example implicite referes 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 occurance count matches to filtername and occourance count in 
  the first macrofile are correlating and will be used to build
  a mix of the iterable parameters.
  Procesing 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 upto 500).
  
  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 2,nd 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 with varying values is restricted
     to filters that provide an iterator procedure
     that handles the mix of filter specific prameter values.
     (see also Filter->Filter all Layers)
     
  
  
  Macrofiles for global usage:
  ---------------------------
  Another methode 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 parmeters.
       
       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.
  
