Service Documentation

Authors: Charles Yates <charles.yates@pandora.be>
         Dan Dennedy <dan@dennedy.org>
Last Revision: 2009-05-08


SERVICES
--------

	Services marked as "(Proprietary)" are not distributed with the LGPL
	version of mlt.

Producers
---------

	avformat

	    Description

	        ffmpeg libavformat based producer for video and audio.

	    Constructor Argument

	        'file' - a filename specification or URL in the form:
	                 [{protocol}|{format}]:{resource}[?{format-parameter}[&{format-parameter}...]]
	                 For example, video4linux:/dev/video1?width:320&height:240
	                 Note: on the bash command line, & must be escaped as '\&'.
	                 Also, note the use of ':' instead of '=' for parameters.
	                 Use 'ffmpeg -formats' to see a list of supported protocols 
	                 and formats.
	                 
	    Details
	    
	        Format parameters only appear to be useful with 'video4linux' or
	        'audio_device' formats. For 'video4linux' the parameters are
	        width, height, frame_rate, frame_rate_base, and standard (ntsc|pal).
	        For 'audio_device' the parameters are channels and sample_rate.

	    Initialisation Properties

	        int video_index - index of video stream to use (-1 is off)
	        int audio_index - index of audio stream to use (-1 is off)
	        int in - in point
	        int out - out point

	    Read Only Properties

	        string resource - file location
	        double source_fps - the framerate of the resource
	        double aspect_ratio - sample aspect ratio of the resource
	                            - this is determined on every frame read

	    Dependencies

	        ffmpeg

	    Known Bugs

	        Audio sync discrepancy with some content.
	        Not all libavformat supported formats are seekable.
	        Fails to play beyond first frame of video of sources with PTS not
	        starting at 0 (video4linux).

	loader

	    Description

	        A friendly giant that likes to rhyme and throw rocks

	    Constructor Argument

	        'file'    - a filename specification:
	                  [{mlt-service}:]{resource} | {mlt-service}
	                - can also be the name of a producer service that can
	                  accept the resource specified post construction.

	    Initialisation Properties

	        int in - in point
	        int out - out point
	        + all producer initialising properties

	    Read Only Properties

	        string resource - file location
	        + all producer read only properties

	    Details

	        This producer has two roles:

	        1. it handles the mappings of all file names to the other
	        producers;
	        2. it attaches normalising filters (rescale, resize and resample)
	        to the producers (when necessary).

	        This producer simplifies many aspects of use. Essentially, it
	        ensures that a consumer will receive images and audio precisely as
	        they request them. 

	    Dependencies

	        all.

	    Known Bugs

	        None.

	
	colour
	
	    Description
	    
	        A simple colour generator.
	        
	    Constructor Argument
	    
	        colour - A colour value is a hexadecimal representation of RGB plus
	                 alpha channel as 0xrrggbbaa.
	               - Also colours can be the words: white, black, red, green,
	                 or blue.
	               - The default colour is black.
	               
	    Initialisation Properties
	    
	        none
	        
	    Read Only Properties
	    
	        none
	        
	    Dependencies
	    
	        none
	        
	    Known Bugs
	    
	        none

	
	libdv

	    Description

	        libdv based decoder for video and audio.

	    Constructor Argument

	        'file'    - produce a/v from file

	    Initialisation Properties

	        int in - in point
	        int out - out point

	    Read Only Properties

	        string resource - file location
	        double fps - output frames per second
	        int length - duration of resource (in frames)
	        
	    Mutable Properties
	    
	        string quality - one of "best," "fast" or anything else chooses
	                         medium.

	    Dependencies

	        libdv.

	    Known Bugs

	        DVCPRO is incorrectly identified as 16:9 aspect ratio. You must use
	        libdv from CVS or a post 0.101 release. 

	mcdv (Proprietary)

	    Description

	        MainConcept based dv decoder for video and audio.

	    Constructor Argument

	        'file'    - produce a/v from file

	    Initialisation Properties

	        int in - in point
	        int out - out point

	    Read Only Properties

	        string resource - file location
	        double fps - output frames per second
	        int length - duration of resource (in frames)

	    Dependencies

	        MainConcept DV or DVCPRO SDK, libdv.
	        "dv_sdk" installed parallel to mlt.

	    Known Bugs

	        None

	mcmpeg (Proprietary)

	    Description

	        MainConcept based mpeg decoder for video and audio.

	    Constructor Argument

	        'file'    - produce a/v from file

	    Initialisation Properties

	        int in - in point
	        int out - out point

	    Read Only Properties

	        string resource - file location
	        double fps - output frames per second
	        double aspect_ratio - sample aspect ratio of video
	        int length - duration of resource (in frames)
	        
	    Dependencies

	        MainConcept MPEG SDK.
	        "mpeg_sdk_release" installed parallel to mlt.

	    Known Bugs

	        None.

	noise

	    Description

	        White noise producer

	    Constructor Argument

	        none

	    Initialisation Properties

	        int in - in point
	        int out - out point

	    Read Only Properties

	        string resource - file location
	        double fps - output frames per second
	        double aspect_ratio - sample aspect ratio of video
	        int length - duration of resource (in frames)
	        
	    Dependencies

	        none

	    Known Bugs

	        none

	pango

	    Description

	        A title generator that uses the Pango international text layout
	        and Freetype2 font renderer.

	    Constructor Argument

	        string file - a text file containing Pango markup, see:
	        http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
	                    - requires xml-like encoding special chars from: 
	                      <, >, &   -to-   &lt;, &gt;, &amp;
	                      
	    Details
	    
	        Supplying a filename with extension ".txt" causes the loader 
	        producer to load with pango. If the filename begins with "+" the 
	        pango producer interprets the filename as pango text. This is a
	        shortcut to embed titles in melt commands. For MLT XML, it is 
	        recommended that you embed the title text in the property value.
	        
	        Pango has builtin scaling. It will rescale the originally rendered
	        title to whatever the consumer requests. Therefore, it will lose
	        its aspect ratio if so requested, and it is up to the consumer to
	        request a proper width and height that maintains the image aspect.

	    Initialisation Properties

	        int in - in point
	        int out - out point

	    Mutable Properties

	        string markup - a string containing Pango markup see:
	        http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
	                      - requires xml-like encoding special chars from: 
	                        <, >, &   -to-   &lt;, &gt;, &amp;
	        string fgcolour - an RGBA colour specification of the text 
	                          (i.e. 0xrrggbbaa)
	        string bgcolour - an RGBA colour of the background rectangle
	        string align - paragraph alignment: left, centre, right
	                     - also, numbers 0, 1 and 2 can be used respectively.
	        int pad - the number of pixels to pad the background rectangle 
	                  beyond edges of text. default 0.
	        string markup - see constructor argument
	        string text - non-markup string in UTF-8 encoding (can contain 
	                      markup chars un-encoded)
	        string font - the default typeface to use when not using markup.
	                      default "Sans 48". FreeType2 renders at 72 dpi.
	        string encoding - the text encoding type of the input if not UTF-8.
	                        - see 'iconv --list' for a list of possible inputs.
			int weight - the weight of the font (default is 400)

	    Read Only Properties

	        string resource - the text/markup file or "pango" if no file.
	        int real_width - the original, unscaled width of the rendered title.
	        int real_height - the original, unscaled height of the title.
	        int width - the last requested scaled image width.
	        int height - the last requested scaled image height.

	    Dependencies

	        libpango-1.0, libpangoft2-1.0, libfreetype, libgdk_pixbuf-2.0, 
	        libglib-2.0, libgobject-2.0, libgmodule-2.0, libfontconfig.

	    Known Bugs

	        The foreground and background Pango markup span attributes are not
	        supported.
	        Word wrapping is not supported.

	pixbuf

	    Description

	        A still graphics to video generator using gdk-pixbuf

	    Constructor Argument

	        'file' - The name of a graphics file loadable by
	                 a gdk-pixbuf loader. see /usr/lib/gdk-pixbuf/loaders
	                 definitely png, jpeg, tiff, pnm, and xpm
	               - If "%" in filename, the filename is used with sprintf
	                 generate a filename from a counter for multi-file/flipbook 
	                 animation. The file sequence ends when numeric 
	                 discontinuity >100.
	               - If filename contains "/.all.", suffix with an extension to 
	                 load all pictures with matching extension from a directory.
	               - If filename contains the string "<svg", then pixbuf tries
	                 to load the filename as inline SVG XML, which is convenient
	                 for melt commands.
	                 
	    Details
	    
	        Pixbuf has builtin scaling. It will rescale the originally rendered
	        title to whatever the consumer requests. Therefore, it will lose
	        its aspect ratio if so requested, and it is up to the consumer to
	        request a proper width and height that maintains the image aspect.

	    Initialisation Properties

	        int in - in point
	        int out - out point
	        int begin  - when using an image sequence, this sets the starting
	                     number.

	    Mutable Properties

	        int ttl - how long (in frames) to repeat each picture in file 
	                  sequences. default is 25.

	    Read Only Properties

	        string resource - file location. See Constructor Argument above.
	        int real_width - the original, unscaled width of the rendered title.
	        int real_height - the original, unscaled height of the title.
	        int width - the last requested scaled image width.
	        int height - the last requested scaled image height.

	    Dependencies

	        libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0

	    Known Bugs

	        XXX: in/out settings are incorrectly handled.

	ppm
	
	    Description

	        Reads a stream of contiguous PPM images.
	        
	    Constructor Argument

	        command - a shell command to run something that produces ppm
	                  streams on stdout.
	        
	    Initialisation Properties

	        none
	        
	    Read Only Properties

	        string resource - the command
	        
	    Dependencies

	        none
	        
	    Known Bugs

	        Since it uses pipes, it is not compatible with bluefish.

	xml

	    Description

	        Construct a service network from an XML description.
	        See docs/mlt-xml.txt.

	    Constructor Argument

	        URL - an XML text file containing MLT XML
	            - Since MLT XML files can be parameterised, the URL syntax is:
	              {file-name}[?{param-name}{'='|':'}{param-value}[&{param-name}{'='|':'}{param-value}...]]
	              A colon is allowed instead of an equal sign to pacify melt,
	              who tokenises anything with an equal sign as a property 
	              setting. Also, when running melt from the shell, beware of
	              the '?' and shell filename expansion. You can surround the URL
	              with single quotations to prevent expansion. Finally, the loader
	              will fail to match the filename when you use parameters, so
	              preface the url with 'xml:' to force the loader to load with
	              the xml service.
	              
	    Read Only Properties

	        string resource - file location

	    Dependencies

	        libxml2

	    Known Bugs

	        Non-referenced producers and playlists are not destroyed until the 
	        network is destroyed.
	        A referenced producer or playlist must appear before the reference.
	        A filter that occurs before a producer has been defined causes a 
	        segfault.

	vorbis

	    Description

	        OGG Vorbis file reader.

	    Constructor Argument

	        'file' - file to use (only .ogg supported at the moment)

	    Initialisation Properties

	        int in - in point
	        int out - out point

	    Read Only Properties

	        double fps - this is fixed at 25 for PAL currently

	    Dependencies

	        libvorbisfile

	    Known Bugs

	        Fixed frame size (PAL audio chunks).
	        Doesn't cover ogg files with multiple, differing sections.

