new volume, mix, and resample filters and transitions
[melted] / mlt / docs / services.txt
index 3588610..0477176 100644 (file)
@@ -3,11 +3,11 @@ Producers
 
        ffmpeg
 
-               Description:
+               Description
 
                        Test case pipe based producer for video and audio.
 
-               Constructor argument:
+               Constructor Argument
 
                        'file'  - produce a/v from file
                        v4l             - produce a/v from video4linux and dsp device
@@ -24,13 +24,15 @@ Producers
                        int audio_channels - audio channels (default: 2)
                        int audio_track - audio track to use (default: 0)
                        int audio_loop - loop audio until video exhausted (default: 0)
-                       timecode in - in point
-                       timecode out - out point
+                       intint in - in point
+                       int out - out point
                        double fps - output frames per second (default: 25)
+                       double aspect_ratio - aspect ratio of video
 
                Read Only Properties
 
-                       end_of_clip - holds 1 when input is exhausted
+                       string resource - file or "v4l"
+                       int end_of_clip - holds 1 when input is exhausted
 
                Dependencies
 
@@ -38,29 +40,31 @@ Producers
 
                Known Bugs
 
-                       in/out point setting is broken.
+                       in point setting is broken.
 
                        Implementation does not allow fast random access.
 
        libdv
 
-               Description:
+               Description
 
                        libdv based decoder for video and audio.
 
-               Constructor argument:
+               Constructor Argument
 
                        'file'  - produce a/v from file
 
                Initialisation Properties
 
-                       string file - file location
-                       timecode in - in point
-                       timecode out - out point
+                       int in - in point
+                       int out - out point
 
                Read Only Properties
 
-                       double fps - output frames per second 
+                       string resource - file location
+                       double fps - output frames per second
+                       double aspect_ratio - aspect ratio of video]
+                       int length - duration of resource (in frames)
 
                Dependencies
 
@@ -68,32 +72,576 @@ Producers
 
                Known Bugs
 
-                       'file' is not populated on properties?
+                       None.
 
        mcdv
+
+               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
+                       double aspect_ratio - aspect ratio of video
+                       int length - duration of resource (in frames)
+
+               Dependencies
+
+                       mainconcept dv sdk and libdv.
+                       "dv_sdk" installed parallel to mlt.
+
+               Known Bugs
+
+                       Can be problematic with source NTSC DV files? really? yes - try
+                       playing pond.dv...
+
        mcmpeg
+
+               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 - aspect ratio of video
+
+               Dependencies
+
+                       mainconcept mpeg sdk.
+                       "mpeg_sdk_demo" installed parallel to mlt.
+
+               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: <, >, & to &lt;, &gt;, &amp;
+
+               Initialisation Properties
+
+                       int in - in point
+                       int out - out point
+
+               Mutable Properties
+
+                       int video_standard - enum mlt_video_standard from mlt_frame.h
+                                            PAL = 0, NTSC = 1
+                                            this determines proper pixel aspect ratio
+
+                       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: <, >, & to &lt;, &gt;, &amp;
+
+                       int fgcolor - an rgba color specification of the text (i.e. 0xrrggbbaa)
+                       int bgcolor - an rgba color of the background rectangle
+                       int align - paragraph alignment: 0 = left, 1 = center, 2 = right
+                       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 text (can contain markup chars un-encoded)
+                       string font - the default typeface to use when not using markup
+                                     default "Sans 48"
+                       int x - the horizontal position of the title on the frame
+                               default 0
+                       int y - the vertical position of the title on the frame
+                               default 0
+                       double mix - the overall opacity control of the generated title
+                                    default 1.0
+
+               Read Only Properties
+
+                       string resource - the text/markup file or "pango" if no file
+
+               Dependencies
+
+                       libpango-1.0, libpangoft2-1.0, libfreetype, libgdk_pixbuf-2.0, libglib-2.0,
+                       libgobject-2.0, libgmodule-2.0, libfontconfig
+
+               Known Bugs
+
+                       no frame-alignment functionality
+
        pixbuf
+
+               Description
+
+                       A graphics overlay 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
+
+               Initialisation Properties
+
+                       int in - in point
+                       int out - out point
+
+               Mutable Properties
+
+                       int video_standard - enum mlt_video_standard from mlt_frame.h
+                                            PAL = 0, NTSC = 1
+                                            this determines proper pixel aspect ratio
+                       double ttl - how long (seconds) to repeat each picture in file sequences
+                       int x - the horizontal offset from the left edge of the frame
+                       int y - the vertical offset from the top edge of the frame
+                       double mix - the opacity factor to apply to the second frame
+                                    (used in addition to alpha channel).
+
+
+               Read Only Properties
+
+                       string resource - file location
+
+               Dependencies
+
+                       libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
+
+               Known Bugs
+
+                       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.
 
 
 Filters
 -------
 
        deinterlace
+       
+               Description
+
+                       Deinterlace a frame consisting of two fields by linearly blending.
+               
+               Constructor Argument
+
+                       none
+               
+               Initialisation Properties
+
+                       int in - in point
+                       int out - out point
+
+               Read Only Properties
+
+                       none
+               
+               Dependencies
+
+                       none
+                       
+               Known Bugs
+
+                       Not a bug, but it only provides fair quality at a fair performance;
+                               i.e., it excels at neither.
+               
        ffmpeg_dub
