Service Documentation Copyright (C) 2004 Ushodaya Enterprises Limited Authors: Charles Yates Dan Dennedy Last Revision: 2004-03-20 SERVICES -------- Services marked as "(Proprietary)" are not distributed with the GPL 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 fps - this is fixed at 25 for PAL currently 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 must be configured as --enable-shared and installed prior to compilation of mlt. Known Bugs Audio sync discrepancy with some content. Not all libavformat supported formats are seekable. Ogg Vorbis is currently broken. MPEG seeking is inaccurate - doesn't seek to i-frames so you may get junk for a few frames. RAW DV seeking not supported. Fails to play beyond first frame of video of sources with PTS not starting at 0 (video4linux). fezzik 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 is 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 ffmpeg (DEPRECATED) Description Test case pipe based producer for video and audio. Constructor Argument 'file' - produce a/v from file v4l - produce a/v from video4linux and dsp device Initialisation Properties string video_type - "file" or "v4l" string video_file - file or v4l device string video_size - WxH of video to produce (default: "") int video_loop - loop video until audio exhausted (default: 0) string audio_type - "file" or "dsp" string audio_file - file or dsp device int audio_rate - audio frequency (default: 48000) 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) int 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 string resource - file or "v4l" int end_of_clip - holds 1 when input is exhausted Dependencies ffmpeg executable. Known Bugs in point setting is broken. Implementation does not allow fast random access. 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- <, >, & Details Supplying a filename with extension ".txt" causes the Fezzik 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 inigo commands. For westley, 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- <, >, & 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. 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 "2 channels. rescale Description Scale the producer video frame size to match the consumer. This filter is automatically invoked by Fezzik in order to normalise sample aspect ratio. 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 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 Fezzik 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 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 ('fezzik') 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, fezzik 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 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%" Initialisation Properties 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. 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 fezzik. Read Only Properties none Mutable 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. Dependencies none Known Bugs Assumes lower field first during field rendering. luma Description A generic dissolve and wipe transition processor. 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 Fezzik. 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 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 Fezzik. 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. 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 fezzik. 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 --------- 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 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 scale_overlay - if 1, resample video from source pixel aspect ratio to square pixels. int progressive - indicates whether to use progressive or field- based rendering, default 0 (off). Read Only Properties none Dependencies libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE Known Bugs none westley Description Serialise the service network to XML. See docs/westley.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.