[Kdenlive-devel] edit file format draft1

[Jason Wood]

On Sunday 05 May 2002 4:56 pm, Christian Berger wrote:
> Servus
>
> Well this is the first draft for the editing file:

Cool, I wasn't expecting it this quick :-) Did you get better quickly, or have 
you been working at it in bed? :-)

> Syntax:
>
>
> real:
>   normal real number with "." as a decimal point and no points or commas
> at the 1000 position
>
> param:
>   -<paramname> <param>
>   example: -startvalue 5
>
> params:
>    <param> <param...>
>   example: -startvalue 1 -stopvalue 4 -wrtlpfmpf "HAllo"
>
> commands: (can only appear outside of scenes)
>   <commandname> <params  >
>   example: open_input -name somefile -filename "file.avi" -speed 1.42
>
> connection:
>   <connectionname> <effect> <params>
>   examples: 3 mosaik -input 2
> 	    2 read somefile
>
> scene_start <params>
>   <connections>
> scene_stop
>
>
> Commands:
>  open_input			: Opens a file for input
>    Params:
>     	-file			: Internal name (no string)
>     	-filename 		: Filename of file on disk
> 	-speed			: factor of speed 1=normal >1 faster <1 slower
> 	-start			: start of file in milliseconds
>
>  open_output			: sets the file for output
>    Params:
> 	-filename		: filename
> 	-sizex			: width of image in pixels
> 	-sizey			: height of image in pixels
> 	-nativesize		: yes=keep frames in size of possible
> 				  no=scale all frames
> 	-type			: type of file (avi, mov, mpg, etc)
> 	-fps			: framerate
> 	-nativefps		: yes=keep original framerate
> 				  no=don't keep framerate
> 	-videocodec		: type of codec
> 	-nativevideocodec	: yes=keep native codec
> 				  no=recompress all contents
> 	-soundrate		: samplerate of sound
> 	-nativesoundrate	: yes/no
> 	-soundformat		: format of sound (8bit, 16bit, uLaw, etc)
> 	-nativesoundformat	: yes/no

I think that videocodec and soundcodec might be better off as seperate 
commands, which are then referenced by open_output. The reason for this is 
that different codecs will have different options. By seperating them out, we 
make the file a little cleaner.


>
>  seek				: seek to a certain position
> 	-file			: identifier of file opened
> 	-absolute		: seek to absolute position in ms
> 	-relative		: seek to relative position in ms

Although obvious, a note should be made that only -absolute OR -relative can 
exist in a single seek command, or an error should be thrown.


>
> Scene definition:
>  scene_start			: command to start a scene
>   Params:
> 	-duration		: duration of sceene
> 	-name			: name of scene
> 	-based_on		: name of scenes which this scene
> 				  is based on (usefull for clusters)
> 				  may apear multible times
>
>  Several lines with connections. The output reads from connection 0. All
> connections (which may contain effects) are only called once per frame
> in an order which makes sense. Scenes also are usually executed in
> order, but might be executed in parallel.

Am I correct from this that only one output may exist at once? That's fine, 
but a line should be added saying that if an attempt is made to open a second 
output, then the command will fail and an error will be thrown.

>  scene_stop  (no params)
>
> Colors:
>   #rrggbb (like in HTML) or
>   #aarrggbb (like in HTML, but with added transparency)

I think this as good a place as any to mention this point :

I think that any parameter which can be set between 0 and some maximum value 
should have that maximum value set to 1.0, and that scaling should occur 
within the cutter. This makes it easy to modify the resolution of the 
parameter at a later date, as well as simplfiying any scaling operations that 
may need to be performed on the value.

If we take color as an example, if we are using 24 bit color, then we simply 
multiply the rgb values by 255 (or 256, can't remember) to get the correct 
value. If we now choose to move to 16 bit color, we simply multiply by the 
new relevant scaling value instead.

Another important point is that if we are doing linear interpolation across 
these values, then we _need_ to work in floating point anyway to avoid 
rounding errors between scenes. I can explain this in detail if you don't 
understand why this is so, but it's a little lengthy so I'll refrain for the 
moment.

Anyway, color is one such value that should be set from 0-1, including fade 
(as you have already set from 0-1 below), other transitions and any other 
effect with a "maximum" value.

Because of all t his :-) I think color would be better represented as either :

		RGB( redvalue, greenvalue, bluevalue)
		RGBA( red, green, blue, alpha)
		ARBG( alpha, red, green, blue)
		-r redvalue, -g greenvalue, -b bluevalue -a alphavalue

The top three are better ways of representing color, as they would allow us to 
represent color using other colorspaces, for instance HSV.

>
> Connections:
>  in 				: simply pipes the input
>   Params:
> 	-file			: identifier of file
>
>  mosaik				: simple mosaic effect
>   Params:
> 	-input			: number of connection to read from
>
>  fade				: simple crossfade
>   Params:
> 	-input1			: connection from which to fade
> 	-input2			: connection to which to fade
> 	-start			: start value of fading (0-1)
> 	-stop 			: stop value of fading (0-1)
>
>  flatcolour			: simple colour
>   Params:
> 	-colour			: colour value
>
>  overlay			: overlays 2 signals
>   Params:
> 	-background		: background connection
> 	-foreground		: foreground connection
>
>  title				: generates title
>   Params:
> 	-text			: text to display
> 	-x			: position x
> 	-y 			: position y
> 	-colour			: colour
> 	-font			: font
> 	-height			: height
>
>
> Well that's it for a start

BTW, once we've discussed this and agreed on everything, I'll add a documents 
section to the web page and put it there.

Cheers,
Jason

-- 
Jason Wood
I knew I needed a break when I tried to close konqueror by typing <Esc>:q!