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 Test case pipe based producer for video and audio.
157 'file' - produce a/v from file
158 v4l - produce a/v from video4linux and dsp device
160 Initialisation Properties
162 string video_type - "file" or "v4l"
163 string video_file - file or v4l device
164 string video_size - WxH of video to produce (default: "")
165 int video_loop - loop video until audio exhausted (default: 0)
166 string audio_type - "file" or "dsp"
167 string audio_file - file or dsp device
168 int audio_rate - audio frequency (default: 48000)
169 int audio_channels - audio channels (default: 2)
170 int audio_track - audio track to use (default: 0)
171 int audio_loop - loop audio until video exhausted (default: 0)
174 double fps - output frames per second (default: 25)
175 double aspect_ratio - aspect ratio of video
179 string resource - file or "v4l"
180 int end_of_clip - holds 1 when input is exhausted
188 in point setting is broken.
190 Implementation does not allow fast random access.
196 libdv based decoder for video and audio.
200 'file' - produce a/v from file
202 Initialisation Properties
209 string resource - file location
210 double fps - output frames per second
211 int length - duration of resource (in frames)
215 string quality - one of "best," "fast" or anything else chooses
224 DVCPRO is incorrectly identified as 16:9 aspect ratio. You must use
225 libdv from CVS or a post 0.101 release.
231 MainConcept based dv decoder for video and audio.
235 'file' - produce a/v from file
237 Initialisation Properties
244 string resource - file location
245 double fps - output frames per second
246 int length - duration of resource (in frames)
250 MainConcept DV or DVCPRO SDK, libdv.
251 "dv_sdk" installed parallel to mlt.
261 MainConcept based mpeg decoder for video and audio.
265 'file' - produce a/v from file
267 Initialisation Properties
274 string resource - file location
275 double fps - output frames per second
276 double aspect_ratio - sample aspect ratio of video
277 int length - duration of resource (in frames)
281 MainConcept MPEG SDK.
282 "mpeg_sdk_release" installed parallel to mlt.
298 Initialisation Properties
305 string resource - file location
306 double fps - output frames per second
307 double aspect_ratio - sample aspect ratio of video
308 int length - duration of resource (in frames)
322 A title generator that uses the Pango international text layout
323 and Freetype2 font renderer.
327 string file - a text file containing Pango markup, see:
328 http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
329 - requires xml-like encoding special chars from:
330 <, >, & -to- <, >, &
334 Supplying a filename with extension ".txt" causes the Fezzik
335 producer to load with pango. If the filename begins with "+" the
336 pango producer interprets the filename as pango text. This is a
337 shortcut to embed titles in inigo commands. For westley, it is
338 recommended that you embed the title text in the property value.
340 Pango has builtin scaling. It will rescale the originally rendered
341 title to whatever the consumer requests. Therefore, it will lose
342 its aspect ratio if so requested, and it is up to the consumer to
343 request a proper width and height that maintains the image aspect.
345 Initialisation Properties
352 string markup - a string containing Pango markup see:
353 http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
354 - requires xml-like encoding special chars from:
355 <, >, & -to- <, >, &
356 string fgcolour - an RGBA colour specification of the text
358 string bgcolour - an RGBA colour of the background rectangle
359 string align - paragraph alignment: left, centre, right
360 - also, numbers 0, 1 and 2 can be used respectively.
361 int pad - the number of pixels to pad the background rectangle
362 beyond edges of text. default 0.
363 string markup - see constructor argument
364 string text - non-markup string in UTF-8 encoding (can contain
365 markup chars un-encoded)
366 string font - the default typeface to use when not using markup.
367 default "Sans 48". FreeType2 renders at 72 dpi.
368 string encoding - the text encoding type of the input if not UTF-8.
369 - see 'iconv --list' for a list of possible inputs.
373 string resource - the text/markup file or "pango" if no file.
374 int real_width - the original, unscaled width of the rendered title.
375 int real_height - the original, unscaled height of the title.
376 int width - the last requested scaled image width.
377 int height - the last requested scaled image height.
381 libpango-1.0, libpangoft2-1.0, libfreetype, libgdk_pixbuf-2.0,
382 libglib-2.0, libgobject-2.0, libgmodule-2.0, libfontconfig.
386 The foreground and background Pango markup span attributes are not
388 Word wrapping is not supported.
394 A still graphics to video generator using gdk-pixbuf
398 'file' - The name of a graphics file loadable by
399 a gdk-pixbuf loader. see /usr/lib/gdk-pixbuf/loaders
400 definitely png, jpeg, tiff, pnm, and xpm
401 - If "%" in filename, the filename is used with sprintf
402 generate a filename from a counter for multi-file/flipbook
403 animation. The file sequence ends when numeric
405 - If filename contains "/.all.", suffix with an extension to
406 load all pictures with matching extension from a directory.
407 - If filename contains the string "<svg", then pixbuf tries
408 to load the filename as inline SVG XML, which is convenient
413 Pixbuf has builtin scaling. It will rescale the originally rendered
414 title to whatever the consumer requests. Therefore, it will lose
415 its aspect ratio if so requested, and it is up to the consumer to
416 request a proper width and height that maintains the image aspect.
418 Initialisation Properties
425 int ttl - how long (in frames) to repeat each picture in file
426 sequences. default is 25.
430 string resource - file location. See Constructor Argument above.
431 int real_width - the original, unscaled width of the rendered title.
432 int real_height - the original, unscaled height of the title.
433 int width - the last requested scaled image width.
434 int height - the last requested scaled image height.
438 libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
442 XXX: in/out settings are incorrectly handled.
448 Reads a stream of contiguous PPM images.
452 command - a shell command to run something that produces ppm
455 Initialisation Properties
461 string resource - the command
469 Since it uses pipes, it is not compatible with bluefish.
475 Construct a service network from an XML description.
476 See docs/westley.txt.
480 URL - an XML text file containing westley XML (schema/DTD pending)
481 - Since westley files can be parameterised, the URL syntax is:
482 {file-name}[?{param-name}{'='|':'}{param-value}[&{param-name}{'='|':'}{param-value}...]]
483 A colon is allowed instead of an equal sign to pacify inigo,
484 who tokenises anything with an equal sign as a property
485 setting. Also, when running inigo from the shell, beware of
486 the '?' and shell filename expansion. You can surround the URL
487 with single quotations to prevent expansion. Finally, fezzik
488 will fail to match the filename when you use parameters, so
489 preface the url with 'westley:' to force fezzik to load with
494 string resource - file location
502 Non-referenced producers and playlists are not destroyed until the
503 network is destroyed.
504 A referenced producer or playlist must appear before the reference.
505 A filter that occurs before a producer has been defined causes a
512 OGG Vorbis file reader.
516 'file' - file to use (only .ogg supported at the moment)
518 Initialisation Properties
525 double fps - this is fixed at 25 for PAL currently
533 Fixed frame size (PAL audio chunks).
534 Doesn't cover ogg files with multiple, differing sections.
543 Shift the luma component using a constant value.
547 start - the constant floating point numeric value to apply.
550 Initialisation Properties
554 double start - see Constructor Argument above.
555 double end - the ending adjustment value. the filter interpolates
556 between the start and end adjustments over the
557 duration of the effect.
569 Does not go completely to black or white.
576 Copy audio from one channel to another channel.
580 to - the 0-indexed channel to copy into, default is 1.
585 int from - the channel from which to copy, default is 0.
601 Deinterlace a frame consisting of two fields using bob, weave,
602 greedy, one-field, and linear blend methods. This code is
603 appropriated from the Xine XV video output plugin.
607 method - a string containing the deinterlace method: bob, weave,
608 greedy, onefield, or linearblend. The default is
611 Initialisation Properties
626 If the frame properties "progressive" or "consumer_progressive"
627 are non-zero, then the filter is not applied. Also, if applied,
628 this sets the frame property "progressive" to 1.
636 Not a bug, but it only provides fair quality.
643 Adjust image luma using a non-linear power-law curve
647 gamma - a floating point value. The default is 1.0, or none.
649 Initialisation Properties
656 double gamma - the exponential factor of the power-law curve
671 Convert colour image to greyscale
677 Initialisation Properties
698 Scale the producer video frame size to match the consumer.
699 This filter is designed for use as a Fezzik normaliser.
703 interpolation - the rescaling method, one of:
704 nearest (lowest quality, fastest),
706 bilinear (default; good quality, moderate speed),
707 hyper (best quality, slowest).
709 Initialisation Properties
716 string interpolation - see constructor argument above
718 If a property "consumer_aspect_ratio" exists on the frame, then
719 rescaler normalises the producer's aspect ratio and maximises the
720 size of the frame, but may not produce the consumer's requested
721 dimension. Therefore, this option works best in conjunction with the
722 resize filter. This behavior can be disabled by another service by
723 either removing the property, setting it to zero, or setting
724 frame property "distort" to 1.
728 libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
738 Applies a luma transition between the current and next frames.
739 Useful for transitions from a slideshow created using producer
746 Initialisation Properties
757 int period - how long to wait between success iterations of the
758 transition. For best results set this to a multiple
759 of ttl used in pixbuf. The default is 24.
761 luma. - all properties beginning with "luma." are passed to the
762 encapsulated luma transition. For example, luma.out controls
763 the duration of the wipe.
767 transition_luma and its dependencies
777 Scale the producer video frame size to match the consumer.
778 This filter is designed for use as a Fezzik normaliser.
782 interpolation - the rescaling method, one of:
783 nearest (lowest quality, fastest),
784 bilinear (default; good quality, moderate speed),
785 hyper (best quality, slowest).
787 Initialisation Properties
794 string interpolation - see constructor argument above
796 If a property "consumer_aspect_ratio" exists on the frame, then
797 rescaler normalises the producer's aspect ratio and maximises the
798 size of the frame, but may not produce the consumer's requested
799 dimension. Therefore, this option works best in conjunction with the
800 resize filter. This behavior can be disabled by another service by
801 either removing the property, setting it to zero, or setting
802 frame property "distort" to 1.
806 the mainconcept rescaling sdk.
816 Provides various mirror and image reversing effects.
820 mirror - horizontal, vertical, diagonal, flip, flop
822 Initialisation Properties
824 int reverse - being 0 or 1
855 Initialisation Properties
857 string start - in the format X,Y:WxH[:PWxPY]
858 - PWxPY is the size of the averaging region in pixels.
859 string end - in the format X,Y:WxH[:PWxPY]
879 Apply one or more filters to a region of the video image. The region
880 can be shaped as well using the alpha channel of another producer.
884 resource - A file whose alpha channel will "shape" the region.
885 - The string "circle" is a shortcut but it requires pixbuf with
886 the librsvg loader. The circle is automatically stretched
887 to the region to create an ellipse.
889 Initialisation Properties
893 plus and region transition properties
897 see the region transition
905 "circle" is unpredictable in the absence of the librsvg pixbuf loader.
912 Adjust an audio stream's sampling rate, and duplicate channels if
913 producer provides less than consumer requested.
915 This filter is automatically invoked by Fezzik for the sake of
916 normalisation over inputs and with the consumer.
920 frequency - a numeric value for the new sample rate
922 Initialisation Properties
929 int frequency - the target sample rate
937 Assumes 2 channels during libsamplerate initialisation. Untested
944 Scale the producer video frame size to match the consumer.
945 This filter is designed for use as a Fezzik normaliser.
951 Initialisation Properties
958 If a property "consumer_aspect_ratio" exists on the frame, then
959 rescaler normalises the producer's aspect ratio and maximises the
960 size of the frame, but may not produce the consumer's requested
961 dimension. Therefore, this option works best in conjunction with the
962 resize filter. This behavior can be disabled by another service by
963 either removing the property, setting it to zero, or setting
964 frame property "distort" to 1.
972 none but... it only implements a nearest neighbour scaling - it is
973 used as the base class for the gtkrescale and mcrescale filters.
979 Image scaling and padding and field order adjustment.
983 Normally resize is used to pad the producer's
984 output to what the consumer has requested after an upstream rescale
985 filter first scales the image to maximise usage of the image area.
986 This filter also adjusts the field order to lower field first
987 if the frame property "top_field_first" has been set to 1.
988 Therefore, when done, it sets the top_field_first to 0.
989 This filter is automatically invoked by Fezzik as part of image
990 sample aspect ratio normalisation.
994 scale - "affine" to use affine transform scaling, otherwise
997 Initialisation Properties
1002 Read Only Properties
1012 Assumes lower field first output.
1018 Adjust an audio stream's volume level
1020 Constructor Argument
1022 gain - a string containing one of:
1023 - a floating point value of the gain adjustment
1024 - a numeric value with the suffix "dB" to adjust in terms of decibels
1025 - "normalise" to normalise the volume to the target amplitude -12dBFS
1027 Initialisation Properties
1031 int window - the number of video frames over which to smooth normalisation.
1036 string gain - same as constructor argument above
1038 string normalise - normalise the volume to the amplitude:
1039 - a numeric value with the suffix "dB" to set amplitude in decibels
1040 - a floating point value of the relative volume
1041 - an unspecified value uses the default -12dBFS
1043 string limiter - limit all samples above:
1044 - a numeric value with the suffix "dB"
1045 - a floating point value ( dB = 20 * log10(x) )
1046 - an unspecified value uses the default -6dBFS
1048 double max_gain - a floating point or decibel value of the maximum gain that
1049 can be applied during normalisation.
1050 - an unspecified value uses the default 20dB
1052 string end - a gain value just like the gain property above.
1053 This causes the gain to be interpolated from 'gain' to 'end'
1056 int window - the size of the normalising smoothing buffer in video frame units.
1057 - the smoothing buffer prevents erratic gain changes.
1058 - the default value is 75 video frames.
1060 gain can be applied as a factor to the normalise amplitude!
1074 Add a watermark to the frames.
1076 Constructor Argument
1078 resource - the producer to use (ie: a .png)
1080 Initialisation Properties
1082 string resource - the producer to use
1083 string factory - producer required for the resource ('fezzik')
1084 string geometry - composite geometry
1085 string distort - control scaling
1095 mlt core modules and optionally, fezzik
1108 A key-framable alpha-channel compositor for two frames.
1112 Performs dissolves and luma wipes in addition to alpha compositing.
1114 By default, the aspect ratio of the B frame is respected and the
1115 size portion of the geometry specification simply defines a
1118 This performs field-based rendering unless the A frame property
1119 "progressive" or "consumer_progressive" or the transition property
1120 "progressive" is set to 1.
1122 Constructor Argument
1124 string start - a geometry specification as X,Y:WxH[!][:mix]
1125 - X, Y, W, H are assumed to pixel units unless they
1127 - '!' is a shortcut to specify distort, see below.
1128 - mix is always a 2 digit percentage, defaults to 100.
1129 - default is "85%,5%:10%x10%"
1131 Initialisation Properties
1133 string end - the ending size and position.
1134 string key[F] - X,Y:WxH[:mix] - set a key frame for geometry between
1135 the in and out. F is a frame number and can be
1136 negative to make it relative to the out point.
1139 string factory - The name of a factory service used as a non-PGM
1140 producer loader. The default is fezzik.
1142 Read Only Properties
1148 int progressive - set to 1 to disable field-based rendering.
1149 string distort - when set, causes the B frame image to fill the WxH
1150 completely with no regard to B's aspect ratio.
1151 string halign - when not distorting, set the horizontal alignment
1152 of B within the geometry rectangle.
1153 - one of: left (0), centre (1), or right (2).
1154 - the default is left.
1155 string valign - when not distorting, set the vertical alignment of
1156 B within the geometry rectangle.
1157 - one of: top (0), middle (1), or bottom (2).
1158 - the default is top.
1159 string luma - the luma map file name. If not supplied, a dissolve.
1160 double softness - only when using a luma map, how soft to make the
1161 edges between A and B. 0.0 = no softness. 1.0 =
1163 Any property starting with "luma." is passed to the non-PGM luma
1172 Assumes lower field first during field rendering.
1178 A generic dissolve and wipe transition processor.
1183 from how it uses a grayscale "map" file. As the luma value varies
1184 over time, a threshold filter is applied to the map to determine
1185 what parts of frame A vs. frame B to show. It reads PGM files
1186 up to 16 bits! Alternatively, it can use the first frame from any
1187 producer that outputs yuv, but it will be limited to the luma
1188 gamut of 220 values.
1189 This performs field-based rendering unless the A frame property
1190 "progressive" or "consumer_progressive" or the transition property
1191 "progressive" is set to 1.
1193 Constructor Argument
1195 string resource - the luma map file name - either PGM or any other
1197 - If not supplied, a dissolve.
1199 Initialisation Properties
1203 string factory - The name of a factory service used as a non-PGM
1204 producer loader. The default is Fezzik.
1208 string resource - same as above
1209 double softness - only when using a luma map, how soft to make the
1210 edges between A and B. 0.0 = no softness. 1.0 =
1212 int reverse - reverse the direction of the transition.
1213 Any property starting with "producer." is passed to the non-PGM luma
1216 Read Only Properties
1226 Assumes lower field first output.
1232 An two stream audio mixer.
1234 Constructor Argument
1238 Initalisation Properties
1245 double start - the mix level to apply to the second frame.
1246 - any negative value causes an automatic crossfade from 0 to 1.
1247 double end - the ending value of the mix level. mix level will be interpolated
1248 from start to end over the in-out range.
1249 int reverse - set to 1 to reverse the direction of the mix.
1251 Read Only Properties
1261 Samples from the longer of the two frames are discarded.
1268 Apply zero or more filters to B frame as it is composited onto
1269 a region of the A frame. The "shape" of the region can be defined
1270 by the alpha channel of a third producer.
1272 Constructor Argument
1274 resource - a shape producer
1276 Initialisation Properties
1278 string resource - nothing is rectangle, "circle" is a pixbuf-
1279 generated SVG circle, anything else is loaded by the factory.
1280 string factory - the service that creates the shape producer.
1281 - the default is fezzik.
1282 string filter[N] - one or more filters to apply. All filter
1283 properties are passed using the same filter "key"
1284 Any property starting with "composite." is passed to the
1285 encapsulated composite transition.
1287 Read Only Properties
1293 transition_composite
1307 Multiformat transcoding consumer.
1309 Constructor Argument
1311 string target - the filename to write to, e.g. test.mpeg.
1313 Initialisation Properties
1315 int buffer - the number of frames to buffer, minimum 1, default 25.
1316 string rescale - a rescale method, see the Filters/rescale.
1317 int progressive - indicates whether to use progressive or field-
1318 based rendering, default 0 (off).
1320 Read Only Properties
1332 bluefish (Proprietary)
1336 BlueFish444 audio and video output module.
1338 Constructor Argument
1340 card - a numeric card id starting at 1, default is 1.
1342 Initialisation Properties
1344 string standard - "PAL" (default) or "NTSC"
1345 - default is based upon MLT_NORMALISATION
1346 environment variable, which defaults to PAL.
1347 int frames - the number of DMA video frames. default is 8.
1348 minimum is 2. maximum on my system is 11.
1349 int buffer - the number of frames to buffer within MLT, minimum 1,
1351 string rescale - a rescale method, see the Filters/rescale.
1353 Read Only Properties
1359 BlueVelvet SDK installed parallel to mlt in "bluefish."
1363 Does not work with any service that uses pipes!
1365 If mlt crashes, you might need to reload the BlueDriver kernel
1366 module due to unreleased DMA buffers.
1368 Only supports 2 channel audio at the moment.
1376 Constructor Argument
1378 string target - the filename to write to, e.g. /dev/dv1394.
1380 Initialisation Properties
1382 int buffer - the number of frames to buffer, minimum 1, default 25.
1383 string rescale - a rescale method, see the Filters/rescale.
1387 int progressive - indicates whether to use progressive or field-
1388 based rendering, default 0 (off).
1390 Read Only Properties
1406 Simple DirectMedia Layer audio and video output module.
1408 Constructor Argument
1410 string video_standard - "PAL" (default), "NTSC", or "WxH"
1412 Initialisation Properties
1414 int buffer - the number of frames to buffer, minimum 1, default 25.
1415 string rescale - a rescale method, see the Filters/rescale.
1416 - Hint: "none" works very good with SDL output.
1420 double volume - audio level factor
1421 int video_off - if 1, disable video output
1422 int audio_off - if 1, disable audio output
1423 int scale_overlay - if 1, resample video from source pixel aspect
1424 ratio to square pixels.
1425 int progressive - indicates whether to use progressive or field-
1426 based rendering, default 0 (off).
1428 Read Only Properties
1434 libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
1444 Serialise the service network to XML.
1445 See docs/westley.txt for more information.
1447 Constructor Argument
1449 resource - the name of a file in which to store the XML.
1450 - stdout is default.
1452 Initialisation Properties
1454 string resource - same as above.
1462 Untested arbitrary nesting of multitracks and playlists.
1463 Property "id" is generated as service type followed by number if
1464 no property named "id" exists, but it fails to guarantee uniqueness.