23fbf4bc829761f63474f3ca55e5ec0954c894ac
[melted] / docs / services.txt
1 SERVICES
2 --------
3
4 Services marked as "(Proprietary)" are not distributed with the GPL version
5 of mlt.
6
7 Producers
8 ---------
9
10         avformat
11
12                 Description
13
14                         ffmpeg libavformat based producer for video and audio.
15
16                 Constructor Argument
17
18                         'file' - producer a/v from file
19
20                 Initialisation Properties
21
22                         int video_index - index of video stream to use (-1 is off)
23                         int audio_index - index of audio stream to use (-1 is off)
24                         int in - in point
25                         int out - out point
26
27                 Read Only Properties
28
29                         string resource - file location
30                         double fps - this is fixed at 25 for PAL currently
31                         double source_fps - the framerate of the resource
32                         double aspect_ratio - sample aspect ratio of the resource
33                                             - this is determined on every frame read
34
35                 Dependencies
36
37                         ffmpeg must be configured as --enable-shared and installed prior
38                         to compilation of mlt.
39
40                 Known Bugs
41
42                         Audio sync discrepancy with some content.
43                         Not all libavformat supported formats are seekable.
44                         Ogg Vorbis is currently broken.
45                         MPEG seeking is inaccurate - doesn't seek to i-frames so you may
46                         get junk for a few frames.
47                         RAW DV seeking not supported.
48
49         fezzik
50
51                 Description
52
53                         A friendly giant that likes to rhyme and throw rocks
54
55                 Constructor Argument
56
57                         'file'  - produce a/v from file
58                                 - can also be the name of a producer service that can
59                                           accept the resource specified post construction.
60
61                 Initialisation Properties
62
63                         int in - in point
64                         int out - out point
65                         + all producer initialising properties
66
67                 Read Only Properties
68
69                         string resource - file location
70                         + all producer read only properties
71
72                 Details
73
74                         This producer is has two roles:
75
76                         1. it handles the mappings of all file names to the other
77                         producers;
78                         2. it attaches normalising filters (rescale, resize and resample)
79                         to the producers (when necessary).
80
81                         This producer simplifies many aspects of use. Essentially, it
82                         ensures that a consumer will receive images and audio precisely as
83                         they request them. 
84
85                 Dependencies
86
87                         all.
88
89                 Known Bugs
90
91                         None.
92
93         
94         colour
95         
96                 Description
97                 
98                         A simple colour generator.
99                         
100                 Constructor Argument
101                 
102                         colour - A colour value is a hexadecimal representation of RGB plus
103                                  alpha channel as 0xrrggbbaa.
104                                - Also colours can be the words: white, black, red, green,
105                                  or blue.
106                                - The default colour is black.
107                                    
108                 Initialisation Properties
109                 
110                         none
111                         
112                 Read Only Properties
113                 
114                         none
115                         
116                 Dependencies
117                 
118                         none
119                         
120                 Known Bugs
121                 
122                         none
123
124         
125         ffmpeg (DEPRECATED)
126
127                 Description
128
129                         Test case pipe based producer for video and audio.
130
131                 Constructor Argument
132
133                         'file'  - produce a/v from file
134                         v4l             - produce a/v from video4linux and dsp device
135
136                 Initialisation Properties
137
138                         string video_type - "file" or "v4l"
139                         string video_file - file or v4l device
140                         string video_size - WxH of video to produce (default: "")
141                         int video_loop - loop video until audio exhausted (default: 0)
142                         string audio_type - "file" or "dsp"
143                         string audio_file - file or dsp device
144                         int audio_rate - audio frequency (default: 48000)
145                         int audio_channels - audio channels (default: 2)
146                         int audio_track - audio track to use (default: 0)
147                         int audio_loop - loop audio until video exhausted (default: 0)
148                         int in - in point
149                         int out - out point
150                         double fps - output frames per second (default: 25)
151                         double aspect_ratio - aspect ratio of video
152
153                 Read Only Properties
154
155                         string resource - file or "v4l"
156                         int end_of_clip - holds 1 when input is exhausted
157
158                 Dependencies
159
160                         ffmpeg executable.
161
162                 Known Bugs
163
164                         in point setting is broken.
165
166                         Implementation does not allow fast random access.
167
168         libdv
169
170                 Description
171
172                         libdv based decoder for video and audio.
173
174                 Constructor Argument
175
176                         'file'  - produce a/v from file
177
178                 Initialisation Properties
179
180                         int in - in point
181                         int out - out point
182
183                 Read Only Properties
184
185                         string resource - file location
186                         double fps - output frames per second
187                         int length - duration of resource (in frames)
188                         
189                 Mutable Properties
190                 
191                         string quality - one of "best," "fast" or anything else chooses
192                                          medium.
193
194                 Dependencies
195
196                         libdv.
197
198                 Known Bugs
199
200                         DVCPRO is incorrectly identified as 16:9 aspect ratio. You must use
201                         libdv from CVS or a post 0.101 release. 
202
203         mcdv (Proprietary)
204
205                 Description
206
207                         MainConcept based dv decoder for video and audio.
208
209                 Constructor Argument
210
211                         'file'  - produce a/v from file
212
213                 Initialisation Properties
214
215                         int in - in point
216                         int out - out point
217
218                 Read Only Properties
219
220                         string resource - file location
221                         double fps - output frames per second
222                         int length - duration of resource (in frames)
223
224                 Dependencies
225
226                         MainConcept DV or DVCPRO SDK, libdv.
227                         "dv_sdk" installed parallel to mlt.
228
229                 Known Bugs
230
231                         None
232
233         mcmpeg (Proprietary)
234
235                 Description
236
237                         MainConcept based mpeg decoder for video and audio.
238
239                 Constructor Argument
240
241                         'file'  - produce a/v from file
242
243                 Initialisation Properties
244
245                         int in - in point
246                         int out - out point
247
248                 Read Only Properties
249
250                         string resource - file location
251                         double fps - output frames per second
252                         double aspect_ratio - sample aspect ratio of video
253                         int length - duration of resource (in frames)
254                         
255                 Dependencies
256
257                         MainConcept MPEG SDK.
258                         "mpeg_sdk_release" installed parallel to mlt.
259
260                 Known Bugs
261
262                         None.
263
264         pango
265
266                 Description
267
268                         A title generator that uses the Pango international text layout
269                         and Freetype2 font renderer.
270
271                 Constructor Argument
272
273                         string file - a text file containing Pango markup, see:
274                         http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
275                                     - requires xml-like encoding special chars from: 
276                                       <, >, &   -to-   &lt;, &gt;, &amp;
277                                                   
278                 Details
279                 
280                         Supplying a filename with extension ".txt" causes the Fezzik 
281                         producer to load with pango. If the filename begins with "+" the 
282                         pango producer interprets the filename as pango text. This is a
283                         shortcut to embed titles in inigo commands. For westley, it is 
284                         recommended that you embed the title text in the property value.
285                         If you need to embed Pango markup in a westley XML file, then
286                         enclose the value inside "<![CDATA[ ... ]]>".
287                         
288                         Pango has builtin scaling. It will rescale the originally rendered
289                         title to whatever the consumer requests. Therefore, it will lose
290                         its aspect ratio if so requested, and it is up to the consumer to
291                         request a proper width and height that maintains the image aspect.
292
293                 Initialisation Properties
294
295                         int in - in point
296                         int out - out point
297
298                 Mutable Properties
299
300                         string markup - a UTF-8 string containing Pango markup see:
301                         http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
302                                       - requires xml-like encoding special chars from: 
303                                         <, >, &   -to-   &lt;, &gt;, &amp;
304                         string fgcolour - an RGBA colour specification of the text 
305                                           (i.e. 0xrrggbbaa)
306                         string bgcolour - an RGBA colour of the background rectangle
307                         string align - paragraph alignment: left, centre, right
308                                      - also, numbers 0, 1 and 2 can be used respectively.
309                         int pad - the number of pixels to pad the background rectangle 
310                                   beyond edges of text. default 0.
311                         string markup - see constructor argument
312                         string text - non-markup string in UTF-8 encoding (can contain 
313                                       markup chars un-encoded)
314                         string font - the default typeface to use when not using markup.
315                                       default "Sans 48". FreeType2 renders at 72 dpi.
316
317                 Read Only Properties
318
319                         string resource - the text/markup file or "pango" if no file.
320                         int real_width - the original, unscaled width of the rendered title.
321                         int real_height - the original, unscaled height of the title.
322                         int width - the last requested scaled image width.
323                         int height - the last requested scaled image height.
324
325                 Dependencies
326
327                         libpango-1.0, libpangoft2-1.0, libfreetype, libgdk_pixbuf-2.0, 
328                         libglib-2.0, libgobject-2.0, libgmodule-2.0, libfontconfig.
329
330                 Known Bugs
331
332                         The foreground and background Pango markup span attributes are not
333                         supported.
334                         Word wrapping is not supported.
335
336         pixbuf
337
338                 Description
339
340                         A still graphics to video generator using gdk-pixbuf
341
342                 Constructor Argument
343
344                         'file' - The name of a graphics file loadable by
345                                  a gdk-pixbuf loader. see /usr/lib/gdk-pixbuf/loaders
346                                  definitely png, jpeg, tiff, pnm, and xpm
347                                - If "%" in filename, the filename is used with sprintf
348                                  generate a filename from a counter for multi-file/flipbook 
349                                  animation. The file sequence ends when numeric 
350                                  discontinuity >100.
351                                - If filename contains "/.all.", suffix with an extension to 
352                                  load all pictures with matching extension from a directory.
353                                - If filename contains the string "<svg", then pixbuf tries
354                                  to load the filename as inline SVG XML, which is convenient
355                                  for inigo commands. For westley XML, set the resource
356                                  property value with inline XML embedded using a CDATA node
357                                  ("<![CDATA[ ... ]]>").
358                                          
359                 Details
360                 
361                         Pixbuf has builtin scaling. It will rescale the originally rendered
362                         title to whatever the consumer requests. Therefore, it will lose
363                         its aspect ratio if so requested, and it is up to the consumer to
364                         request a proper width and height that maintains the image aspect.
365
366                 Initialisation Properties
367
368                         int in - in point
369                         int out - out point
370
371                 Mutable Properties
372
373                         int ttl - how long (in frames) to repeat each picture in file 
374                                   sequences. default is 25.
375
376                 Read Only Properties
377
378                         string resource - file location. See Constructor Argument above.
379                         int real_width - the original, unscaled width of the rendered title.
380                         int real_height - the original, unscaled height of the title.
381                         int width - the last requested scaled image width.
382                         int height - the last requested scaled image height.
383
384                 Dependencies
385
386                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
387
388                 Known Bugs
389
390                         XXX: in/out settings are incorrectly handled.
391
392         ppm
393         
394                 Description
395
396                         Reads a stream of contiguous PPM images.
397                         
398                 Constructor Argument
399
400                         command - a shell command to run something that produces ppm
401                                   streams on stdout.
402                         
403                 Initialisation Properties
404
405                         none
406                         
407                 Read Only Properties
408
409                         string resource - the command
410                         
411                 Dependencies
412
413                         none
414                         
415                 Known Bugs
416
417                         Since it uses pipes, it is not compatible with bluefish.
418
419         westley
420
421                 Description
422
423                         Construct a service network from an XML description.
424                         See docs/westley.txt.
425
426                 Constructor Argument
427
428                         file - an XML text file containing westley XML (schema pending)
429
430                 Read Only Properties
431
432                         string resource - file location
433
434                 Dependencies
435
436                         libxml2
437
438                 Known Bugs
439
440                         Non-referenced producers and playlists are not destroyed until the 
441                         network is destroyed.
442                         A referenced producer or playlist must appear before the reference.
443                         A filter that occurs before a producer has been defined causes a 
444                         segfault.
445
446         vorbis
447
448                 Description
449
450                         OGG Vorbis file reader.
451
452                 Constructor Argument
453
454                         'file' - file to use (only .ogg supported at the moment)
455
456                 Initialisation Properties
457
458                         int in - in point
459                         int out - out point
460
461                 Read Only Properties
462
463                         double fps - this is fixed at 25 for PAL currently
464
465                 Dependencies
466
467                         libvorbisfile
468
469                 Known Bugs
470
471                         Fixed frame size (PAL audio chunks).
472                         Doesn't cover ogg files with multiple, differing sections.
473
474 Filters
475 -------
476
477         brightness
478         
479                 Description
480                 
481                         Shift the luma component using a constant value.
482                         
483                 Constructor Argument
484                 
485                         start - the constant floating point numeric value to apply.
486                               - the default is 0.
487                         
488                 Initialisation Properties
489                 
490                         int in - in point
491                         int out - out point
492                         double start - see Constructor Argument above.
493                         double end - the ending adjustment value. the filter interpolates
494                                      between the start and end adjustments over the 
495                                      duration of the effect.
496                                                  
497                 Read Only Properties
498                 
499                         none
500                         
501                 Dependencies
502                 
503                         none
504                         
505                 Known Bugs
506                 
507                         Does not go completely to black or white.
508
509
510         deinterlace
511         
512                 Description
513
514                         Deinterlace a frame consisting of two fields using bob, weave,
515                         greedy, one-field, and linear blend methods. This code is 
516                         appropriated from the Xine XV video output plugin.
517                 
518                 Constructor Argument
519
520                         method - a string containing the deinterlace method: bob, weave,
521                                  greedy, onefield, or linearblend. The default is
522                                          linearblend.
523                 
524                 Initialisation Properties
525
526                         int in - in point
527                         int out - out point
528                         
529                 Read Only Properties
530
531                         none
532                 
533                 Mutable Properties
534                 
535                         string method
536                         
537                 Details
538                 
539                         If the frame properties "progressive" or "consumer_progressive"
540                         are non-zero, then the filter is not applied. Also, if applied,
541                         this sets the frame property "progressive" to 1.
542
543                 Dependencies
544
545                         none
546                         
547                 Known Bugs
548
549                         Not a bug, but it only provides fair quality.
550                         
551                 
552         ffmpeg_dub
553         
554                 Description
555
556                     Use ffmpeg executable to substitute audio stream.
557                 
558                 Constructor Argument
559
560                         file - filename of a WAV, Ogg Vorbis (--enable-vorbis),
561                                MP3 (--enable-mp3lame), or AC-3 (--enable-a52) audio file.
562                 
563                 Initialisation Properties
564
565                         int in - in point
566                         int out - out point
567                 
568                 Read Only Properties
569                 
570                         string resource - file
571                         
572                 Dependencies
573
574                         ffmpeg plus for ffmpeg:
575                         libogg and libvorbis for Ogg Vorbis, libmp3lame for MP3, liba52 for AC-3.
576                         
577                 Known Bugs
578
579                         Uses pipes and is therefore not compatible with bluefish.
580                         
581
582         gamma
583         
584                 Description
585
586                         Adjust image luma using a non-linear power-law curve
587                         
588                 Constructor Argument
589
590                         gamma - a floating point value. The default is 1.0, or none.
591                 
592                 Initialisation Properties
593                 
594                         int in - in point
595                         int out - out point
596
597                 Mutable Properties
598
599                         double gamma - the exponential factor of the power-law curve
600                         
601                 Dependencies
602
603                         none
604                         
605                 Known Bugs
606
607                         none
608                         
609         
610         greyscale
611         
612                 Description
613
614                         Convert colour image to greyscale
615                         
616                 Constructor Argument
617
618                         none
619                         
620                 Initialisation Properties
621                 
622                         int in - in point
623                         int out - out point
624
625                 Read Only Properties
626
627                         none
628                         
629                 Dependencies
630
631                         none
632                         
633                 Known Bugs
634
635                         none
636                 
637         luma
638         
639                 Description
640                 
641                         Applies a luma transition between the current and next frames.
642                         Useful for transitions from a slideshow created using producer
643                         pixbuf.
644                         
645                 Constructor Argument
646                 
647                         file - a luma wipe
648                         
649                 Initialisation Properties
650                 
651                         int in - in point
652                         int out - out point
653                         
654                 Read Only Properties
655                 
656                         none
657                         
658                 Mutable Properties
659                 
660                         int period - how long to wait between success iterations of the
661                                      transition. For best results set this to a multiple
662                                      of ttl used in pixbuf. The default is 24.
663                                                  
664                         luma. - all properties beginning with "luma." are passed to the
665                                 encapsulated luma transition. For example, luma.out controls
666                                 the duration of the wipe.
667                         
668                 Dependencies
669                 
670                         transition_luma and its dependencies
671                         
672                 Known Bugs
673                 
674                         none
675                 
676         
677         obscure
678         
679                 Description
680
681                         Obscuring filter.
682                         
683                 Constructor Argument
684
685                         none
686                         
687                 Initialisation Properties
688                 
689                         string start - in the format X,Y:WxH[:PWxPY]
690                                      - PWxPY is the size of the averaging region in pixels.
691                         string end - in the format X,Y:WxH[:PWxPY]
692                         int in - in point
693                         int out - out point
694
695                 Read Only Properties
696
697                         none
698                         
699                 Dependencies
700
701                         none
702
703                 Known Bugs
704
705                         none
706
707         region
708         
709                 Description
710                 
711                         Apply one or filters to a region of the video image. The region
712                         can be shaped as well using the alpha channel of another producer.
713                         
714                 Constructor Argument
715                 
716                         file - A file whose alpha channel will "shape"  the region.
717                              - The string "circle" is a shortcut but it requires pixbuf with
718                                the librsvg loader. The circle is automatically stretched
719                                to the region to create an ellipse.
720         
721                 Initialisation Properties
722
723                         int in - in point
724                         int out - out point
725                         plus and region transition properties
726                         
727                 Read Only Properties
728                 
729                         see the region transition
730                         
731                 Dependencies
732                 
733                         transition_region
734                         
735                 Known Bugs
736                 
737                         "circle" is unpredictable in the absence of the librsvg pixbuf loader.
738                         
739
740         resample
741
742                 Description
743
744                         Adjust an audio stream's sampling rate.
745                         This filter is automatically invoked by Fezzik for the sake of
746                         normalisation over inputs and with the consumer.
747
748                 Constructor Argument
749
750                         frequency - a numeric value for the new sample rate
751
752                 Initialisation Properties
753
754                         int in - in point
755                         int out - out point
756
757                 Mutable Properties
758
759                         int frequency - the target sample rate
760
761                 Dependencies
762
763                         libresample
764
765                 Known Bugs
766
767                         none
768
769         rescale
770
771                 Description
772
773                         Scale the producer video frame size to match the consumer.
774                         This filter is automatically invoked by Fezzik in order to normalise
775                         sample aspect ratio.
776
777                 Constructor Argument
778
779                         interpolation - the rescaling method, one of:
780                                 nearest (lowest quality, fastest),
781                                 tiles,
782                                 bilinear (default; good quality, moderate speed),
783                                 hyper (best quality, slowest).
784
785                 Initialisation Properties
786
787                         int in - in point
788                         int out - out point
789
790                 Mutable Properties
791
792                         string interpolation - see constructor argument above
793
794                         If a property "consumer_aspect_ratio" exists on the frame, then
795                         rescaler normalises the producer's aspect ratio and maximises the
796                         size of the frame, but may not produce the consumer's requested
797                         dimension. Therefore, this option works best in conjunction with the
798                         resize filter. This behavior can be disabled by another service by
799                         either removing the property, setting it to zero, or setting
800                         frame property "distort" to 1.
801
802                 Dependencies
803
804                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
805
806                 Known Bugs
807
808                         none
809
810         resize
811         
812                 Description
813
814                         Image scaling and padding and field order adjustment.
815                                 
816                 Details
817                 
818                         Normally resize is used to pad the producer's
819                         output to what the consumer has requested after an upstream rescale
820                         filter first scales the image to maximise usage of the image area.
821                         This filter also adjusts the field order to lower field first
822                         if the frame property "top_field_first" has been set to 1.
823                         Therefore, when done, it sets the top_field_first to 0.
824                         This filter is automatically invoked by Fezzik as part of image
825                         sample aspect ratio normalisation.
826                         
827                 Constructor Argument
828
829                         scale - "affine" to use affine transform scaling, otherwise
830                                  center and pad.
831                         
832                 Initialisation Properties
833                 
834                         int in - in point
835                         int out - out point
836
837                 Read Only Properties
838
839                         none
840                         
841                 Dependencies
842
843                         none
844                         
845                 Known Bugs
846
847                         Assumes lower field first output.
848
849         volume
850
851                 Description
852
853                         Adjust an audio stream's volume level
854                         
855                 Constructor Argument
856
857                         gain - a string containing one of:
858                                  - a floating point value of the gain adjustment
859                                  - a numeric value with the suffix "dB" to adjust in terms of decibels
860                                  - "normalise" to normalise the volume to the target amplitude -12dBFS
861                         
862                 Initialisation Properties
863                 
864                         int in - in point
865                         int out - out point
866                         int window - the number of video frames over which to smooth normalisation.
867                                      defaults to 75.
868
869                 Mutable Properties
870
871                         string gain - same as constructor argument above
872
873                         string normalise - normalise the volume to the amplitude:
874                                 - a numeric value with the suffix "dB" to set amplitude in decibels
875                                 - a floating point value of the relative volume
876                                 - an unspecified value uses the default -12dBFS
877
878                         string limiter - limit all samples above:
879                                 - a numeric value with the suffix "dB"
880                                 - a floating point value ( dB = 20 * log10(x) )
881                                 - an unspecified value uses the default -6dBFS
882
883                         double max_gain - a floating point or decibel value of the maximum gain that
884                                 can be applied during normalisation.
885                                 - an unspecified value uses the default 20dB
886
887                         string end - a gain value just like the gain property above.
888                                      This causes the gain to be interpolated from 'gain' to 'end'
889                                      over the duration.
890
891                         int window - the size of the normalising smoothing buffer in video frame units.
892                                    - the smoothing buffer prevents erratic gain changes.
893                                    - the default value is 75 video frames. 
894
895                         gain can be applied as a factor to the normalise amplitude!
896                         
897                 Dependencies
898
899                         none
900                         
901                 Known Bugs
902
903                         none
904
905         watermark
906
907                 Description
908
909                         Add a watermark to the frames.
910
911                 Constructor Argument
912
913                         resource - the producer to use (ie: a .png)
914
915                 Initialisation Properties
916
917                         string resource - the producer to use
918                         string factory - producer required for the resource ('fezzik')
919                         string geometry - composite geometry
920                         string distort - control scaling
921                         int in - in point
922                         int out - out point
923
924                 Mutable Properties
925
926                         none
927
928                 Dependencies
929
930                         mlt core modules and optionally, fezzik
931
932                 Known Bugs
933
934                         none
935
936 Transitions
937 -----------
938
939         composite
940         
941                 Description
942
943                         A key-framable alpha-channel compositor for two frames.
944                         
945                 Details
946                 
947                         Performs dissolves and luma wipes in addition to alpha compositing.
948                         
949                         By default, the aspect ratio of the B frame is respected and the
950                         size portion of the geometry specification simply defines a 
951                         bounding rectangle.
952                 
953                         This performs field-based rendering unless the A frame property
954                         "progressive" or "consumer_progressive" or the transition property
955                         "progressive" is set to 1.
956                         
957                 Constructor Argument
958
959                         string start - a geometry specification as X,Y:WxH[!][:mix]
960                                      - X, Y, W, H are assumed to pixel units unless they
961                                        have the suffix '%'
962                                      - '!' is a shortcut to specify distort, see below.
963                                      - mix is always a 2 digit percentage, defaults to 100.
964                                                  - default is "85%,5%:10%x10%"
965
966                 Initialisation Properties
967                         
968                         string end - the ending size and position.
969                         string key[F] - X,Y:WxH[:mix] - set a key frame for geometry between
970                                         the in and out. F is a frame number and can be
971                                         negative to make it relative to the out point.
972                         int in - in point
973                         int out - out point
974                         string factory - The name of a factory service used as a non-PGM
975                                          producer loader. The default is fezzik.
976         
977                 Read Only Properties
978
979                         none
980
981                 Mutable Properties
982                         
983                         int progressive - set to 1 to disable field-based rendering.
984                         string distort - when set, causes the B frame image to fill the WxH
985                                          completely with no regard to B's aspect ratio.
986                         string halign - when not distorting, set the horizontal alignment
987                                         of B within the geometry rectangle.
988                                       - one of: left (0), centre (1), or right (2).
989                                       - the default is left.
990                         string valign - when not distorting, set the vertical alignment of 
991                                         B within the geometry rectangle.
992                                       - one of: top (0), middle (1), or bottom (2).
993                                       - the default is top.
994                         string luma - the luma map file name. If not supplied, a dissolve.
995                         double softness - only when using a luma map, how soft to make the
996                                           edges between A and B. 0.0 = no softness. 1.0 =
997                                           too soft.
998                         Any property starting with "luma." is passed to the non-PGM luma
999                             producer.
1000
1001                 Dependencies
1002
1003                         none
1004                 
1005                 Known Bugs
1006
1007                         Assumes lower field first during field rendering.
1008
1009         luma
1010         
1011                 Description
1012
1013                         A generic dissolve and wipe transition processor.
1014
1015                 Details
1016
1017                         luma gets its name
1018                         from how it uses a grayscale "map" file. As the luma value varies
1019                         over time, a threshold filter is applied to the map to determine
1020                         what parts of frame A vs. frame B to show. It reads PGM files
1021                         up to 16 bits! Alternatively, it can use the first frame from any
1022                         producer that outputs yuv, but it will be limited to the luma
1023                         gamut of 220 values.
1024                         This performs field-based rendering unless the A frame property
1025                         "progressive" or "consumer_progressive" or the transition property
1026                         "progressive" is set to 1.
1027                 
1028                 Constructor Argument
1029
1030                         string resource - the luma map file name - either PGM or any other
1031                                           producable video. 
1032                                         - If not supplied, a dissolve.
1033
1034                 Initialisation Properties
1035                 
1036                         int in - in point
1037                         int out - out point
1038                         string factory - The name of a factory service used as a non-PGM
1039                                          producer loader. The default is Fezzik.
1040
1041                 Mutable Properties
1042
1043                         string resource - same as above
1044                         double softness - only when using a luma map, how soft to make the
1045                                           edges between A and B. 0.0 = no softness. 1.0 =
1046                                           too soft.
1047                         Any property starting with "producer." is passed to the non-PGM luma
1048                             producer.
1049                         
1050                 Read Only Properties
1051
1052                         none
1053                         
1054                 Dependencies
1055
1056                         none
1057                         
1058                 Known Bugs
1059                         
1060                         Assumes lower field first output.
1061
1062         mix
1063
1064                 Description
1065
1066                         An two stream audio mixer.
1067
1068                 Constructor Argument
1069
1070                         start - see below
1071
1072                 Initalisation Properties
1073
1074                         int in - in point
1075                         int out - out point
1076
1077                 Mutable Properties
1078
1079                         double start - the mix level to apply to the second frame.
1080                                      - any negative value causes an automatic crossfade from 0 to 1.
1081                         double end - the ending value of the mix level. mix level will be interpolated
1082                                      from start to end over the in-out range.
1083                         int reverse - set to 1 to reverse the direction of the mix.
1084
1085                 Read Only Properties
1086
1087                         none
1088
1089                 Dependencies
1090
1091                         none
1092
1093                 Known Bugs
1094
1095                         Samples from the longer of the two frames are discarded.
1096                         
1097         
1098         region
1099         
1100                 Description
1101                 
1102                         Apply zero or more filters to B frame as it is composited onto
1103                         a region of the A frame. The "shape" of the region can be defined
1104                         by the alpha channel of a third producer.
1105                         
1106                 Constructor Argument
1107
1108                         resource - a shape producer
1109                 
1110                 Initialisation Properties
1111                 
1112                         string resource - nothing is rectangle, "circle" is a pixbuf-
1113                             generated SVG circle, anything else is loaded by the factory.
1114                         string factory - the service that creates the shape producer.
1115                                        - the default is fezzik.
1116                         string filter[N] - one or more filters to apply. All filter
1117                                            properties are passed using the same filter "key"
1118                         Any property starting with "composite." is passed to the 
1119                             encapsulated composite transition.
1120                         
1121                 Read Only Properties
1122                 
1123                         none
1124                         
1125                 Dependencies
1126                 
1127                         transition_composite
1128                         
1129                 Known Bugs
1130                 
1131                         none
1132                         
1133
1134 Consumers
1135 ---------
1136
1137         bluefish (Proprietary)
1138         
1139                 Description
1140
1141                         BlueFish444 audio and video output module.
1142                 
1143                 Constructor Argument
1144
1145                         string video_standard - "PAL" (default) or "NTSC"
1146                         
1147                 Initialisation Properties
1148
1149                         int video_standard - 0 = PAL, 1 = NTSC
1150                         
1151                 Read Only Properties
1152
1153                         none
1154                 
1155                 Dependencies
1156
1157                         BlueVelvet SDK installed parallel to mlt in "bluefish."
1158                 
1159                 Known Bugs
1160
1161                         Does not work with any service that uses pipes!
1162                         
1163                         If mlt crashes, you must reload the BlueDriver kernel module
1164                         due to unreleased DMA buffers.
1165                         
1166                         Needs an argument or property for multi-card address.
1167                 
1168         ffmpeg
1169         
1170                 Description
1171                 Constructor Argument
1172                 Initialisation Properties
1173                 Read Only Properties
1174                 Dependencies
1175                 Known Bugs
1176
1177         libdv
1178         
1179                 Description
1180                 
1181                         libdv dv producer.
1182
1183                 Constructor Argument
1184
1185                         string target
1186
1187                 Initialisation Properties
1188                 
1189                         int buffer
1190                         string rescale
1191                         
1192                 Read Only Properties
1193                 
1194                         none
1195                         
1196                 Dependencies
1197                 
1198                         libdv
1199                         
1200                 Known Bugs
1201                 
1202                         none
1203
1204         sdl
1205
1206                 Description
1207
1208                         Simple DirectMedia Layer audio and video output module.
1209                         
1210                 Constructor Argument
1211
1212                         string video_standard - "PAL" (default), "NTSC", or "WxH"
1213                         
1214                 Mutable Properties
1215
1216                         double volume - audio level factor
1217                         int video_off - if 1, disable video output
1218                         int audio_off - if 1, disable audio output
1219                         int scale_overlay - if 1, resample video from source pixel aspect
1220                                             ratio to square pixels.
1221                         
1222                 Read Only Properties
1223
1224                         none
1225                         
1226                 Dependencies
1227
1228                         libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
1229                 
1230                 Known Bugs
1231
1232                         NTSC handling needs tightening up - sdl:NTSC is the only valid
1233                         constructor for NTSC playback at the moment.
1234
1235         westley
1236
1237                 Description
1238
1239                         Serialise the service network to XML.
1240                         See docs/westley.txt for more information.
1241                         
1242                 Constructor Argument
1243
1244                         resource - the name of a file in which to store the XML.
1245                                 stdout is used if not supplied.
1246                         
1247                 Initialisation Properties
1248
1249                         string resource - same as above.
1250                         
1251                 Dependencies
1252                 
1253                         libxml2
1254                         
1255                 Known Bugs
1256
1257                         Untested arbitrary nesting of multitracks and playlists.
1258                         Property "id" is generated as service type followed by number if
1259                         no property named "id" exists, but it fails to guarantee uniqueness.