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