3 Copyright (C) 2004 Ushodaya Enterprises Limited
4 Authors: Charles Yates <charles.yates@pandora.be>
5 Dan Dennedy <dan@dennedy.org>
6 Last Revision: 2004-03-20
12 Services marked as "(Proprietary)" are not distributed with the GPL version
22 ffmpeg libavformat based producer for video and audio.
26 'file' - a filename specification or URL in the form:
27 [{protocol}|{format}]:{resource}[?{format-parameter}[&{format-parameter}...]]
28 For example, video4linux:/dev/video1?width:320&height:240
29 Note: on the bash command line, & must be escaped as '\&'.
30 Also, note the use of ':' instead of '=' for parameters.
31 Use 'ffmpeg -formats' to see a list of supported protocols
36 Format parameters only appear to be useful with 'video4linux' or
37 'audio_device' formats. For 'video4linux' the parameters are
38 width, height, frame_rate, frame_rate_base, and standard (ntsc|pal).
39 For 'audio_device' the parameters are channels and sample_rate.
41 Initialisation Properties
43 int video_index - index of video stream to use (-1 is off)
44 int audio_index - index of audio stream to use (-1 is off)
50 string resource - file location
51 double fps - this is fixed at 25 for PAL currently
52 double source_fps - the framerate of the resource
53 double aspect_ratio - sample aspect ratio of the resource
54 - this is determined on every frame read
58 ffmpeg must be configured as --enable-shared and installed prior
59 to compilation of mlt.
63 Audio sync discrepancy with some content.
64 Not all libavformat supported formats are seekable.
65 Ogg Vorbis is currently broken.
66 MPEG seeking is inaccurate - doesn't seek to i-frames so you may
67 get junk for a few frames.
68 RAW DV seeking not supported.
69 Fails to play beyond first frame of video of sources with PTS not
70 starting at 0 (video4linux).
76 A friendly giant that likes to rhyme and throw rocks
80 'file' - a filename specification:
81 [{mlt-service}:]{resource} | {mlt-service}
82 - can also be the name of a producer service that can
83 accept the resource specified post construction.
85 Initialisation Properties
89 + all producer initialising properties
93 string resource - file location
94 + all producer read only properties
98 This producer has two roles:
100 1. it handles the mappings of all file names to the other
102 2. it attaches normalising filters (rescale, resize and resample)
103 to the producers (when necessary).
105 This producer simplifies many aspects of use. Essentially, it
106 ensures that a consumer will receive images and audio precisely as
122 A simple colour generator.
126 colour - A colour value is a hexadecimal representation of RGB plus
127 alpha channel as 0xrrggbbaa.
128 - Also colours can be the words: white, black, red, green,
130 - The default colour is black.
132 Initialisation Properties
153 libdv based decoder for video and audio.
157 'file' - produce a/v from file
159 Initialisation Properties
166 string resource - file location
167 double fps - output frames per second
168 int length - duration of resource (in frames)
172 string quality - one of "best," "fast" or anything else chooses
181 DVCPRO is incorrectly identified as 16:9 aspect ratio. You must use
182 libdv from CVS or a post 0.101 release.
188 MainConcept based dv decoder for video and audio.
192 'file' - produce a/v from file
194 Initialisation Properties
201 string resource - file location
202 double fps - output frames per second
203 int length - duration of resource (in frames)
207 MainConcept DV or DVCPRO SDK, libdv.
208 "dv_sdk" installed parallel to mlt.
218 MainConcept based mpeg decoder for video and audio.
222 'file' - produce a/v from file
224 Initialisation Properties
231 string resource - file location
232 double fps - output frames per second
233 double aspect_ratio - sample aspect ratio of video
234 int length - duration of resource (in frames)
238 MainConcept MPEG SDK.
239 "mpeg_sdk_release" installed parallel to mlt.
255 Initialisation Properties
262 string resource - file location
263 double fps - output frames per second
264 double aspect_ratio - sample aspect ratio of video
265 int length - duration of resource (in frames)
279 A title generator that uses the Pango international text layout
280 and Freetype2 font renderer.
284 string file - a text file containing Pango markup, see:
285 http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
286 - requires xml-like encoding special chars from:
287 <, >, & -to- <, >, &
291 Supplying a filename with extension ".txt" causes the Fezzik
292 producer to load with pango. If the filename begins with "+" the
293 pango producer interprets the filename as pango text. This is a
294 shortcut to embed titles in inigo commands. For westley, it is
295 recommended that you embed the title text in the property value.
297 Pango has builtin scaling. It will rescale the originally rendered
298 title to whatever the consumer requests. Therefore, it will lose
299 its aspect ratio if so requested, and it is up to the consumer to
300 request a proper width and height that maintains the image aspect.
302 Initialisation Properties
309 string markup - a string containing Pango markup see:
310 http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
311 - requires xml-like encoding special chars from:
312 <, >, & -to- <, >, &
313 string fgcolour - an RGBA colour specification of the text
315 string bgcolour - an RGBA colour of the background rectangle
316 string align - paragraph alignment: left, centre, right
317 - also, numbers 0, 1 and 2 can be used respectively.
318 int pad - the number of pixels to pad the background rectangle
319 beyond edges of text. default 0.
320 string markup - see constructor argument
321 string text - non-markup string in UTF-8 encoding (can contain
322 markup chars un-encoded)
323 string font - the default typeface to use when not using markup.
324 default "Sans 48". FreeType2 renders at 72 dpi.
325 string encoding - the text encoding type of the input if not UTF-8.
326 - see 'iconv --list' for a list of possible inputs.
330 string resource - the text/markup file or "pango" if no file.
331 int real_width - the original, unscaled width of the rendered title.
332 int real_height - the original, unscaled height of the title.
333 int width - the last requested scaled image width.
334 int height - the last requested scaled image height.
338 libpango-1.0, libpangoft2-1.0, libfreetype, libgdk_pixbuf-2.0,
339 libglib-2.0, libgobject-2.0, libgmodule-2.0, libfontconfig.
343 The foreground and background Pango markup span attributes are not
345 Word wrapping is not supported.
351 A still graphics to video generator using gdk-pixbuf
355 'file' - The name of a graphics file loadable by
356 a gdk-pixbuf loader. see /usr/lib/gdk-pixbuf/loaders
357 definitely png, jpeg, tiff, pnm, and xpm
358 - If "%" in filename, the filename is used with sprintf
359 generate a filename from a counter for multi-file/flipbook
360 animation. The file sequence ends when numeric
362 - If filename contains "/.all.", suffix with an extension to
363 load all pictures with matching extension from a directory.
364 - If filename contains the string "<svg", then pixbuf tries
365 to load the filename as inline SVG XML, which is convenient
370 Pixbuf has builtin scaling. It will rescale the originally rendered
371 title to whatever the consumer requests. Therefore, it will lose
372 its aspect ratio if so requested, and it is up to the consumer to
373 request a proper width and height that maintains the image aspect.
375 Initialisation Properties
382 int ttl - how long (in frames) to repeat each picture in file
383 sequences. default is 25.
387 string resource - file location. See Constructor Argument above.
388 int real_width - the original, unscaled width of the rendered title.
389 int real_height - the original, unscaled height of the title.
390 int width - the last requested scaled image width.
391 int height - the last requested scaled image height.
395 libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
399 XXX: in/out settings are incorrectly handled.
405 Reads a stream of contiguous PPM images.
409 command - a shell command to run something that produces ppm
412 Initialisation Properties
418 string resource - the command
426 Since it uses pipes, it is not compatible with bluefish.
432 Construct a service network from an XML description.
433 See docs/westley.txt.
437 URL - an XML text file containing westley XML (schema/DTD pending)
438 - Since westley files can be parameterised, the URL syntax is:
439 {file-name}[?{param-name}{'='|':'}{param-value}[&{param-name}{'='|':'}{param-value}...]]
440 A colon is allowed instead of an equal sign to pacify inigo,
441 who tokenises anything with an equal sign as a property
442 setting. Also, when running inigo from the shell, beware of
443 the '?' and shell filename expansion. You can surround the URL
444 with single quotations to prevent expansion. Finally, fezzik
445 will fail to match the filename when you use parameters, so
446 preface the url with 'westley:' to force fezzik to load with
451 string resource - file location
459 Non-referenced producers and playlists are not destroyed until the
460 network is destroyed.
461 A referenced producer or playlist must appear before the reference.
462 A filter that occurs before a producer has been defined causes a
469 OGG Vorbis file reader.
473 'file' - file to use (only .ogg supported at the moment)
475 Initialisation Properties
482 double fps - this is fixed at 25 for PAL currently
490 Fixed frame size (PAL audio chunks).
491 Doesn't cover ogg files with multiple, differing sections.
500 Shift the luma component using a constant value.
504 start - the constant floating point numeric value to apply.
507 Initialisation Properties
511 double start - see Constructor Argument above.
512 double end - the ending adjustment value. the filter interpolates
513 between the start and end adjustments over the
514 duration of the effect.
526 Does not go completely to black or white.
533 Copy audio from one channel to another channel.
537 to - the 0-indexed channel to copy into, default is 1.
542 int from - the channel from which to copy, default is 0.
558 Deinterlace a frame consisting of two fields using bob, weave,
559 greedy, one-field, and linear blend methods. This code is
560 appropriated from the Xine XV video output plugin.
564 method - a string containing the deinterlace method: bob, weave,
565 greedy, onefield, or linearblend. The default is
568 Initialisation Properties
583 If the frame properties "progressive" or "consumer_progressive"
584 are non-zero, then the filter is not applied. Also, if applied,
585 this sets the frame property "progressive" to 1.
593 Not a bug, but it only provides fair quality.
600 Adjust image luma using a non-linear power-law curve
604 gamma - a floating point value. The default is 1.0, or none.
606 Initialisation Properties
613 double gamma - the exponential factor of the power-law curve
628 Convert colour image to greyscale
634 Initialisation Properties
655 Scale the producer video frame size to match the consumer.
656 This filter is designed for use as a Fezzik normaliser.
660 interpolation - the rescaling method, one of:
661 nearest (lowest quality, fastest),
663 bilinear (default; good quality, moderate speed),
664 hyper (best quality, slowest).
666 Initialisation Properties
673 string interpolation - see constructor argument above
675 If a property "consumer_aspect_ratio" exists on the frame, then
676 rescaler normalises the producer's aspect ratio and maximises the
677 size of the frame, but may not produce the consumer's requested
678 dimension. Therefore, this option works best in conjunction with the
679 resize filter. This behavior can be disabled by another service by
680 either removing the property, setting it to zero, or setting
681 frame property "distort" to 1.
685 libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
695 Applies a luma transition between the current and next frames.
696 Useful for transitions from a slideshow created using producer
703 Initialisation Properties
714 int period - how long to wait between success iterations of the
715 transition. For best results set this to a multiple
716 of ttl used in pixbuf. The default is 24.
718 luma. - all properties beginning with "luma." are passed to the
719 encapsulated luma transition. For example, luma.out controls
720 the duration of the wipe.
724 transition_luma and its dependencies
734 Scale the producer video frame size to match the consumer.
735 This filter is designed for use as a Fezzik normaliser.
739 interpolation - the rescaling method, one of:
740 nearest (lowest quality, fastest),
741 bilinear (default; good quality, moderate speed),
742 hyper (best quality, slowest).
744 Initialisation Properties
751 string interpolation - see constructor argument above
753 If a property "consumer_aspect_ratio" exists on the frame, then
754 rescaler normalises the producer's aspect ratio and maximises the
755 size of the frame, but may not produce the consumer's requested
756 dimension. Therefore, this option works best in conjunction with the
757 resize filter. This behavior can be disabled by another service by
758 either removing the property, setting it to zero, or setting
759 frame property "distort" to 1.
763 the mainconcept rescaling sdk.
773 Provides various mirror and image reversing effects.
777 mirror - horizontal, vertical, diagonal, flip, flop
779 Initialisation Properties
781 int reverse - being 0 or 1
812 Initialisation Properties
814 string start - in the format X,Y:WxH[:PWxPY]
815 - PWxPY is the size of the averaging region in pixels.
816 string end - in the format X,Y:WxH[:PWxPY]
836 Apply one or more filters to a region of the video image. The region
837 can be shaped as well using the alpha channel of another producer.
841 resource - A file whose alpha channel will "shape" the region.
842 - The string "circle" is a shortcut but it requires pixbuf with
843 the librsvg loader. The circle is automatically stretched
844 to the region to create an ellipse.
846 Initialisation Properties
850 plus and region transition properties
854 see the region transition
862 "circle" is unpredictable in the absence of the librsvg pixbuf loader.
869 Adjust an audio stream's sampling rate, and duplicate channels if
870 producer provides less than consumer requested.
872 This filter is automatically invoked by Fezzik for the sake of
873 normalisation over inputs and with the consumer.
877 frequency - a numeric value for the new sample rate
879 Initialisation Properties
886 int frequency - the target sample rate
894 Assumes 2 channels during libsamplerate initialisation. Untested
901 Scale the producer video frame size to match the consumer.
902 This filter is designed for use as a Fezzik normaliser.
908 Initialisation Properties
915 If a property "consumer_aspect_ratio" exists on the frame, then
916 rescaler normalises the producer's aspect ratio and maximises the
917 size of the frame, but may not produce the consumer's requested
918 dimension. Therefore, this option works best in conjunction with the
919 resize filter. This behavior can be disabled by another service by
920 either removing the property, setting it to zero, or setting
921 frame property "distort" to 1.
929 none but... it only implements a nearest neighbour scaling - it is
930 used as the base class for the gtkrescale and mcrescale filters.
936 Image scaling and padding and field order adjustment.
940 Normally resize is used to pad the producer's
941 output to what the consumer has requested after an upstream rescale
942 filter first scales the image to maximise usage of the image area.
943 This filter also adjusts the field order to lower field first
944 if the frame property "top_field_first" has been set to 1.
945 Therefore, when done, it sets the top_field_first to 0.
946 This filter is automatically invoked by Fezzik as part of image
947 sample aspect ratio normalisation.
951 scale - "affine" to use affine transform scaling, otherwise
954 Initialisation Properties
969 Assumes lower field first output.
975 Adjust an audio stream's volume level
976 - based on the 'normalize' utility
980 gain - a string containing one of:
981 - a floating point value of the gain adjustment
982 - a numeric value with the suffix "dB" to adjust in terms of decibels
983 - "normalise" to normalise the volume to the target amplitude -12dBFS
985 Initialisation Properties
989 int window - the number of video frames over which to smooth normalisation.
994 string gain - same as constructor argument above
996 string normalise - normalise the volume to the amplitude:
997 - a numeric value with the suffix "dB" to set amplitude in decibels
998 - a floating point value of the relative volume
999 - an unspecified value uses the default -12dBFS
1001 string limiter - limit all samples above:
1002 - a numeric value with the suffix "dB"
1003 - a floating point value ( dB = 20 * log10(x) )
1004 - an unspecified value uses the default -6dBFS
1006 double max_gain - a floating point or decibel value of the maximum gain that
1007 can be applied during normalisation.
1008 - an unspecified value uses the default 20dB
1010 string end - a gain value just like the gain property above.
1011 This causes the gain to be interpolated from 'gain' to 'end'
1014 int window - the size of the normalising smoothing buffer in video frame units.
1015 - the smoothing buffer prevents erratic gain changes.
1016 - the default value is 75 video frames.
1018 gain can be applied as a factor to the normalise amplitude!
1032 Add a watermark to the frames.
1034 Constructor Argument
1036 resource - the producer to use (ie: a .png)
1038 Initialisation Properties
1040 string resource - the producer to use
1041 string factory - producer required for the resource ('fezzik')
1042 string geometry - composite geometry
1043 string distort - control scaling
1053 mlt core modules and optionally, fezzik
1066 A key-framable alpha-channel compositor for two frames.
1070 Performs dissolves and luma wipes in addition to alpha compositing.
1072 By default, the aspect ratio of the B frame is respected and the
1073 size portion of the geometry specification simply defines a
1076 This performs field-based rendering unless the A frame property
1077 "progressive" or "consumer_progressive" or the transition property
1078 "progressive" is set to 1.
1080 Constructor Argument
1082 string start - a geometry specification as X,Y:WxH[!][:mix]
1083 - X, Y, W, H are assumed to pixel units unless they
1085 - '!' is a shortcut to specify distort, see below.
1086 - mix is always a 2 digit percentage, defaults to 100.
1087 - default is "85%,5%:10%x10%"
1089 Initialisation Properties
1091 string end - the ending size and position.
1092 string key[F] - X,Y:WxH[:mix] - set a key frame for geometry between
1093 the in and out. F is a frame number and can be
1094 negative to make it relative to the out point.
1097 string factory - The name of a factory service used as a non-PGM
1098 producer loader. The default is fezzik.
1100 Read Only Properties
1106 int progressive - set to 1 to disable field-based rendering.
1107 string distort - when set, causes the B frame image to fill the WxH
1108 completely with no regard to B's aspect ratio.
1109 string halign - when not distorting, set the horizontal alignment
1110 of B within the geometry rectangle.
1111 - one of: left (0), centre (1), or right (2).
1112 - the default is left.
1113 string valign - when not distorting, set the vertical alignment of
1114 B within the geometry rectangle.
1115 - one of: top (0), middle (1), or bottom (2).
1116 - the default is top.
1117 string luma - the luma map file name. If not supplied, a dissolve.
1118 double softness - only when using a luma map, how soft to make the
1119 edges between A and B. 0.0 = no softness. 1.0 =
1121 Any property starting with "luma." is passed to the non-PGM luma
1130 Assumes lower field first during field rendering.
1136 A generic dissolve and wipe transition processor.
1141 from how it uses a grayscale "map" file. As the luma value varies
1142 over time, a threshold filter is applied to the map to determine
1143 what parts of frame A vs. frame B to show. It reads PGM files
1144 up to 16 bits! Alternatively, it can use the first frame from any
1145 producer that outputs yuv, but it will be limited to the luma
1146 gamut of 220 values.
1147 This performs field-based rendering unless the A frame property
1148 "progressive" or "consumer_progressive" or the transition property
1149 "progressive" is set to 1.
1151 Constructor Argument
1153 string resource - the luma map file name - either PGM or any other
1155 - If not supplied, a dissolve.
1157 Initialisation Properties
1161 string factory - The name of a factory service used as a non-PGM
1162 producer loader. The default is Fezzik.
1166 string resource - same as above
1167 double softness - only when using a luma map, how soft to make the
1168 edges between A and B. 0.0 = no softness. 1.0 =
1170 int reverse - reverse the direction of the transition.
1171 Any property starting with "producer." is passed to the non-PGM luma
1174 Read Only Properties
1184 Assumes lower field first output.
1190 An two stream audio mixer.
1192 Constructor Argument
1196 Initalisation Properties
1203 double start - the mix level to apply to the second frame.
1204 - any negative value causes an automatic crossfade from 0 to 1.
1205 double end - the ending value of the mix level. mix level will be interpolated
1206 from start to end over the in-out range.
1207 int reverse - set to 1 to reverse the direction of the mix.
1209 Read Only Properties
1219 Samples from the longer of the two frames are discarded.
1226 Apply zero or more filters to B frame as it is composited onto
1227 a region of the A frame. The "shape" of the region can be defined
1228 by the alpha channel of a third producer.
1230 Constructor Argument
1232 resource - a shape producer
1234 Initialisation Properties
1236 string resource - nothing is rectangle, "circle" is a pixbuf-
1237 generated SVG circle, anything else is loaded by the factory.
1238 string factory - the service that creates the shape producer.
1239 - the default is fezzik.
1240 string filter[N] - one or more filters to apply. All filter
1241 properties are passed using the same filter "key"
1242 Any property starting with "composite." is passed to the
1243 encapsulated composite transition.
1245 Read Only Properties
1251 transition_composite
1265 Multiformat transcoding consumer.
1267 Constructor Argument
1269 string target - the filename to write to, e.g. test.mpeg.
1271 Initialisation Properties
1273 int buffer - the number of frames to buffer, minimum 1, default 25.
1274 string rescale - a rescale method, see the Filters/rescale.
1275 int progressive - indicates whether to use progressive or field-
1276 based rendering, default 0 (off).
1278 Read Only Properties
1290 bluefish (Proprietary)
1294 BlueFish444 audio and video output module.
1296 Constructor Argument
1298 card - a numeric card id starting at 1, default is 1.
1300 Initialisation Properties
1302 string standard - "PAL" (default) or "NTSC"
1303 - default is based upon MLT_NORMALISATION
1304 environment variable, which defaults to PAL.
1305 int frames - the number of DMA video frames. default is 8.
1306 minimum is 2. maximum on my system is 11.
1307 int buffer - the number of frames to buffer within MLT, minimum 1,
1309 string rescale - a rescale method, see the Filters/rescale.
1311 Read Only Properties
1317 BlueVelvet SDK installed parallel to mlt in "bluefish."
1321 Does not work with any service that uses pipes!
1323 If mlt crashes, you might need to reload the BlueDriver kernel
1324 module due to unreleased DMA buffers.
1326 Only supports 2 channel audio at the moment.
1334 Constructor Argument
1336 string target - the filename to write to, e.g. /dev/dv1394.
1338 Initialisation Properties
1340 int buffer - the number of frames to buffer, minimum 1, default 25.
1341 string rescale - a rescale method, see the Filters/rescale.
1345 int progressive - indicates whether to use progressive or field-
1346 based rendering, default 0 (off).
1348 Read Only Properties
1364 Simple DirectMedia Layer audio and video output module.
1366 Constructor Argument
1368 string video_standard - "PAL" (default), "NTSC", or "WxH"
1370 Initialisation Properties
1372 int buffer - the number of frames to buffer, minimum 1, default 25.
1373 string rescale - a rescale method, see the Filters/rescale.
1374 - Hint: "none" works very good with SDL output.
1378 double volume - audio level factor
1379 int video_off - if 1, disable video output
1380 int audio_off - if 1, disable audio output
1381 int scale_overlay - if 1, resample video from source pixel aspect
1382 ratio to square pixels.
1383 int progressive - indicates whether to use progressive or field-
1384 based rendering, default 0 (off).
1386 Read Only Properties
1392 libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
1402 Serialise the service network to XML.
1403 See docs/westley.txt for more information.
1405 Constructor Argument
1407 resource - the name of a file in which to store the XML.
1408 - stdout is default.
1410 Initialisation Properties
1412 string resource - same as above.
1420 Untested arbitrary nesting of multitracks and playlists.
1421 Property "id" is generated as service type followed by number if
1422 no property named "id" exists, but it fails to guarantee uniqueness.