+       
+               Description
+
+                       Use ffmpeg executable to substitute audio stream.
+               
+               Constructor Argument
+
+                       file - filename of a WAV, Ogg Vorbis (--enable-vorbis),
+                              MP3 (--enable-mp3lame), or AC-3 (--enable-a52) audio file.
+               
+               Initialisation Properties
+
+                       int in - in point
+                       int out - out point
+               
+               Read Only Properties
+               
+                       string resource - file
+                       
+               Dependencies
+
+                       ffmpeg plus for ffmpeg:
+                       libogg and libvorbis for Ogg Vorbis, libmp3lame for MP3, liba52 for AC-3.
+                       
+               Known Bugs
+
+                       Uses pipes and is therefore not compatible with bluefish.
+
        gamma
+       
+               Description
+
+                       Adjust image luma using a non-linear power-law curve
+                       
+               Constructor Argument
+
+                       gamma - a floating point value
+               
+               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 color 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
+               
        resize
+       
+               Description
+
+                       Image scaling and padding
+                       
+               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
+
+                       none
+
+       volume
+
+               Description
+
+                       Adjust an audio stream's volume level
+                       
+               Constructor Argument
+
+                       volume - a floating point value of the factor
+                       
+               Initialisation Properties
+               
+                       int in - in point
+                       int out - out point
+
+               Mutable Properties
+
+                       double volume - the factor applied to each sample
+                       
+               Dependencies
+
+                       none
+                       
+               Known Bugs
+
+                       none
+
+       resample
+
+               Description
+
+                       Adjust an audio stream's sampling rate
+
+               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
+
+                       none
 
 Transitions
 -----------
 
        composite
+       
+               Description
+
+                       An alpha-channel based compositor for two frames.
+                       
+               Constructor Argument
+
+                       mix - see below
+
+               Initialisation Properties
+                       
+                       int in - in point
+                       int out - out point
+
+               Mutable Properties
+
+                       int x - the horizontal offset from the left edge of the frame
+                       int y - the vertical offset from the top edge of the frame
+                       double mix - the opacity factor to apply to the second frame
+                                    (used in addition to alpha channel).
+                                  - any negative value causes an automatic dissolve
+               
+               Read Only Properties
+
+                       none
+               
+               Dependencies
+
+                       none
+               
+               Known Bugs
+
+                       Need to add field-based rendering.
+
+       luma
+       
+               Description
+
+                       A generic dissolve and wipe transition processor. It 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 only reads PGM
+                       files, but it does handle 16 bit PGM. This performs field-based
+                       rendering.
+               
+               Constructor Argument
+
+                       string file - the luma map file name. If not supplied, a dissolve.
+
+               Initialisation Properties
+               
+                       int in - in point
+                       int out - out point
+
+               Mutable Properties
+
+                       string filename - 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.
+                       
+               Read Only Properties
+
+                       none
+                       
+               Dependencies
+
+                       none
+                       
+               Known Bugs
+
+                       The luma map must be the same size as the B frame.
+
+       mix
+
+               Description
+
+                       An two stream audio mixer.
+
+               Constructor Argument
+
+                       mix - see below
+
+               Initalisation Properties
+
+                       int in - in point
+                       int out - out point
+
+               Mutable Properties
+
+                       double mix - the mix level to apply to the second frame.
+                                  - any negative value causes an automatic crossfade.
+
+               Read Only Properties
+
+                       none
+
+               Dependencies
+
+                       none
+
+               Known Bugs
+
+                       Samples from the longer of the two frames are discarded.
 
 Consumers
 ---------
 
        bluefish
+       
+               Description
+
+                       BlueFish444 audio and video output module.
+               
+               Constructor Argument
+
+                       string video_standard - "PAL" (default) or "NTSC"
+                       
+               Initialisation Properties
+
+                       int video_standard - 0 = PAL, 1 = NTSC
+                       
+               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 must reload the BlueDriver kernel module
+                       due to unreleased DMA buffers.
+                       
+                       Needs an argument or property for multi-card address.
+               
+       ffmpeg
+       
+               Description
+               Constructor Argument
+               Initialisation Properties
+               Read Only Properties
+               Dependencies
+               Known Bugs
+
        sdl
+               Description
+
+                       Simple DirectMedia Layer audio and video output module.
+                       
+               Constructor Argument
+
+                       string video_standard - "PAL" (default), "NTSC", or "WxH"
+                       
+               Mutable Properties
+
+                       double volume - audio level factor
+                       int video_off - if 1, disable video output
+                       int audio_off - if 1, disable audio output
+                       int scale_overlay - if 1, resample video from source pixel aspect
+                                           ratio to square pixels.
+                       
+               Read Only Properties
+
+                       none
+                       
+               Dependencies
+
+                       libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
+               
+               Known Bugs
+
+                       NTSC handling needs tightening up - sdl:NTSC is the only valid
+                       constructor for NTSC playback at the moment.