Filters
-------

	brightness
	
	    Description
	    
	        Shift the luma component using a constant value.
	        
	    Constructor Argument
	    
	        start - the constant floating point numeric value to apply.
	              - the default is 0.
	        
	    Initialisation Properties
	    
	        int in - in point
	        int out - out point
	        double start - see Constructor Argument above.
	        double end - the ending adjustment value. the filter interpolates
	                     between the start and end adjustments over the 
	                     duration of the effect.
	                     
	    Read Only Properties
	    
	        none
	        
	    Dependencies
	    
	        none
	        
	    Known Bugs
	    
	        Does not go completely to black or white.
	        
	
	channelcopy
	
	    Description
	    
	        Copy audio from one channel to another channel.
	        
	    Constructor Argument
	    
	        to - the 0-indexed channel to copy into, default is 1.
	        
	    Mutable Properties
	    
	        int to - see above
	        int from - the channel from which to copy, default is 0.
	        
	    Dependencies
	    
	        none
	        
	    Known Bugs
	    
	        none
	        


	deinterlace
	
	    Description

	        Deinterlace a frame consisting of two fields using bob, weave,
	        greedy, one-field, and linear blend methods. This code is 
	        appropriated from the Xine XV video output plugin.
	    
	    Constructor Argument

	        method - a string containing the deinterlace method: bob, weave,
	                 greedy, onefield, or linearblend. The default is
	                 linearblend.
	    
	    Initialisation Properties

	        int in - in point
	        int out - out point
	        
	    Read Only Properties

	        none
	    
	    Mutable Properties
	    
	        string method
	        
	    Details
	    
	        If the frame properties "progressive" or "consumer_progressive"
	        are non-zero, then the filter is not applied. Also, if applied,
	        this sets the frame property "progressive" to 1.

	    Dependencies

	        none
	        
	    Known Bugs

	        Not a bug, but it only provides fair quality.
	        
	    
	gamma
	
	    Description

	        Adjust image luma using a non-linear power-law curve
	        
	    Constructor Argument

	        gamma - a floating point value. The default is 1.0, or none.
	    
	    Initialisation Properties
	    
	        int in - in point
	        int out - out point

	    Mutable Properties

	        double gamma - the exponential factor of the power-law curve
	        
	    Dependencies

	        none
	        
	    Known Bugs

	        none
	        
	
	greyscale
	
	    Description

	        Convert colour image to greyscale
	        
	    Constructor Argument

	        none
	        
	    Initialisation Properties
	    
	        int in - in point
	        int out - out point

	    Read Only Properties

	        none
	        
	    Dependencies

	        none
	        
	    Known Bugs

	        none
	    
	gtkrescale

	    Description

	        Scale the producer video frame size to match the consumer.
	        This filter is designed for use as a normaliser for the loader producer.

	    Constructor Argument

	        interpolation - the rescaling method, one of:
	            nearest (lowest quality, fastest),
	            tiles,
	            bilinear (default; good quality, moderate speed),
	            hyper (best quality, slowest).

	    Initialisation Properties

	        int in - in point
	        int out - out point

	    Mutable Properties

	        string interpolation - see constructor argument above

	        If a property "consumer_aspect_ratio" exists on the frame, then
	        rescaler normalises the producer's aspect ratio and maximises the
	        size of the frame, but may not produce the consumer's requested
	        dimension. Therefore, this option works best in conjunction with the
	        resize filter. This behavior can be disabled by another service by
	        either removing the property, setting it to zero, or setting
	        frame property "distort" to 1.

	    Dependencies

	        libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0

	    Known Bugs

	        none

	jackrack
	
	    Description
	    
	        Creates Jack ports and runs a JackRack project to process audio
			through a stack of LADSPA filters.
	        
	    Constructor Argument
	    
	        src - a JackRack file
			
		Details
		
			If you are using a consumer that uses ALSA, then you should start
			jackd with the dummy driver: jackd -d dummy.
			I also recommend using a period size of 2048: -p 2048.
			
			jackd -ddummy -r48000 -p2048
	        
	    Initialisation Properties
	    
	        int in - in point
	        int out - out point
			
			The following can be used without a rack file in order to connect
			filter_jackrack to a running instance of JackRack:
			string out_1 - Jack port to connect MLT's output port (JackRack's input)
			string out_2 - Jack port to connect MLT's output port (JackRack's input)
			string in_1 - Jack port to connect MLT's input port (JackRack's output)
			string in_2 - Jack port to connect MLT's input port (JackRack's output)
	        
	    Read Only Properties
	    
	        none
	        
	    Mutable Properties

			none
	        
	    Dependencies
	    
	        Jack, LADSPA, glib-2.0, libxml2
	        
	    Known Bugs
	    
			Currently, due to timing and synchronisation issues, the audio
			is distorted with repeated samples and latency clicks.
	        no encapsulated resampling and jack runs at a fixed frequency
	    
	ladspa
	
	    Description
	    
	        Runs a JackRack project to process audio through a stack of
			LADSPA filters without using Jack.
	        
	    Constructor Argument
	    
	        src - a JackRack file
			
		Details

			Due to audio integrity issues with the jackrack filter, this
			filter is better for runtime, while jackrack is more suitable
			for prototyping a rack file using the Jack Rack GUI.
		
	    Initialisation Properties
	    
	        int in - in point
	        int out - out point
			
	    Read Only Properties
	    
	        none
	        
	    Mutable Properties

			none
	        
	    Dependencies
	    
	        Jack, LADSPA, glib-2.0, libxml2
			Jack is still required because this coexists with the jackrack 
			filter.
	        
	    Known Bugs
	    
	        no encapsulated resampling and jack runs at a fixed frequency
	    
	luma
	
	    Description
	    
	        Applies a luma transition between the current and next frames.
	        Useful for transitions from a slideshow created using producer
	        pixbuf.
	        
	    Constructor Argument
	    
	        file - a luma wipe
	        
	    Initialisation Properties
	    
	        int in - in point
	        int out - out point
	        
	    Read Only Properties
	    
	        none
	        
	    Mutable Properties
	    
	        int period - how long to wait between success iterations of the
	                     transition. For best results set this to a multiple
	                     of ttl used in pixbuf. The default is 24.
	                     
	        luma. - all properties beginning with "luma." are passed to the
	                encapsulated luma transition. For example, luma.out controls
	                the duration of the wipe.
	        
	    Dependencies
	    
	        transition_luma and its dependencies
	        
	    Known Bugs
	    
	        none
	    
	mcrescale

	    Description

	        Scale the producer video frame size to match the consumer.
	        This filter is designed for use as a normaliser for the loader producer.

	    Constructor Argument

	        interpolation - the rescaling method, one of:
	            nearest (lowest quality, fastest),
	            bilinear (default; good quality, moderate speed),
	            hyper (best quality, slowest).

	    Initialisation Properties

	        int in - in point
	        int out - out point

	    Mutable Properties

	        string interpolation - see constructor argument above

	        If a property "consumer_aspect_ratio" exists on the frame, then
	        rescaler normalises the producer's aspect ratio and maximises the
	        size of the frame, but may not produce the consumer's requested
	        dimension. Therefore, this option works best in conjunction with the
	        resize filter. This behavior can be disabled by another service by
	        either removing the property, setting it to zero, or setting
	        frame property "distort" to 1.

	    Dependencies

	        the mainconcept rescaling sdk.

	    Known Bugs

	        none
	
	mirror
	
	    Description
	    
	        Provides various mirror and image reversing effects.

	    Constructor Argument
	    
	        mirror - horizontal, vertical, diagonal, flip, flop
	        
	    Initialisation Properties
	    
	        int reverse - being 0 or 1
	        int in - in point
	        int out - out point
	        
	    Read Only Properties
	    
	        none
	        
	    Mutable Properties
	    
	        none

	    Dependencies
	    
	        none
	        
	    Known Bugs
	    
	        none


	mono
	
	    Description
	    
	        Mix all channels of audio into a mono signal and output it as
			N channels.

	    Constructor Argument
	    
	        channels - the number of output channels (default 2)
	        
	    Initialisation Properties
	    
	        none
	        
	    Read Only Properties
	    
	        none
	        
	    Mutable Properties
	    
	        none

	    Dependencies
	    
	        none
	        
	    Known Bugs
	    
	        none


	obscure
	
	    Description

	        Obscuring filter.
	        
	    Constructor Argument

	        none
	        
	    Initialisation Properties
	    
	        string start - in the format X,Y:WxH[:PWxPY]
	                     - PWxPY is the size of the averaging region in pixels.
	        string end - in the format X,Y:WxH[:PWxPY]
	        int in - in point
	        int out - out point

	    Read Only Properties

	        none
	        
	    Dependencies

	        none

	    Known Bugs

	        none

	region
	
	    Description
	    
	        Apply one or more filters to a region of the video image. The region
	        can be shaped as well using the alpha channel of another producer.
	        
	    Constructor Argument
	    
	        resource - A file whose alpha channel will "shape"  the region.
	             - The string "circle" is a shortcut but it requires pixbuf with
	               the librsvg loader. The circle is automatically stretched
	               to the region to create an ellipse.
	
	    Initialisation Properties

	        int in - in point
	        int out - out point
	        plus and region transition properties
	        
	    Read Only Properties
	    
	        see the region transition
	        
	    Dependencies
	    
	        transition_region
	        
	    Known Bugs
	    
	        "circle" is unpredictable in the absence of the librsvg pixbuf loader.
	        

	resample

	    Description

	        Adjust an audio stream's sampling rate, and duplicate channels if 
	        producer provides less than consumer requested.
	        
	        This filter is automatically invoked by the loader producer for the
	        sake of normalisation over inputs and with the consumer.

	    Constructor Argument

	        frequency - a numeric value for the new sample rate

	    Initialisation Properties

	        int in - in point
	        int out - out point

	    Mutable Properties

	        int frequency - the target sample rate

	    Dependencies

	        libresample

	    Known Bugs

	        Assumes 2 channels during libsamplerate initialisation. Untested
	        with >2 channels.

	rescale

	    Description

	        Scale the producer video frame size to match the consumer.
	        This filter is designed for use as a normaliser for the loader producer.

	    Constructor Argument

	        None.

	    Initialisation Properties

	        int in - in point
	        int out - out point

	    Mutable Properties

	        If a property "consumer_aspect_ratio" exists on the frame, then
	        rescaler normalises the producer's aspect ratio and maximises the
	        size of the frame, but may not produce the consumer's requested
	        dimension. Therefore, this option works best in conjunction with the
	        resize filter. This behavior can be disabled by another service by
	        either removing the property, setting it to zero, or setting
	        frame property "distort" to 1.

	    Dependencies

	        none

	    Known Bugs

	        none but... it only implements a nearest neighbour scaling - it is
			used as the base class for the gtkrescale and mcrescale filters.

	resize
	
	    Description

	        Image scaling and padding and field order adjustment.
	            
	    Details
	    
	        Normally resize is used to pad the producer's
	        output to what the consumer has requested after an upstream rescale
	        filter first scales the image to maximise usage of the image area.
	        This filter also adjusts the field order to lower field first
	        if the frame property "top_field_first" has been set to 1.
	        Therefore, when done, it sets the top_field_first to 0.
	        This filter is automatically invoked by the loader as part of image
	        sample aspect ratio normalisation.
	        
	    Constructor Argument

	        scale - "affine" to use affine transform scaling, otherwise
	                 center and pad.
	        
	    Initialisation Properties
	    
	        int in - in point
	        int out - out point

	    Read Only Properties

	        none
	        
	    Dependencies

	        none
	        
	    Known Bugs

	        Assumes lower field first output.

	volume

	    Description

	        Adjust an audio stream's volume level 
				- based on the 'normalize' utility
	        
	    Constructor Argument

	        gain - a string containing one of:
	             - a floating point value of the gain adjustment
	             - a numeric value with the suffix "dB" to adjust in terms of decibels
	             - "normalise" to normalise the volume to the target amplitude -12dBFS
	        
	    Initialisation Properties
	    
	        int in - in point
	        int out - out point
	        int window - the number of video frames over which to smooth normalisation.
	                     defaults to 75.

	    Mutable Properties

	        string gain - same as constructor argument above

	        string normalise - normalise the volume to the amplitude:
	            - a numeric value with the suffix "dB" to set amplitude in decibels
	            - a floating point value of the relative volume
	            - an unspecified value uses the default -12dBFS

	        string limiter - limit all samples above:
	            - a numeric value with the suffix "dB"
	            - a floating point value ( dB = 20 * log10(x) )
	            - an unspecified value uses the default -6dBFS

	        double max_gain - a floating point or decibel value of the maximum gain that
	            can be applied during normalisation.
	            - an unspecified value uses the default 20dB

	        string end - a gain value just like the gain property above.
	                     This causes the gain to be interpolated from 'gain' to 'end'
	                     over the duration.

	        int window - the size of the normalising smoothing buffer in video frame units.
	                   - the smoothing buffer prevents erratic gain changes.
	                   - the default value is 75 video frames. 

	        gain can be applied as a factor to the normalise amplitude!
	        
	    Dependencies

	        none
	        
	    Known Bugs

	        none

	watermark

	    Description

	        Add a watermark to the frames.

	    Constructor Argument

	        resource - the producer to use (ie: a .png)

	    Initialisation Properties

	        string resource - the producer to use
	        string factory - producer required for the resource (default: 'loader')
	        string geometry - composite geometry
	        string distort - control scaling
	        int in - in point
	        int out - out point

	    Mutable Properties

	        none

	    Dependencies

	        mlt core modules and optionally, loader

	    Known Bugs

	        none

