X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=docs%2Fservices.txt;h=86a9ab6366be2e2caa36943eb99dc0e73374fa9a;hb=2a2669b620e293e8963205c86606618789951eed;hp=4fde29a8ed0f392f1456b128d4f63c2deb4131c7;hpb=978543a20e47302b82bc29007852bff8180031c2;p=mlt diff --git a/docs/services.txt b/docs/services.txt index 4fde29a8..86a9ab63 100644 --- a/docs/services.txt +++ b/docs/services.txt @@ -1,907 +1,1513 @@ -Producers ---------- +Service Documentation - avformat +Copyright (C) 2004 Ushodaya Enterprises Limited +Authors: Charles Yates + Dan Dennedy +Last Revision: 2004-11-07 - Description - ffmpeg libavformat based producer for video and audio. +SERVICES +-------- - Constructor Argument + Services marked as "(Proprietary)" are not distributed with the GPL version + of mlt. - 'file' - producer a/v from file +Producers +--------- - Initialisation Properties + avformat - 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 + Description - Read Only Properties + ffmpeg libavformat based producer for video and audio. - double fps - this is fixed at 25 for PAL currently - double aspect_ratio - this is determined on the first frame read + Constructor Argument - Dependencies + '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. - ffmpeg must be configured as --enable-shared and installed prior - to compilation of mlt. + Initialisation Properties - Oddities + 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 - There seems to be a discrepancy between audio and video pts (time - stamps) which causes audio seeking to be unreliable in some cases. - If audio playback is broken, try adding discrepancy=3 as a - property. + Read Only Properties - Not sure of the exact reasons, but am investigating. + 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 - Known Bugs + Dependencies - Fixed frame rate. - Audio sync discrepancy with some content. - Not all libavformat supported formats are seekable. - ogg is currently broken. - mpeg seeking is inaccurate - doesn't seek to i-frames so you may - get junk for a few frames. + ffmpeg must be configured as --enable-shared and installed prior + to compilation of mlt. - fezzik + Known Bugs - Description + 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). - A friendly giant that likes to rhyme and throw rocks + fezzik - Constructor Argument + Description - 'file' - produce a/v from file + A friendly giant that likes to rhyme and throw rocks - Initialisation Properties + Constructor Argument - int in - in point - int out - out point - + all producer initialising properties + '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. - Read Only Properties + Initialisation Properties - string resource - file location - + all producer read only properties + int in - in point + int out - out point + + all producer initialising properties - Details + Read Only Properties - This producer is has two roles: + string resource - file location + + all producer read only properties - 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). + Details - This producer simplifies many aspects of use. Essentially, it - ensures that a consumer will receive images and audio precisely as - they request them. + This producer has two roles: - Dependencies + 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). - all. + This producer simplifies many aspects of use. Essentially, it + ensures that a consumer will receive images and audio precisely as + they request them. - Known Bugs + Dependencies - None. + all. - ffmpeg + Known Bugs - Description + None. - Test case pipe based producer for video and audio. + + 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 - Constructor Argument + + libdv - 'file' - produce a/v from file - v4l - produce a/v from video4linux and dsp device + Description - Initialisation Properties + libdv based decoder for video and audio. - 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 + Constructor Argument - Read Only Properties + 'file' - produce a/v from file - string resource - file or "v4l" - int end_of_clip - holds 1 when input is exhausted + Initialisation Properties - Dependencies + int in - in point + int out - out point - ffmpeg executable. + Read Only Properties - Known Bugs + 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. - in point setting is broken. + Dependencies - Implementation does not allow fast random access. + libdv. - libdv + Known Bugs - Description + DVCPRO is incorrectly identified as 16:9 aspect ratio. You must use + libdv from CVS or a post 0.101 release. - libdv based decoder for video and audio. + mcdv (Proprietary) - Constructor Argument + Description - 'file' - produce a/v from file + MainConcept based dv decoder for video and audio. - Initialisation Properties + Constructor Argument - int in - in point - int out - out point + 'file' - produce a/v from file - Read Only Properties + Initialisation 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) + int in - in point + int out - out point - Dependencies + Read Only Properties - libdv. + string resource - file location + double fps - output frames per second + int length - duration of resource (in frames) - Known Bugs + Dependencies - None. + MainConcept DV or DVCPRO SDK, libdv. + "dv_sdk" installed parallel to mlt. - mcdv + Known Bugs - Description + None - Mainconcept based dv decoder for video and audio. + mcmpeg (Proprietary) - Constructor Argument + Description - 'file' - produce a/v from file + MainConcept based mpeg decoder for video and audio. - Initialisation Properties + Constructor Argument - int in - in point - int out - out point + 'file' - produce a/v from file - Read Only Properties + Initialisation 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) + int in - in point + int out - out point - Dependencies + Read Only Properties - mainconcept dv sdk and libdv. - "dv_sdk" installed parallel to mlt. + 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 - Known Bugs + MainConcept MPEG SDK. + "mpeg_sdk_release" installed parallel to mlt. - Can be problematic with some NTSC DV files? + Known Bugs - mcmpeg + None. - Description + noise - Mainconcept based mpeg decoder for video and audio. + Description - Constructor Argument + White noise producer - 'file' - produce a/v from file + Constructor Argument - Initialisation Properties + none - int in - in point - int out - out point + Initialisation Properties - Read Only Properties + int in - in point + int out - out point - string resource - file location - double fps - output frames per second - double aspect_ratio - aspect ratio of video + Read Only Properties - Dependencies + 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_demo" installed parallel to mlt. + none - Known Bugs + Known Bugs - None. + none pango - Description + 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. + 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. - A title generator that uses the Pango international text layout - and Freetype2 font renderer. + pixbuf - Constructor Argument + Description - 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 <, >, & + A still graphics to video generator using gdk-pixbuf - Initialisation Properties + Constructor Argument - int in - in point - int out - out point + '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 ", & to <, >, & + Mutable Properties - string fgcolour - an rgba colour specification of the text (i.e. 0xrrggbbaa) - string bgcolour - an rgba colour 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 ttl - how long (in frames) to repeat each picture in file + sequences. default is 25. - Read Only Properties + Read Only Properties - string resource - the text/markup file or "pango" if no file + 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 + Dependencies - libpango-1.0, libpangoft2-1.0, libfreetype, libgdk_pixbuf-2.0, libglib-2.0, - libgobject-2.0, libgmodule-2.0, libfontconfig + libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0 - Known Bugs + Known Bugs - no frame-alignment functionality + XXX: in/out settings are incorrectly handled. - pixbuf - - Description + ppm + + Description - A graphics overlay generator using gdk-pixbuf + Reads a stream of contiguous PPM images. + + Constructor Argument - Constructor Argument + command - a shell command to run something that produces ppm + streams on stdout. + + Initialisation Properties - '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 + none + + Read Only Properties - Initialisation Properties + string resource - the command + + Dependencies - int in - in point - int out - out point + none + + Known Bugs - Mutable Properties + Since it uses pipes, it is not compatible with bluefish. - 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 + westley - Read Only Properties + Description - string resource - file location + Construct a service network from an XML description. + See docs/westley.txt. - Dependencies + Constructor Argument - libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0 + URL - an XML text file containing westley XML (schema/DTD pending) + - Since westley 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 inigo, + who tokenises anything with an equal sign as a property + setting. Also, when running inigo from the shell, beware of + the '?' and shell filename expansion. You can surround the URL + with single quotations to prevent expansion. Finally, fezzik + will fail to match the filename when you use parameters, so + preface the url with 'westley:' to force fezzik to load with + the westley service. + + Read Only Properties - Known Bugs + string resource - file location - in/out settings are incorrectly handled. + Dependencies - ppm - - Description + libxml2 - Reads a stream of contiguous PPM images. - - Constructor Argument + Known Bugs - command - a shell command to run something that produces ppm - streams on stdout. - - Initialisation Properties + 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. - none - - Read Only Properties + vorbis - string resource - the command - - Dependencies + Description - none - - Known Bugs + OGG Vorbis file reader. - Since it uses pipes, it is not compatible with bluefish. + Constructor Argument - westley + 'file' - file to use (only .ogg supported at the moment) - Description + Initialisation Properties - Construct a service network from an XML description. + int in - in point + int out - out point - Constructor Argument + Read Only Properties - file - an XML text file containing westley XML (schema pending) + double fps - this is fixed at 25 for PAL currently - Read Only Properties + Dependencies - string resource - file location + libvorbisfile - Dependencies + Known Bugs - libxml2 + Fixed frame size (PAL audio chunks). + Doesn't cover ogg files with multiple, differing sections. - Known Bugs +Filters +------- - Non-referenced producers and playlists are not destroyed. - A referenced producer or playlist must appear before the reference. + 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 + - vorbis - Description + 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 - OGG Vorbis file reader. + Adjust image luma using a non-linear power-law curve + + Constructor Argument - Constructor Argument + gamma - a floating point value. The default is 1.0, or none. + + Initialisation Properties + + int in - in point + int out - out point - 'file' - file to use (only .ogg supported at the moment) + Mutable Properties - Initialisation Properties + double gamma - the exponential factor of the power-law curve + + Dependencies - int in - in point - int out - out point + none + + Known Bugs - Read Only Properties + none + + + greyscale + + Description - double fps - this is fixed at 25 for PAL currently + Convert colour image to greyscale + + Constructor Argument - Dependencies + none + + Initialisation Properties + + int in - in point + int out - out point - libvorbisfile + Read Only Properties - Known Bugs + none + + Dependencies - Fixed frame size (PAL audio chunks). - Doesn't cover ogg files with multiple, differing sections. + none + + Known Bugs -Filters -------- + none + + gtkrescale - deinterlace - - Description + Description - Deinterlace a frame consisting of two fields by linearly blending. - - Constructor Argument + Scale the producer video frame size to match the consumer. + This filter is designed for use as a Fezzik normaliser. - none - - Initialisation Properties + Constructor Argument - int in - in point - int out - out point + interpolation - the rescaling method, one of: + nearest (lowest quality, fastest), + tiles, + bilinear (default; good quality, moderate speed), + hyper (best quality, slowest). - Read Only Properties + Initialisation Properties - none - - Dependencies + int in - in point + int out - out point - none - - Known Bugs + Mutable Properties - Not a bug, but it only provides fair quality at a fair performance; - i.e., it excels at neither. - - ffmpeg_dub - - Description + string interpolation - see constructor argument above - Use ffmpeg executable to substitute audio stream. - - Constructor Argument + 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. - file - filename of a WAV, Ogg Vorbis (--enable-vorbis), - MP3 (--enable-mp3lame), or AC-3 (--enable-a52) audio file. - - Initialisation Properties + Dependencies - int in - in point - int out - out point - - Read Only Properties - - string resource - file - - Dependencies + libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0 - ffmpeg plus for ffmpeg: - libogg and libvorbis for Ogg Vorbis, libmp3lame for MP3, liba52 for AC-3. - - Known Bugs + Known Bugs - Uses pipes and is therefore not compatible with bluefish. + none - gamma + jackrack - Description - - Adjust image luma using a non-linear power-law curve + Description + + Creates Jack ports and runs a JackRack project to process audio + through a stack of LADSPA filters. + + Constructor Argument + + src - a JackRack file - Constructor Argument - - gamma - a floating point value - - Initialisation Properties + Details - int in - in point - int out - out point - - Mutable Properties - - double gamma - the exponential factor of the power-law curve + If you are using a consumer that uses ALSA, then you should start + jacks with the dummy driver: jackd -d dummy. + I also recommend using a period size of 2048: -p 2048. - Dependencies - - none + jackd -ddummy -r48000 -p2048 + + Initialisation Properties + + int in - in point + int out - out point - Known Bugs + 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 + + no encapsulated resampling and jack runs at a fixed frequency + + luma - greyscale + 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 Fezzik normaliser. + + 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 - Description - - Convert colour image to greyscale - - Constructor Argument - - none - - Initialisation Properties - - int in - in point - int out - out point - - Read Only Properties - - none - - Dependencies + 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 - none - - Known Bugs - none - obscure - Description + Description - Obscuring filter. - - Constructor Argument + Obscuring filter. + + Constructor Argument - none - - Initialisation Properties - - string start - in the format X,Y:WxH[:PWxPY] - string end - in the format X,Y:WxH[:PWxPY] - int in - in point - int out - out point + 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 + Read Only Properties - none - - Dependencies + none + + Dependencies - none + none - Known Bugs + Known Bugs - none + none - resize + region - Description + 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. + - Image scaling and padding - - Constructor Argument + resample - scale - "affine" to use affine transform scaling, otherwise - center and pad. - - Initialisation Properties - - int in - in point - int out - out point + Description - Read Only Properties + Adjust an audio stream's sampling rate, and duplicate channels if + producer provides less than consumer requested. + + This filter is automatically invoked by Fezzik for the sake of + normalisation over inputs and with the consumer. - none - - Dependencies + Constructor Argument - none - - Known Bugs + frequency - a numeric value for the new sample rate - none + Initialisation Properties - volume + int in - in point + int out - out point - Description + Mutable Properties - Adjust an audio stream's volume level - - Constructor Argument + int frequency - the target sample rate - 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. + Dependencies - Mutable Properties + libresample - string gain - same as constructor argument above + Known Bugs - 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 + Assumes 2 channels during libsamplerate initialisation. Untested + with >2 channels. - 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 + rescale - 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 + Description - 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. + Scale the producer video frame size to match the consumer. + This filter is designed for use as a Fezzik normaliser. - 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. + Constructor Argument - gain can be applied as a factor to the normalise amplitude! - - Dependencies + None. - none - - Known Bugs + Initialisation Properties - none + int in - in point + int out - out point - resample + Mutable Properties - Description + 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. - Adjust an audio stream's sampling rate + Dependencies - Constructor Argument + none - frequency - a numeric value for the new sample rate + Known Bugs - Initialisation Properties + none but... it only implements a nearest neighbour scaling - it is + used as the base class for the gtkrescale and mcrescale filters. - int in - in point - int out - out point + 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. - Mutable Properties + volume - int frequency - the target sample rate + Description - Dependencies + Adjust an audio stream's volume level + - based on the 'normalize' utility + + Constructor Argument - libresample + 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. - Known Bugs + Mutable Properties - none + string gain - same as constructor argument above - rescale + 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 - Description + 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 - Scale the producer video frame size to match the consumer. + 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 - Constructor Argument + 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. - interpolation - the rescaling method, one of: - nearest (lowest quality, fastest), - tiles, - bilinear (good quality, moderate speed), - hyper (best quality, slowest) + 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. - Initialisation Properties + gain can be applied as a factor to the normalise amplitude! + + Dependencies - int in - in point - int out - out point + none + + Known Bugs - Mutable Properties + none - string interpolation - see constructor argument above + watermark - 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. + Description - Dependencies + Add a watermark to the frames. - libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0 + Constructor Argument - Known Bugs + resource - the producer to use (ie: a .png) - none + Initialisation Properties -Transitions ------------ + 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 - composite - - Description + Mutable Properties - An alpha-channel based compositor for two frames. - - Constructor Argument + none - string start - X,Y:WxH[:mix] + Dependencies - Initialisation Properties - - string end - X,Y:WxH[:mix] - int in - in point - int out - out point - - Read Only Properties + mlt core modules and optionally, fezzik - none - - Dependencies + Known Bugs - none - - Known Bugs + none - Need to add field-based rendering. +Transitions +----------- - luma + composite - 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 resource - the luma map file name. If not supplied, a dissolve. - - Initialisation Properties - - int in - in point - int out - out point - - 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. - - Read Only Properties - - none - - Dependencies - - none - - Known Bugs + 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 fezzik. + + 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. - The luma map must be the same size as the B frame. - The PGM parser does not handle comments. + 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 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 + + none + + Known Bugs + + Assumes lower field first output. mix - Description + Description - An two stream audio mixer. + An two stream audio mixer. - Constructor Argument + Constructor Argument - start - see below + start - see below - Initalisation Properties + Initalisation Properties - int in - in point - int out - out point + int in - in point + int out - out point - Mutable Properties + 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. + 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 + Read Only Properties - none + none - Dependencies + Dependencies - none + none - Known Bugs + Known Bugs - Samples from the longer of the two frames are discarded. + 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 + avformat - 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 + + 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 - Constructor Argument - Initialisation Properties - Read Only Properties - Dependencies - Known Bugs - + 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 + 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 - string video_standard - "PAL" (default) or "NTSC" - - Initialisation Properties - Read Only Properties - Dependencies - Known Bugs + 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" - - 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. + 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 westley - Description - - Serialise the service network to XML. - - Constructor Argument - - resource - the name of a file in which to store the XML. - stdout is used if not supplied. - - 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. - + 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.