c0742065e953e673af4a27ef59d166349fb89c7d
[melted] / docs / services.txt
1 Service Documentation
2
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
7
8
9 SERVICES
10 --------
11
12         Services marked as "(Proprietary)" are not distributed with the GPL version
13         of mlt.
14
15 Producers
16 ---------
17
18         avformat
19
20             Description
21
22                 ffmpeg libavformat based producer for video and audio.
23
24             Constructor Argument
25
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 
32                          and formats.
33                          
34             Details
35             
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.
40
41             Initialisation Properties
42
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)
45                 int in - in point
46                 int out - out point
47
48             Read Only Properties
49
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
55
56             Dependencies
57
58                 ffmpeg must be configured as --enable-shared and installed prior
59                 to compilation of mlt.
60
61             Known Bugs
62
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).
71
72         fezzik
73
74             Description
75
76                 A friendly giant that likes to rhyme and throw rocks
77
78             Constructor Argument
79
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.
84
85             Initialisation Properties
86
87                 int in - in point
88                 int out - out point
89                 + all producer initialising properties
90
91             Read Only Properties
92
93                 string resource - file location
94                 + all producer read only properties
95
96             Details
97
98                 This producer has two roles:
99
100                 1. it handles the mappings of all file names to the other
101                 producers;
102                 2. it attaches normalising filters (rescale, resize and resample)
103                 to the producers (when necessary).
104
105                 This producer simplifies many aspects of use. Essentially, it
106                 ensures that a consumer will receive images and audio precisely as
107                 they request them. 
108
109             Dependencies
110
111                 all.
112
113             Known Bugs
114
115                 None.
116
117         
118         colour
119         
120             Description
121             
122                 A simple colour generator.
123                 
124             Constructor Argument
125             
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,
129                          or blue.
130                        - The default colour is black.
131                        
132             Initialisation Properties
133             
134                 none
135                 
136             Read Only Properties
137             
138                 none
139                 
140             Dependencies
141             
142                 none
143                 
144             Known Bugs
145             
146                 none
147
148         
149         ffmpeg (DEPRECATED)
150
151             Description
152
153                 Test case pipe based producer for video and audio.
154
155             Constructor Argument
156
157                 'file'    - produce a/v from file
158                 v4l        - produce a/v from video4linux and dsp device
159
160             Initialisation Properties
161
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)
172                 int in - in point
173                 int out - out point
174                 double fps - output frames per second (default: 25)
175                 double aspect_ratio - aspect ratio of video
176
177             Read Only Properties
178
179                 string resource - file or "v4l"
180                 int end_of_clip - holds 1 when input is exhausted
181
182             Dependencies
183
184                 ffmpeg executable.
185
186             Known Bugs
187
188                 in point setting is broken.
189
190                 Implementation does not allow fast random access.
191
192         libdv
193
194             Description
195
196                 libdv based decoder for video and audio.
197
198             Constructor Argument
199
200                 'file'    - produce a/v from file
201
202             Initialisation Properties
203
204                 int in - in point
205                 int out - out point
206
207             Read Only Properties
208
209                 string resource - file location
210                 double fps - output frames per second
211                 int length - duration of resource (in frames)
212                 
213             Mutable Properties
214             
215                 string quality - one of "best," "fast" or anything else chooses
216                                  medium.
217
218             Dependencies
219
220                 libdv.
221
222             Known Bugs
223
224                 DVCPRO is incorrectly identified as 16:9 aspect ratio. You must use
225                 libdv from CVS or a post 0.101 release. 
226
227         mcdv (Proprietary)
228
229             Description
230
231                 MainConcept based dv decoder for video and audio.
232
233             Constructor Argument
234
235                 'file'    - produce a/v from file
236
237             Initialisation Properties
238
239                 int in - in point
240                 int out - out point
241
242             Read Only Properties
243
244                 string resource - file location
245                 double fps - output frames per second
246                 int length - duration of resource (in frames)
247
248             Dependencies
249
250                 MainConcept DV or DVCPRO SDK, libdv.
251                 "dv_sdk" installed parallel to mlt.
252
253             Known Bugs
254
255                 None
256
257         mcmpeg (Proprietary)
258
259             Description
260
261                 MainConcept based mpeg decoder for video and audio.
262
263             Constructor Argument
264
265                 'file'    - produce a/v from file
266
267             Initialisation Properties
268
269                 int in - in point
270                 int out - out point
271
272             Read Only Properties
273
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)
278                 
279             Dependencies
280
281                 MainConcept MPEG SDK.
282                 "mpeg_sdk_release" installed parallel to mlt.
283
284             Known Bugs
285
286                 None.
287
288         noise
289
290             Description
291
292                 White noise producer
293
294             Constructor Argument
295
296                 none
297
298             Initialisation Properties
299
300                 int in - in point
301                 int out - out point
302
303             Read Only Properties
304
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)
309                 
310             Dependencies
311
312                 none
313
314             Known Bugs
315
316                 none
317
318         pango
319
320             Description
321
322                 A title generator that uses the Pango international text layout
323                 and Freetype2 font renderer.
324
325             Constructor Argument
326
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-   &lt;, &gt;, &amp;
331                               
332             Details
333             
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.
339                 
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.
344
345             Initialisation Properties
346
347                 int in - in point
348                 int out - out point
349
350             Mutable Properties
351
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-   &lt;, &gt;, &amp;
356                 string fgcolour - an RGBA colour specification of the text 
357                                   (i.e. 0xrrggbbaa)
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.
370
371             Read Only Properties
372
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.
378
379             Dependencies
380
381                 libpango-1.0, libpangoft2-1.0, libfreetype, libgdk_pixbuf-2.0, 
382                 libglib-2.0, libgobject-2.0, libgmodule-2.0, libfontconfig.
383
384             Known Bugs
385
386                 The foreground and background Pango markup span attributes are not
387                 supported.
388                 Word wrapping is not supported.
389
390         pixbuf
391
392             Description
393
394                 A still graphics to video generator using gdk-pixbuf
395
396             Constructor Argument
397
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 
404                          discontinuity >100.
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
409                          for inigo commands.
410                          
411             Details
412             
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.
417
418             Initialisation Properties
419
420                 int in - in point
421                 int out - out point
422
423             Mutable Properties
424
425                 int ttl - how long (in frames) to repeat each picture in file 
426                           sequences. default is 25.
427
428             Read Only Properties
429
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.
435
436             Dependencies
437
438                 libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
439
440             Known Bugs
441
442                 XXX: in/out settings are incorrectly handled.
443
444         ppm
445         
446             Description
447
448                 Reads a stream of contiguous PPM images.
449                 
450             Constructor Argument
451
452                 command - a shell command to run something that produces ppm
453                           streams on stdout.
454                 
455             Initialisation Properties
456
457                 none
458                 
459             Read Only Properties
460
461                 string resource - the command
462                 
463             Dependencies
464
465                 none
466                 
467             Known Bugs
468
469                 Since it uses pipes, it is not compatible with bluefish.
470
471         westley
472
473             Description
474
475                 Construct a service network from an XML description.
476                 See docs/westley.txt.
477
478             Constructor Argument
479
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
490                       the westley service.
491                       
492             Read Only Properties
493
494                 string resource - file location
495
496             Dependencies
497
498                 libxml2
499
500             Known Bugs
501
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 
506                 segfault.
507
508         vorbis
509
510             Description
511
512                 OGG Vorbis file reader.
513
514             Constructor Argument
515
516                 'file' - file to use (only .ogg supported at the moment)
517
518             Initialisation Properties
519
520                 int in - in point
521                 int out - out point
522
523             Read Only Properties
524
525                 double fps - this is fixed at 25 for PAL currently
526
527             Dependencies
528
529                 libvorbisfile
530
531             Known Bugs
532
533                 Fixed frame size (PAL audio chunks).
534                 Doesn't cover ogg files with multiple, differing sections.
535
536 Filters
537 -------
538
539         brightness
540         
541             Description
542             
543                 Shift the luma component using a constant value.
544                 
545             Constructor Argument
546             
547                 start - the constant floating point numeric value to apply.
548                       - the default is 0.
549                 
550             Initialisation Properties
551             
552                 int in - in point
553                 int out - out point
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.
558                              
559             Read Only Properties
560             
561                 none
562                 
563             Dependencies
564             
565                 none
566                 
567             Known Bugs
568             
569                 Does not go completely to black or white.
570                 
571         
572         channelcopy
573         
574             Description
575             
576                 Copy audio from one channel to another channel.
577                 
578             Constructor Argument
579             
580                 to - the 0-indexed channel to copy into, default is 1.
581                 
582             Mutable Properties
583             
584                 int to - see above
585                 int from - the channel from which to copy, default is 0.
586                 
587             Dependencies
588             
589                 none
590                 
591             Known Bugs
592             
593                 none
594                 
595
596
597         deinterlace
598         
599             Description
600
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.
604             
605             Constructor Argument
606
607                 method - a string containing the deinterlace method: bob, weave,
608                          greedy, onefield, or linearblend. The default is
609                          linearblend.
610             
611             Initialisation Properties
612
613                 int in - in point
614                 int out - out point
615                 
616             Read Only Properties
617
618                 none
619             
620             Mutable Properties
621             
622                 string method
623                 
624             Details
625             
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.
629
630             Dependencies
631
632                 none
633                 
634             Known Bugs
635
636                 Not a bug, but it only provides fair quality.
637                 
638             
639         gamma
640         
641             Description
642
643                 Adjust image luma using a non-linear power-law curve
644                 
645             Constructor Argument
646
647                 gamma - a floating point value. The default is 1.0, or none.
648             
649             Initialisation Properties
650             
651                 int in - in point
652                 int out - out point
653
654             Mutable Properties
655
656                 double gamma - the exponential factor of the power-law curve
657                 
658             Dependencies
659
660                 none
661                 
662             Known Bugs
663
664                 none
665                 
666         
667         greyscale
668         
669             Description
670
671                 Convert colour image to greyscale
672                 
673             Constructor Argument
674
675                 none
676                 
677             Initialisation Properties
678             
679                 int in - in point
680                 int out - out point
681
682             Read Only Properties
683
684                 none
685                 
686             Dependencies
687
688                 none
689                 
690             Known Bugs
691
692                 none
693             
694         luma
695         
696             Description
697             
698                 Applies a luma transition between the current and next frames.
699                 Useful for transitions from a slideshow created using producer
700                 pixbuf.
701                 
702             Constructor Argument
703             
704                 file - a luma wipe
705                 
706             Initialisation Properties
707             
708                 int in - in point
709                 int out - out point
710                 
711             Read Only Properties
712             
713                 none
714                 
715             Mutable Properties
716             
717                 int period - how long to wait between success iterations of the
718                              transition. For best results set this to a multiple
719                              of ttl used in pixbuf. The default is 24.
720                              
721                 luma. - all properties beginning with "luma." are passed to the
722                         encapsulated luma transition. For example, luma.out controls
723                         the duration of the wipe.
724                 
725             Dependencies
726             
727                 transition_luma and its dependencies
728                 
729             Known Bugs
730             
731                 none
732             
733         
734         mirror
735         
736             Description
737             
738                 Provides various mirror and image reversing effects.
739
740             Constructor Argument
741             
742                 mirror - horizontal, vertical, diagonal, flip, flop
743                 
744             Initialisation Properties
745             
746                 int reverse - being 0 or 1
747                 int in - in point
748                 int out - out point
749                 
750             Read Only Properties
751             
752                 none
753                 
754             Mutable Properties
755             
756                 none
757
758             Dependencies
759             
760                 none
761                 
762             Known Bugs
763             
764                 none
765
766
767         obscure
768         
769             Description
770
771                 Obscuring filter.
772                 
773             Constructor Argument
774
775                 none
776                 
777             Initialisation Properties
778             
779                 string start - in the format X,Y:WxH[:PWxPY]
780                              - PWxPY is the size of the averaging region in pixels.
781                 string end - in the format X,Y:WxH[:PWxPY]
782                 int in - in point
783                 int out - out point
784
785             Read Only Properties
786
787                 none
788                 
789             Dependencies
790
791                 none
792
793             Known Bugs
794
795                 none
796
797         region
798         
799             Description
800             
801                 Apply one or filters to a region of the video image. The region
802                 can be shaped as well using the alpha channel of another producer.
803                 
804             Constructor Argument
805             
806                 resource - A file whose alpha channel will "shape"  the region.
807                      - The string "circle" is a shortcut but it requires pixbuf with
808                        the librsvg loader. The circle is automatically stretched
809                        to the region to create an ellipse.
810         
811             Initialisation Properties
812
813                 int in - in point
814                 int out - out point
815                 plus and region transition properties
816                 
817             Read Only Properties
818             
819                 see the region transition
820                 
821             Dependencies
822             
823                 transition_region
824                 
825             Known Bugs
826             
827                 "circle" is unpredictable in the absence of the librsvg pixbuf loader.
828                 
829
830         resample
831
832             Description
833
834                 Adjust an audio stream's sampling rate, and duplicate channels if 
835                 producer provides less than consumer requested.
836                 
837                 This filter is automatically invoked by Fezzik for the sake of
838                 normalisation over inputs and with the consumer.
839
840             Constructor Argument
841
842                 frequency - a numeric value for the new sample rate
843
844             Initialisation Properties
845
846                 int in - in point
847                 int out - out point
848
849             Mutable Properties
850
851                 int frequency - the target sample rate
852
853             Dependencies
854
855                 libresample
856
857             Known Bugs
858
859                 Assumes 2 channels during libsamplerate initialisation. Untested
860                 with >2 channels.
861
862         rescale
863
864             Description
865
866                 Scale the producer video frame size to match the consumer.
867                 This filter is automatically invoked by Fezzik in order to normalise
868                 sample aspect ratio.
869
870             Constructor Argument
871
872                 interpolation - the rescaling method, one of:
873                     nearest (lowest quality, fastest),
874                     tiles,
875                     bilinear (default; good quality, moderate speed),
876                     hyper (best quality, slowest).
877
878             Initialisation Properties
879
880                 int in - in point
881                 int out - out point
882
883             Mutable Properties
884
885                 string interpolation - see constructor argument above
886
887                 If a property "consumer_aspect_ratio" exists on the frame, then
888                 rescaler normalises the producer's aspect ratio and maximises the
889                 size of the frame, but may not produce the consumer's requested
890                 dimension. Therefore, this option works best in conjunction with the
891                 resize filter. This behavior can be disabled by another service by
892                 either removing the property, setting it to zero, or setting
893                 frame property "distort" to 1.
894
895             Dependencies
896
897                 libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
898
899             Known Bugs
900
901                 none
902
903         resize
904         
905             Description
906
907                 Image scaling and padding and field order adjustment.
908                     
909             Details
910             
911                 Normally resize is used to pad the producer's
912                 output to what the consumer has requested after an upstream rescale
913                 filter first scales the image to maximise usage of the image area.
914                 This filter also adjusts the field order to lower field first
915                 if the frame property "top_field_first" has been set to 1.
916                 Therefore, when done, it sets the top_field_first to 0.
917                 This filter is automatically invoked by Fezzik as part of image
918                 sample aspect ratio normalisation.
919                 
920             Constructor Argument
921
922                 scale - "affine" to use affine transform scaling, otherwise
923                          center and pad.
924                 
925             Initialisation Properties
926             
927                 int in - in point
928                 int out - out point
929
930             Read Only Properties
931
932                 none
933                 
934             Dependencies
935
936                 none
937                 
938             Known Bugs
939
940                 Assumes lower field first output.
941
942         volume
943
944             Description
945
946                 Adjust an audio stream's volume level
947                 
948             Constructor Argument
949
950                 gain - a string containing one of:
951                      - a floating point value of the gain adjustment
952                      - a numeric value with the suffix "dB" to adjust in terms of decibels
953                      - "normalise" to normalise the volume to the target amplitude -12dBFS
954                 
955             Initialisation Properties
956             
957                 int in - in point
958                 int out - out point
959                 int window - the number of video frames over which to smooth normalisation.
960                              defaults to 75.
961
962             Mutable Properties
963
964                 string gain - same as constructor argument above
965
966                 string normalise - normalise the volume to the amplitude:
967                     - a numeric value with the suffix "dB" to set amplitude in decibels
968                     - a floating point value of the relative volume
969                     - an unspecified value uses the default -12dBFS
970
971                 string limiter - limit all samples above:
972                     - a numeric value with the suffix "dB"
973                     - a floating point value ( dB = 20 * log10(x) )
974                     - an unspecified value uses the default -6dBFS
975
976                 double max_gain - a floating point or decibel value of the maximum gain that
977                     can be applied during normalisation.
978                     - an unspecified value uses the default 20dB
979
980                 string end - a gain value just like the gain property above.
981                              This causes the gain to be interpolated from 'gain' to 'end'
982                              over the duration.
983
984                 int window - the size of the normalising smoothing buffer in video frame units.
985                            - the smoothing buffer prevents erratic gain changes.
986                            - the default value is 75 video frames. 
987
988                 gain can be applied as a factor to the normalise amplitude!
989                 
990             Dependencies
991
992                 none
993                 
994             Known Bugs
995
996                 none
997
998         watermark
999
1000             Description
1001
1002                 Add a watermark to the frames.
1003
1004             Constructor Argument
1005
1006                 resource - the producer to use (ie: a .png)
1007
1008             Initialisation Properties
1009
1010                 string resource - the producer to use
1011                 string factory - producer required for the resource ('fezzik')
1012                 string geometry - composite geometry
1013                 string distort - control scaling
1014                 int in - in point
1015                 int out - out point
1016
1017             Mutable Properties
1018
1019                 none
1020
1021             Dependencies
1022
1023                 mlt core modules and optionally, fezzik
1024
1025             Known Bugs
1026
1027                 none
1028
1029 Transitions
1030 -----------
1031
1032         composite
1033         
1034             Description
1035
1036                 A key-framable alpha-channel compositor for two frames.
1037                 
1038             Details
1039             
1040                 Performs dissolves and luma wipes in addition to alpha compositing.
1041                 
1042                 By default, the aspect ratio of the B frame is respected and the
1043                 size portion of the geometry specification simply defines a 
1044                 bounding rectangle.
1045             
1046                 This performs field-based rendering unless the A frame property
1047                 "progressive" or "consumer_progressive" or the transition property
1048                 "progressive" is set to 1.
1049                 
1050             Constructor Argument
1051
1052                 string start - a geometry specification as X,Y:WxH[!][:mix]
1053                              - X, Y, W, H are assumed to pixel units unless they
1054                                have the suffix '%'
1055                              - '!' is a shortcut to specify distort, see below.
1056                              - mix is always a 2 digit percentage, defaults to 100.
1057                              - default is "85%,5%:10%x10%"
1058
1059             Initialisation Properties
1060                 
1061                 string end - the ending size and position.
1062                 string key[F] - X,Y:WxH[:mix] - set a key frame for geometry between
1063                                 the in and out. F is a frame number and can be
1064                                 negative to make it relative to the out point.
1065                 int in - in point
1066                 int out - out point
1067                 string factory - The name of a factory service used as a non-PGM
1068                                  producer loader. The default is fezzik.
1069         
1070             Read Only Properties
1071
1072                 none
1073
1074             Mutable Properties
1075                 
1076                 int progressive - set to 1 to disable field-based rendering.
1077                 string distort - when set, causes the B frame image to fill the WxH
1078                                  completely with no regard to B's aspect ratio.
1079                 string halign - when not distorting, set the horizontal alignment
1080                                 of B within the geometry rectangle.
1081                               - one of: left (0), centre (1), or right (2).
1082                               - the default is left.
1083                 string valign - when not distorting, set the vertical alignment of 
1084                                 B within the geometry rectangle.
1085                               - one of: top (0), middle (1), or bottom (2).
1086                               - the default is top.
1087                 string luma - the luma map file name. If not supplied, a dissolve.
1088                 double softness - only when using a luma map, how soft to make the
1089                                   edges between A and B. 0.0 = no softness. 1.0 =
1090                                   too soft.
1091                 Any property starting with "luma." is passed to the non-PGM luma
1092                     producer.
1093
1094             Dependencies
1095
1096                 none
1097             
1098             Known Bugs
1099
1100                 Assumes lower field first during field rendering.
1101
1102         luma
1103         
1104             Description
1105
1106                 A generic dissolve and wipe transition processor.
1107
1108             Details
1109
1110                 luma gets its name
1111                 from how it uses a grayscale "map" file. As the luma value varies
1112                 over time, a threshold filter is applied to the map to determine
1113                 what parts of frame A vs. frame B to show. It reads PGM files
1114                 up to 16 bits! Alternatively, it can use the first frame from any
1115                 producer that outputs yuv, but it will be limited to the luma
1116                 gamut of 220 values.
1117                 This performs field-based rendering unless the A frame property
1118                 "progressive" or "consumer_progressive" or the transition property
1119                 "progressive" is set to 1.
1120             
1121             Constructor Argument
1122
1123                 string resource - the luma map file name - either PGM or any other
1124                                   producable video. 
1125                                 - If not supplied, a dissolve.
1126
1127             Initialisation Properties
1128             
1129                 int in - in point
1130                 int out - out point
1131                 string factory - The name of a factory service used as a non-PGM
1132                                  producer loader. The default is Fezzik.
1133
1134             Mutable Properties
1135
1136                 string resource - same as above
1137                 double softness - only when using a luma map, how soft to make the
1138                                   edges between A and B. 0.0 = no softness. 1.0 =
1139                                   too soft.
1140                 int reverse - reverse the direction of the transition.
1141                 Any property starting with "producer." is passed to the non-PGM luma
1142                     producer.
1143                 
1144             Read Only Properties
1145
1146                 none
1147                 
1148             Dependencies
1149
1150                 none
1151                 
1152             Known Bugs
1153                 
1154                 Assumes lower field first output.
1155
1156         mix
1157
1158             Description
1159
1160                 An two stream audio mixer.
1161
1162             Constructor Argument
1163
1164                 start - see below
1165
1166             Initalisation Properties
1167
1168                 int in - in point
1169                 int out - out point
1170
1171             Mutable Properties
1172
1173                 double start - the mix level to apply to the second frame.
1174                              - any negative value causes an automatic crossfade from 0 to 1.
1175                 double end - the ending value of the mix level. mix level will be interpolated
1176                              from start to end over the in-out range.
1177                 int reverse - set to 1 to reverse the direction of the mix.
1178
1179             Read Only Properties
1180
1181                 none
1182
1183             Dependencies
1184
1185                 none
1186
1187             Known Bugs
1188
1189                 Samples from the longer of the two frames are discarded.
1190                 
1191         
1192         region
1193         
1194             Description
1195             
1196                 Apply zero or more filters to B frame as it is composited onto
1197                 a region of the A frame. The "shape" of the region can be defined
1198                 by the alpha channel of a third producer.
1199                 
1200             Constructor Argument
1201
1202                 resource - a shape producer
1203             
1204             Initialisation Properties
1205             
1206                 string resource - nothing is rectangle, "circle" is a pixbuf-
1207                     generated SVG circle, anything else is loaded by the factory.
1208                 string factory - the service that creates the shape producer.
1209                                - the default is fezzik.
1210                 string filter[N] - one or more filters to apply. All filter
1211                                    properties are passed using the same filter "key"
1212                 Any property starting with "composite." is passed to the 
1213                     encapsulated composite transition.
1214                 
1215             Read Only Properties
1216             
1217                 none
1218                 
1219             Dependencies
1220             
1221                 transition_composite
1222                 
1223             Known Bugs
1224             
1225                 none
1226                 
1227
1228 Consumers
1229 ---------
1230
1231         avformat
1232         
1233             Description
1234             
1235                 Multiformat transcoding consumer.
1236
1237             Constructor Argument
1238
1239                 string target - the filename to write to, e.g. test.mpeg.
1240
1241             Initialisation Properties
1242             
1243                 int buffer - the number of frames to buffer, minimum 1, default 25.
1244                 string rescale - a rescale method, see the Filters/rescale.
1245                 int progressive - indicates whether to use progressive or field-
1246                                   based rendering, default 0 (off).
1247                 
1248             Read Only Properties
1249             
1250                 none
1251                 
1252             Dependencies
1253             
1254                 libavformat
1255                 
1256             Known Bugs
1257             
1258                 Plenty.
1259
1260         bluefish (Proprietary)
1261         
1262             Description
1263
1264                 BlueFish444 audio and video output module.
1265             
1266             Constructor Argument
1267
1268                 card - a numeric card id starting at 1, default is 1.
1269                 
1270             Initialisation Properties
1271
1272                 string standard - "PAL" (default) or "NTSC"
1273                                 - default is based upon MLT_NORMALISATION 
1274                                   environment variable, which defaults to PAL.
1275                 int frames - the number of DMA video frames. default is 8.
1276                              minimum is 2. maximum on my system is 11.
1277                 int buffer - the number of frames to buffer within MLT, minimum 1, 
1278                              default 25.
1279                 string rescale - a rescale method, see the Filters/rescale.
1280                 
1281             Read Only Properties
1282
1283                 none
1284             
1285             Dependencies
1286
1287                 BlueVelvet SDK installed parallel to mlt in "bluefish."
1288             
1289             Known Bugs
1290
1291                 Does not work with any service that uses pipes!
1292                 
1293                 If mlt crashes, you might need to reload the BlueDriver kernel 
1294                 module due to unreleased DMA buffers.
1295                 
1296                 Only supports 2 channel audio at the moment.
1297             
1298         libdv
1299         
1300             Description
1301             
1302                 libdv dv producer.
1303
1304             Constructor Argument
1305
1306                 string target - the filename to write to, e.g. /dev/dv1394.
1307
1308             Initialisation Properties
1309             
1310                 int buffer - the number of frames to buffer, minimum 1, default 25.
1311                 string rescale - a rescale method, see the Filters/rescale.
1312             
1313             Mutable Properties
1314             
1315                 int progressive - indicates whether to use progressive or field-
1316                                   based rendering, default 0 (off).
1317                 
1318             Read Only Properties
1319             
1320                 none
1321                 
1322             Dependencies
1323             
1324                 libdv
1325                 
1326             Known Bugs
1327             
1328                 none
1329
1330         sdl
1331
1332             Description
1333
1334                 Simple DirectMedia Layer audio and video output module.
1335                 
1336             Constructor Argument
1337
1338                 string video_standard - "PAL" (default), "NTSC", or "WxH"
1339                 
1340             Initialisation Properties
1341             
1342                 int buffer - the number of frames to buffer, minimum 1, default 25.
1343                 string rescale - a rescale method, see the Filters/rescale.
1344                                - Hint: "none" works very good with SDL output.
1345                 
1346             Mutable Properties
1347
1348                 double volume - audio level factor
1349                 int video_off - if 1, disable video output
1350                 int audio_off - if 1, disable audio output
1351                 int scale_overlay - if 1, resample video from source pixel aspect
1352                                     ratio to square pixels.
1353                 int progressive - indicates whether to use progressive or field-
1354                                   based rendering, default 0 (off).
1355                 
1356             Read Only Properties
1357
1358                 none
1359                 
1360             Dependencies
1361
1362                 libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
1363             
1364             Known Bugs
1365
1366                 none
1367
1368         westley
1369
1370             Description
1371
1372                 Serialise the service network to XML.
1373                 See docs/westley.txt for more information.
1374                 
1375             Constructor Argument
1376
1377                 resource - the name of a file in which to store the XML.
1378                           - stdout is default.
1379                 
1380             Initialisation Properties
1381
1382                 string resource - same as above.
1383                 
1384             Dependencies
1385             
1386                 libxml2
1387                 
1388             Known Bugs
1389
1390                 Untested arbitrary nesting of multitracks and playlists.
1391                 Property "id" is generated as service type followed by number if
1392                 no property named "id" exists, but it fails to guarantee uniqueness.