Transitions
-----------

	composite
	
	    Description

	        A key-framable alpha-channel compositor for two frames.
	        
	    Details
	    
	        Performs dissolves and luma wipes in addition to alpha compositing.
	        
	        By default, the aspect ratio of the B frame is respected and the
	        size portion of the geometry specification simply defines a 
	        bounding rectangle.
	    
	        This performs field-based rendering unless the A frame property
	        "progressive" or "consumer_progressive" or the transition property
	        "progressive" is set to 1.
	        
	    Constructor Argument

			none[*]

	    Initialisation Properties
	        
	        int in - in point
	        int out - out point
	        string factory - The name of a factory service used as a non-PGM
	                         producer loader. The default is 'loader'.
	
	    Read Only Properties

	        none

	    Mutable Properties


			string geometry - key frame specification
							- this is a ; delimited form of the deprecated start,
							  key[n], end properties
	        int progressive - set to 1 to disable field-based rendering.
	        string distort - when set, causes the B frame image to fill the WxH
	                         completely with no regard to B's aspect ratio.
	        string halign - when not distorting, set the horizontal alignment
	                        of B within the geometry rectangle.
	                      - one of: left (0), centre (1), or right (2).
	                      - the default is left.
	        string valign - when not distorting, set the vertical alignment of 
	                        B within the geometry rectangle.
	                      - one of: top (0), middle (1), or bottom (2).
	                      - the default is top.
	        string luma - the luma map file name. If not supplied, a dissolve.
	        double softness - only when using a luma map, how soft to make the
	                          edges between A and B. 0.0 = no softness. 1.0 =
	                          too soft.
	        Any property starting with "luma." is passed to the non-PGM luma
	            producer.

		Deprecated Properties

	        string start - a geometry specification as X,Y:WxH[!][:mix]
	                     - X, Y, W, H are assumed to pixel units unless they
	                       have the suffix '%'
	                     - '!' is a shortcut to specify distort, see below.
	                     - mix is always a 2 digit percentage, defaults to 100.
	                     - default is "85%,5%:10%x10%"
	        string end - the ending size and position.
	        string key[F] - X,Y:WxH[:mix] - set a key frame for geometry between
	                        the in and out. F is a frame number and can be
	                        negative to make it relative to the out point.

	    Dependencies

	        none
	    
	    Known Bugs

	        Assumes lower field first during field rendering.

	luma
	
	    Description

	        A generic dissolve and wipe transition processor.

	    Details

	        luma gets its name
	        from how it uses a grayscale "map" file. As the luma value varies
	        over time, a threshold filter is applied to the map to determine
	        what parts of frame A vs. frame B to show. It reads PGM files
	        up to 16 bits! Alternatively, it can use the first frame from any
	        producer that outputs yuv, but it will be limited to the luma
	        gamut of 220 values.
	        This performs field-based rendering unless the A frame property
	        "progressive" or "consumer_progressive" or the transition property
	        "progressive" is set to 1.
	    
	    Constructor Argument

	        string resource - the luma map file name - either PGM or any other
	                          producable video. 
	                        - If not supplied, a dissolve.

	    Initialisation Properties
	    
	        int in - in point
	        int out - out point
	        string factory - The name of a factory service used as a non-PGM
	                         producer loader. The default is 'loader'.

	    Mutable Properties

	        string resource - same as above
	        double softness - only when using a luma map, how soft to make the
	                          edges between A and B. 0.0 = no softness. 1.0 =
	                          too soft.
	        int reverse - reverse the direction of the transition.
	        Any property starting with "producer." is passed to the non-PGM luma
	            producer.
	        
	    Read Only Properties

	        none
	        
	    Dependencies

	        none
	        
	    Known Bugs
	        
	        Assumes lower field first output.

	mix

	    Description

	        An two stream audio mixer.

	    Constructor Argument

	        start - see below

	    Initalisation Properties

	        int in - in point
	        int out - out point

	    Mutable Properties

	        double start - the mix level to apply to the second frame.
	                     - any negative value causes an automatic crossfade from 0 to 1.
	        double end - the ending value of the mix level. mix level will be interpolated
	                     from start to end over the in-out range.
	        int reverse - set to 1 to reverse the direction of the mix.

	    Read Only Properties

	        none

	    Dependencies

	        none

	    Known Bugs

	        Samples from the longer of the two frames are discarded.
	        
	
	region
	
	    Description
	    
	        Apply zero or more filters to B frame as it is composited onto
	        a region of the A frame. The "shape" of the region can be defined
	        by the alpha channel of a third producer.
	        
	    Constructor Argument

	        resource - a shape producer
	    
	    Initialisation Properties
	    
	        string resource - nothing is rectangle, "circle" is a pixbuf-
	            generated SVG circle, anything else is loaded by the factory.
	        string factory - the service that creates the shape producer.
	                       - the default is 'loader'.
	        string filter[N] - one or more filters to apply. All filter
	                           properties are passed using the same filter "key"
	        Any property starting with "composite." is passed to the 
	            encapsulated composite transition.
	        
	    Read Only Properties
	    
	        none
	        
	    Dependencies
	    
	        transition_composite
	        
	    Known Bugs
	    
	        none
	        

