3 Authors: Charles Yates <charles.yates@pandora.be>
4 Dan Dennedy <dan@dennedy.org>
5 Last Revision: 2009-05-08
11 Services marked as "(Proprietary)" are not distributed with the LGPL
21 ffmpeg libavformat based producer for video and audio.
25 'file' - a filename specification or URL in the form:
26 [{protocol}|{format}]:{resource}[?{format-parameter}[&{format-parameter}...]]
27 For example, video4linux:/dev/video1?width:320&height:240
28 Note: on the bash command line, & must be escaped as '\&'.
29 Also, note the use of ':' instead of '=' for parameters.
30 Use 'ffmpeg -formats' to see a list of supported protocols
35 Format parameters only appear to be useful with 'video4linux' or
36 'audio_device' formats. For 'video4linux' the parameters are
37 width, height, frame_rate, frame_rate_base, and standard (ntsc|pal).
38 For 'audio_device' the parameters are channels and sample_rate.
40 Initialisation Properties
42 int video_index - index of video stream to use (-1 is off)
43 int audio_index - index of audio stream to use (-1 is off)
49 string resource - file location
50 double source_fps - the framerate of the resource
51 double aspect_ratio - sample aspect ratio of the resource
52 - this is determined on every frame read
60 Audio sync discrepancy with some content.
61 Not all libavformat supported formats are seekable.
62 Fails to play beyond first frame of video of sources with PTS not
63 starting at 0 (video4linux).
69 A friendly giant that likes to rhyme and throw rocks
73 'file' - a filename specification:
74 [{mlt-service}:]{resource} | {mlt-service}
75 - can also be the name of a producer service that can
76 accept the resource specified post construction.
78 Initialisation Properties
82 + all producer initialising properties
86 string resource - file location
87 + all producer read only properties
91 This producer has two roles:
93 1. it handles the mappings of all file names to the other
95 2. it attaches normalising filters (rescale, resize and resample)
96 to the producers (when necessary).
98 This producer simplifies many aspects of use. Essentially, it
99 ensures that a consumer will receive images and audio precisely as
115 A simple colour generator.
119 colour - A colour value is a hexadecimal representation of RGB plus
120 alpha channel as 0xrrggbbaa.
121 - Also colours can be the words: white, black, red, green,
123 - The default colour is black.
125 Initialisation Properties
146 libdv based decoder for video and audio.
150 'file' - produce a/v from file
152 Initialisation Properties
159 string resource - file location
160 double fps - output frames per second
161 int length - duration of resource (in frames)
165 string quality - one of "best," "fast" or anything else chooses
174 DVCPRO is incorrectly identified as 16:9 aspect ratio. You must use
175 libdv from CVS or a post 0.101 release.
187 Initialisation Properties
194 string resource - file location
195 double fps - output frames per second
196 double aspect_ratio - sample aspect ratio of video
197 int length - duration of resource (in frames)
211 A title generator that uses the Pango international text layout
212 and Freetype2 font renderer.
216 string file - a text file containing Pango markup, see:
217 http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
218 - requires xml-like encoding special chars from:
219 <, >, & -to- <, >, &
223 Supplying a filename with extension ".txt" causes the loader
224 producer to load with pango. If the filename begins with "+" the
225 pango producer interprets the filename as pango text. This is a
226 shortcut to embed titles in melt commands. For MLT XML, it is
227 recommended that you embed the title text in the property value.
229 Pango has builtin scaling. It will rescale the originally rendered
230 title to whatever the consumer requests. Therefore, it will lose
231 its aspect ratio if so requested, and it is up to the consumer to
232 request a proper width and height that maintains the image aspect.
234 Initialisation Properties
241 string markup - a string containing Pango markup see:
242 http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
243 - requires xml-like encoding special chars from:
244 <, >, & -to- <, >, &
245 string fgcolour - an RGBA colour specification of the text
247 string bgcolour - an RGBA colour of the background rectangle
248 string align - paragraph alignment: left, centre, right
249 - also, numbers 0, 1 and 2 can be used respectively.
250 int pad - the number of pixels to pad the background rectangle
251 beyond edges of text. default 0.
252 string markup - see constructor argument
253 string text - non-markup string in UTF-8 encoding (can contain
254 markup chars un-encoded)
255 string font - the default typeface to use when not using markup.
256 default "Sans 48". FreeType2 renders at 72 dpi.
257 string encoding - the text encoding type of the input if not UTF-8.
258 - see 'iconv --list' for a list of possible inputs.
259 int weight - the weight of the font (default is 400)
263 string resource - the text/markup file or "pango" if no file.
264 int real_width - the original, unscaled width of the rendered title.
265 int real_height - the original, unscaled height of the title.
266 int width - the last requested scaled image width.
267 int height - the last requested scaled image height.
271 libpango-1.0, libpangoft2-1.0, libfreetype, libgdk_pixbuf-2.0,
272 libglib-2.0, libgobject-2.0, libgmodule-2.0, libfontconfig.
276 The foreground and background Pango markup span attributes are not
278 Word wrapping is not supported.
284 A still graphics to video generator using gdk-pixbuf
288 'file' - The name of a graphics file loadable by
289 a gdk-pixbuf loader. see /usr/lib/gdk-pixbuf/loaders
290 definitely png, jpeg, tiff, pnm, and xpm
291 - If "%" in filename, the filename is used with sprintf
292 generate a filename from a counter for multi-file/flipbook
293 animation. The file sequence ends when numeric
295 - If filename contains "/.all.", suffix with an extension to
296 load all pictures with matching extension from a directory.
297 - If filename contains the string "<svg", then pixbuf tries
298 to load the filename as inline SVG XML, which is convenient
303 Pixbuf has builtin scaling. It will rescale the originally rendered
304 title to whatever the consumer requests. Therefore, it will lose
305 its aspect ratio if so requested, and it is up to the consumer to
306 request a proper width and height that maintains the image aspect.
308 Initialisation Properties
312 int begin - when using an image sequence, this sets the starting
317 int ttl - how long (in frames) to repeat each picture in file
318 sequences. default is 25.
322 string resource - file location. See Constructor Argument above.
323 int real_width - the original, unscaled width of the rendered title.
324 int real_height - the original, unscaled height of the title.
325 int width - the last requested scaled image width.
326 int height - the last requested scaled image height.
330 libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
334 XXX: in/out settings are incorrectly handled.
340 Reads a stream of contiguous PPM images.
344 command - a shell command to run something that produces ppm
347 Initialisation Properties
353 string resource - the command
361 Since it uses pipes, it is not compatible with bluefish.
367 Construct a service network from an XML description.
368 See docs/mlt-xml.txt.
372 URL - an XML text file containing MLT XML
373 - Since MLT XML files can be parameterised, the URL syntax is:
374 {file-name}[?{param-name}{'='|':'}{param-value}[&{param-name}{'='|':'}{param-value}...]]
375 A colon is allowed instead of an equal sign to pacify melt,
376 who tokenises anything with an equal sign as a property
377 setting. Also, when running melt from the shell, beware of
378 the '?' and shell filename expansion. You can surround the URL
379 with single quotations to prevent expansion. Finally, the loader
380 will fail to match the filename when you use parameters, so
381 preface the url with 'xml:' to force the loader to load with
386 string resource - file location
394 Non-referenced producers and playlists are not destroyed until the
395 network is destroyed.
396 A referenced producer or playlist must appear before the reference.
397 A filter that occurs before a producer has been defined causes a
404 OGG Vorbis file reader.
408 'file' - file to use (only .ogg supported at the moment)
410 Initialisation Properties
417 double fps - this is fixed at 25 for PAL currently
425 Fixed frame size (PAL audio chunks).
426 Doesn't cover ogg files with multiple, differing sections.
435 Shift the luma component using a constant value.
439 start - the constant floating point numeric value to apply.
442 Initialisation Properties
446 double start - see Constructor Argument above.
447 double end - the ending adjustment value. the filter interpolates
448 between the start and end adjustments over the
449 duration of the effect.
461 Does not go completely to black or white.
468 Copy audio from one channel to another channel.
472 to - the 0-indexed channel to copy into, default is 1.
477 int from - the channel from which to copy, default is 0.
493 Deinterlace a frame consisting of two fields using bob, weave,
494 greedy, one-field, and linear blend methods. This code is
495 appropriated from the Xine XV video output plugin.
499 method - a string containing the deinterlace method: bob, weave,
500 greedy, onefield, or linearblend. The default is
503 Initialisation Properties
518 If the frame properties "progressive" or "consumer_progressive"
519 are non-zero, then the filter is not applied. Also, if applied,
520 this sets the frame property "progressive" to 1.
528 Not a bug, but it only provides fair quality.
535 Adjust image luma using a non-linear power-law curve
539 gamma - a floating point value. The default is 1.0, or none.
541 Initialisation Properties
548 double gamma - the exponential factor of the power-law curve
563 Convert colour image to greyscale
569 Initialisation Properties
590 Scale the producer video frame size to match the consumer.
591 This filter is designed for use as a normaliser for the loader producer.
595 interpolation - the rescaling method, one of:
596 nearest (lowest quality, fastest),
598 bilinear (default; good quality, moderate speed),
599 hyper (best quality, slowest).
601 Initialisation Properties
608 string interpolation - see constructor argument above
610 If a property "consumer_aspect_ratio" exists on the frame, then
611 rescaler normalises the producer's aspect ratio and maximises the
612 size of the frame, but may not produce the consumer's requested
613 dimension. Therefore, this option works best in conjunction with the
614 resize filter. This behavior can be disabled by another service by
615 either removing the property, setting it to zero, or setting
616 frame property "distort" to 1.
620 libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
630 Creates Jack ports and runs a JackRack project to process audio
631 through a stack of LADSPA filters.
635 src - a JackRack file
639 If you are using a consumer that uses ALSA, then you should start
640 jackd with the dummy driver: jackd -d dummy.
641 I also recommend using a period size of 2048: -p 2048.
643 jackd -ddummy -r48000 -p2048
645 Initialisation Properties
650 The following can be used without a rack file in order to connect
651 filter_jackrack to a running instance of JackRack:
652 string out_1 - Jack port to connect MLT's output port (JackRack's input)
653 string out_2 - Jack port to connect MLT's output port (JackRack's input)
654 string in_1 - Jack port to connect MLT's input port (JackRack's output)
655 string in_2 - Jack port to connect MLT's input port (JackRack's output)
667 Jack, LADSPA, glib-2.0, libxml2
671 Currently, due to timing and synchronisation issues, the audio
672 is distorted with repeated samples and latency clicks.
673 no encapsulated resampling and jack runs at a fixed frequency
679 Runs a JackRack project to process audio through a stack of
680 LADSPA filters without using Jack.
684 src - a JackRack file
688 Due to audio integrity issues with the jackrack filter, this
689 filter is better for runtime, while jackrack is more suitable
690 for prototyping a rack file using the Jack Rack GUI.
692 Initialisation Properties
707 Jack, LADSPA, glib-2.0, libxml2
708 Jack is still required because this coexists with the jackrack
713 no encapsulated resampling and jack runs at a fixed frequency
719 Applies a luma transition between the current and next frames.
720 Useful for transitions from a slideshow created using producer
727 Initialisation Properties
738 int period - how long to wait between success iterations of the
739 transition. For best results set this to a multiple
740 of ttl used in pixbuf. The default is 24.
742 luma. - all properties beginning with "luma." are passed to the
743 encapsulated luma transition. For example, luma.out controls
744 the duration of the wipe.
748 transition_luma and its dependencies
758 Provides various mirror and image reversing effects.
762 mirror - horizontal, vertical, diagonal, flip, flop
764 Initialisation Properties
766 int reverse - being 0 or 1
791 Mix all channels of audio into a mono signal and output it as
796 channels - the number of output channels (default 2)
798 Initialisation Properties
829 Initialisation Properties
831 string start - in the format X/Y:WxH[:PWxPY]
832 - PWxPY is the size of the averaging region in pixels.
833 string end - in the format X/Y:WxH[:PWxPY]
853 Apply one or more filters to a region of the video image. The region
854 can be shaped as well using the alpha channel of another producer.
858 resource - A file whose alpha channel will "shape" the region.
859 - The string "circle" is a shortcut but it requires pixbuf with
860 the librsvg loader. The circle is automatically stretched
861 to the region to create an ellipse.
863 Initialisation Properties
867 plus and region transition properties
871 see the region transition
879 "circle" is unpredictable in the absence of the librsvg pixbuf loader.
886 Adjust an audio stream's sampling rate, and duplicate channels if
887 producer provides less than consumer requested.
889 This filter is automatically invoked by the loader producer for the
890 sake of normalisation over inputs and with the consumer.
894 frequency - a numeric value for the new sample rate
896 Initialisation Properties
903 int frequency - the target sample rate
911 Assumes 2 channels during libsamplerate initialisation. Untested
918 Scale the producer video frame size to match the consumer.
919 This filter is designed for use as a normaliser for the loader producer.
925 Initialisation Properties
932 If a property "consumer_aspect_ratio" exists on the frame, then
933 rescaler normalises the producer's aspect ratio and maximises the
934 size of the frame, but may not produce the consumer's requested
935 dimension. Therefore, this option works best in conjunction with the
936 resize filter. This behavior can be disabled by another service by
937 either removing the property, setting it to zero, or setting
938 frame property "distort" to 1.
946 none but... it only implements a nearest neighbour scaling - it is
947 used as the base class for the gtkrescale and mcrescale filters.
953 Image scaling and padding and field order adjustment.
957 Normally resize is used to pad the producer's
958 output to what the consumer has requested after an upstream rescale
959 filter first scales the image to maximise usage of the image area.
960 This filter also adjusts the field order to lower field first
961 if the frame property "top_field_first" has been set to 1.
962 Therefore, when done, it sets the top_field_first to 0.
963 This filter is automatically invoked by the loader as part of image
964 sample aspect ratio normalisation.
968 scale - "affine" to use affine transform scaling, otherwise
971 Initialisation Properties
986 Assumes lower field first output.
992 Adjust an audio stream's volume level
993 - based on the 'normalize' utility
997 gain - a string containing one of:
998 - a floating point value of the gain adjustment
999 - a numeric value with the suffix "dB" to adjust in terms of decibels
1000 - "normalise" to normalise the volume to the target amplitude -12dBFS
1002 Initialisation Properties
1006 int window - the number of video frames over which to smooth normalisation.
1011 string gain - same as constructor argument above
1013 string normalise - normalise the volume to the amplitude:
1014 - a numeric value with the suffix "dB" to set amplitude in decibels
1015 - a floating point value of the relative volume
1016 - an unspecified value uses the default -12dBFS
1018 string limiter - limit all samples above:
1019 - a numeric value with the suffix "dB"
1020 - a floating point value ( dB = 20 * log10(x) )
1021 - an unspecified value uses the default -6dBFS
1023 double max_gain - a floating point or decibel value of the maximum gain that
1024 can be applied during normalisation.
1025 - an unspecified value uses the default 20dB
1027 string end - a gain value just like the gain property above.
1028 This causes the gain to be interpolated from 'gain' to 'end'
1031 int window - the size of the normalising smoothing buffer in video frame units.
1032 - the smoothing buffer prevents erratic gain changes.
1033 - the default value is 75 video frames.
1035 gain can be applied as a factor to the normalise amplitude!
1049 Add a watermark to the frames.
1051 Constructor Argument
1053 resource - the producer to use (ie: a .png)
1055 Initialisation Properties
1057 string resource - the producer to use
1058 string factory - producer required for the resource (default: 'loader')
1059 string composite.geometry - composite geometry
1060 string composite.distort - control scaling
1070 mlt core modules and optionally, loader
1083 A key-framable alpha-channel compositor for two frames.
1087 Performs dissolves and luma wipes in addition to alpha compositing.
1089 By default, the aspect ratio of the B frame is respected and the
1090 size portion of the geometry specification simply defines a
1093 This performs field-based rendering unless the A frame property
1094 "progressive" or "consumer_progressive" or the transition property
1095 "progressive" is set to 1.
1097 Constructor Argument
1101 Initialisation Properties
1105 string factory - The name of a factory service used as a non-PGM
1106 producer loader. The default is 'loader'.
1108 Read Only Properties
1115 string geometry - key frame specification
1116 - this is a ; delimited form of the deprecated start,
1117 key[n], end properties
1118 int progressive - set to 1 to disable field-based rendering.
1119 string distort - when set, causes the B frame image to fill the WxH
1120 completely with no regard to B's aspect ratio.
1121 string halign - when not distorting, set the horizontal alignment
1122 of B within the geometry rectangle.
1123 - one of: left (0), centre (1), or right (2).
1124 - the default is left.
1125 string valign - when not distorting, set the vertical alignment of
1126 B within the geometry rectangle.
1127 - one of: top (0), middle (1), or bottom (2).
1128 - the default is top.
1129 string luma - the luma map file name. If not supplied, a dissolve.
1130 double softness - only when using a luma map, how soft to make the
1131 edges between A and B. 0.0 = no softness. 1.0 =
1133 Any property starting with "luma." is passed to the non-PGM luma
1136 Deprecated Properties
1138 string start - a geometry specification as X/Y:WxH[!][:mix]
1139 - X, Y, W, H are assumed to pixel units unless they
1141 - '!' is a shortcut to specify distort, see below.
1142 - mix is always a 2 digit percentage, defaults to 100.
1143 - default is "85%/5%:10%x10%"
1144 string end - the ending size and position.
1145 string key[F] - X/Y:WxH[:mix] - set a key frame for geometry between
1146 the in and out. F is a frame number and can be
1147 negative to make it relative to the out point.
1155 Assumes lower field first during field rendering.
1161 A generic dissolve and wipe transition processor.
1166 from how it uses a grayscale "map" file. As the luma value varies
1167 over time, a threshold filter is applied to the map to determine
1168 what parts of frame A vs. frame B to show. It reads PGM files
1169 up to 16 bits! Alternatively, it can use the first frame from any
1170 producer that outputs yuv, but it will be limited to the luma
1171 gamut of 220 values.
1172 This performs field-based rendering unless the A frame property
1173 "progressive" or "consumer_progressive" or the transition property
1174 "progressive" is set to 1.
1176 Constructor Argument
1178 string resource - the luma map file name - either PGM or any other
1180 - If not supplied, a dissolve.
1182 Initialisation Properties
1186 string factory - The name of a factory service used as a non-PGM
1187 producer loader. The default is 'loader'.
1191 string resource - same as above
1192 double softness - only when using a luma map, how soft to make the
1193 edges between A and B. 0.0 = no softness. 1.0 =
1195 int reverse - reverse the direction of the transition.
1196 Any property starting with "producer." is passed to the non-PGM luma
1199 Read Only Properties
1209 Assumes lower field first output.
1215 An two stream audio mixer.
1217 Constructor Argument
1221 Initalisation Properties
1228 double start - the mix level to apply to the second frame.
1229 - any negative value causes an automatic crossfade from 0 to 1.
1230 double end - the ending value of the mix level. mix level will be interpolated
1231 from start to end over the in-out range.
1232 int reverse - set to 1 to reverse the direction of the mix.
1234 Read Only Properties
1244 Samples from the longer of the two frames are discarded.
1251 Apply zero or more filters to B frame as it is composited onto
1252 a region of the A frame. The "shape" of the region can be defined
1253 by the alpha channel of a third producer.
1255 Constructor Argument
1257 resource - a shape producer
1259 Initialisation Properties
1261 string resource - nothing is rectangle, "circle" is a pixbuf-
1262 generated SVG circle, anything else is loaded by the factory.
1263 string factory - the service that creates the shape producer.
1264 - the default is 'loader'.
1265 string filter[N] - one or more filters to apply. All filter
1266 properties are passed using the same filter "key"
1267 Any property starting with "composite." is passed to the
1268 encapsulated composite transition.
1270 Read Only Properties
1276 transition_composite
1290 Multiformat transcoding consumer.
1292 Constructor Argument
1294 string target - the filename to write to, e.g. test.mpeg.
1296 Initialisation Properties
1298 int buffer - the number of frames to buffer, minimum 1, default 25.
1299 string rescale - a rescale method, see the Filters/rescale.
1300 int progressive - indicates whether to use progressive or field-
1301 based rendering, default 0 (off).
1303 Read Only Properties
1321 Constructor Argument
1323 string target - the filename to write to, e.g. /dev/dv1394.
1325 Initialisation Properties
1327 int buffer - the number of frames to buffer, minimum 1, default 25.
1328 string rescale - a rescale method, see the Filters/rescale.
1332 int progressive - indicates whether to use progressive or field-
1333 based rendering, default 0 (off).
1335 Read Only Properties
1351 Simple DirectMedia Layer audio and video output module.
1353 Constructor Argument
1355 string video_standard - "PAL" (default), "NTSC", or "WxH"
1357 Initialisation Properties
1359 int buffer - the number of frames to buffer, minimum 1, default 25.
1360 string rescale - a rescale method, see the Filters/rescale.
1361 - Hint: "none" works very good with SDL output.
1365 double volume - audio level factor
1366 int video_off - if 1, disable video output
1367 int audio_off - if 1, disable audio output
1369 int progressive - indicates whether to use progressive or field-
1370 based rendering, default 0 (off).
1371 int audio_buffer - size of the sdl audio buffer (default: 1024)
1373 Read Only Properties
1379 libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
1389 Serialise the service network to XML.
1390 See docs/mlt-xml.txt for more information.
1392 Constructor Argument
1394 resource - the name of a file in which to store the XML.
1395 - stdout is default.
1397 Initialisation Properties
1399 string resource - same as above.
1407 Untested arbitrary nesting of multitracks and playlists.
1408 Property "id" is generated as service type followed by number if
1409 no property named "id" exists, but it fails to guarantee uniqueness.
projects / mlt / blob