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