Consumers
---------

	avformat
	
	    Description
	    
	        Multiformat transcoding consumer.

	    Constructor Argument

	        string target - the filename to write to, e.g. test.mpeg.

	    Initialisation Properties
	    
	        int buffer - the number of frames to buffer, minimum 1, default 25.
	        string rescale - a rescale method, see the Filters/rescale.
	        int progressive - indicates whether to use progressive or field-
	                          based rendering, default 0 (off).
	        
	    Read Only Properties
	    
	        none
	        
	    Dependencies
	    
	        libavformat
	        
	    Known Bugs
	    
	        Plenty.

	bluefish (Proprietary)
	
	    Description

	        BlueFish444 audio and video output module.
	    
	    Constructor Argument

	        card - a numeric card id starting at 1, default is 1.
	        
	    Initialisation Properties

	        string standard - "PAL" (default) or "NTSC"
	                        - default is based upon MLT_NORMALISATION 
	                          environment variable, which defaults to PAL.
	        int frames - the number of DMA video frames. default is 8.
	                     minimum is 2. maximum on my system is 11.
	        int buffer - the number of frames to buffer within MLT, minimum 1, 
	                     default 25.
	        string rescale - a rescale method, see the Filters/rescale.
	        
	    Read Only Properties

	        none
	    
	    Dependencies

	        BlueVelvet SDK installed parallel to mlt in "bluefish."
	    
	    Known Bugs

	        Does not work with any service that uses pipes!
	        
	        If mlt crashes, you might need to reload the BlueDriver kernel 
	        module due to unreleased DMA buffers.
	        
	        Only supports 2 channel audio at the moment.
	    
	libdv
	
	    Description
	    
	        libdv dv producer.

	    Constructor Argument

	        string target - the filename to write to, e.g. /dev/dv1394.

	    Initialisation Properties
	    
	        int buffer - the number of frames to buffer, minimum 1, default 25.
	        string rescale - a rescale method, see the Filters/rescale.
	    
	    Mutable Properties
	    
	        int progressive - indicates whether to use progressive or field-
	                          based rendering, default 0 (off).
	        
	    Read Only Properties
	    
	        none
	        
	    Dependencies
	    
	        libdv
	        
	    Known Bugs
	    
	        none

	mcmpeg
	
	    Description
	    
	        Mainconcept MPEG encoder.

	    Constructor Argument

	        string target - the filename to write to.

	    Initialisation Properties
	    
	        int buffer - the number of frames to buffer, minimum 1, default 25.
	        string rescale - a rescale method, see the Filters/rescale.
	        string format - vcd [default], svcd or dvd provide base settings
	        int motion_search_type - 0 to 16 - reduces quality/cpu usage
	        int gop - group of picture size (default: format dependent)

	    Mutable Properties
	    
	        int progressive - indicates whether to use progressive or field-
	                          based rendering, default 0 (off).
	        
	    Read Only Properties
	    
	        none
	        
	    Dependencies
	    
	        Mainconcept MPEG SDK
	        
	    Known Bugs
	    
	        none

	sdl

	    Description

	        Simple DirectMedia Layer audio and video output module.
	        
	    Constructor Argument

	        string video_standard - "PAL" (default), "NTSC", or "WxH"
	        
	    Initialisation Properties
	    
	        int buffer - the number of frames to buffer, minimum 1, default 25.
	        string rescale - a rescale method, see the Filters/rescale.
	                       - Hint: "none" works very good with SDL output.
	        
	    Mutable Properties

	        double volume - audio level factor
	        int video_off - if 1, disable video output
	        int audio_off - if 1, disable audio output
			int resize - TODO
	        int progressive - indicates whether to use progressive or field-
	                          based rendering, default 0 (off).
		int audio_buffer - size of the sdl audio buffer (default: 1024)
	        
	    Read Only Properties

	        none
	        
	    Dependencies

	        libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
	    
	    Known Bugs

	        none

	xml

	    Description

	        Serialise the service network to XML.
	        See docs/mlt-xml.txt for more information.
	        
	    Constructor Argument

	        resource - the name of a file in which to store the XML.
	                  - stdout is default.
	        
	    Initialisation Properties

	        string resource - same as above.
	        
	    Dependencies
	    
	        libxml2
	        
	    Known Bugs

	        Untested arbitrary nesting of multitracks and playlists.
	        Property "id" is generated as service type followed by number if
	        no property named "id" exists, but it fails to guarantee uniqueness.
