]> git.sesse.net Git - mlt/blob - docs/services.txt
minor typos
[mlt] / 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                         
302                         Pango has builtin scaling. It will rescale the originally rendered
303                         title to whatever the consumer requests. Therefore, it will lose
304                         its aspect ratio if so requested, and it is up to the consumer to
305                         request a proper width and height that maintains the image aspect.
306
307                 Initialisation Properties
308
309                         int in - in point
310                         int out - out point
311
312                 Mutable Properties
313
314                         string markup - a string containing Pango markup see:
315                         http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
316                                       - requires xml-like encoding special chars from: 
317                                         <, >, &   -to-   &lt;, &gt;, &amp;
318                         string fgcolour - an RGBA colour specification of the text 
319                                           (i.e. 0xrrggbbaa)
320                         string bgcolour - an RGBA colour of the background rectangle
321                         string align - paragraph alignment: left, centre, right
322                                      - also, numbers 0, 1 and 2 can be used respectively.
323                         int pad - the number of pixels to pad the background rectangle 
324                                   beyond edges of text. default 0.
325                         string markup - see constructor argument
326                         string text - non-markup string in UTF-8 encoding (can contain 
327                                       markup chars un-encoded)
328                         string font - the default typeface to use when not using markup.
329                                       default "Sans 48". FreeType2 renders at 72 dpi.
330                         string encoding - the text encoding type of the input if not UTF-8.
331                                         - see 'iconv --list' for a list of possible inputs.
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.
372                                          
373                 Details
374                 
375                         Pixbuf has builtin scaling. It will rescale the originally rendered
376                         title to whatever the consumer requests. Therefore, it will lose
377                         its aspect ratio if so requested, and it is up to the consumer to
378                         request a proper width and height that maintains the image aspect.
379
380                 Initialisation Properties
381
382                         int in - in point
383                         int out - out point
384
385                 Mutable Properties
386
387                         int ttl - how long (in frames) to repeat each picture in file 
388                                   sequences. default is 25.
389
390                 Read Only Properties
391
392                         string resource - file location. See Constructor Argument above.
393                         int real_width - the original, unscaled width of the rendered title.
394                         int real_height - the original, unscaled height of the title.
395                         int width - the last requested scaled image width.
396                         int height - the last requested scaled image height.
397
398                 Dependencies
399
400                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
401
402                 Known Bugs
403
404                         XXX: in/out settings are incorrectly handled.
405
406         ppm
407         
408                 Description
409
410                         Reads a stream of contiguous PPM images.
411                         
412                 Constructor Argument
413
414                         command - a shell command to run something that produces ppm
415                                   streams on stdout.
416                         
417                 Initialisation Properties
418
419                         none
420                         
421                 Read Only Properties
422
423                         string resource - the command
424                         
425                 Dependencies
426
427                         none
428                         
429                 Known Bugs
430
431                         Since it uses pipes, it is not compatible with bluefish.
432
433         westley
434
435                 Description
436
437                         Construct a service network from an XML description.
438                         See docs/westley.txt.
439
440                 Constructor Argument
441
442                         file - an XML text file containing westley XML (schema pending)
443
444                 Read Only Properties
445
446                         string resource - file location
447
448                 Dependencies
449
450                         libxml2
451
452                 Known Bugs
453
454                         Non-referenced producers and playlists are not destroyed until the 
455                         network is destroyed.
456                         A referenced producer or playlist must appear before the reference.
457                         A filter that occurs before a producer has been defined causes a 
458                         segfault.
459
460         vorbis
461
462                 Description
463
464                         OGG Vorbis file reader.
465
466                 Constructor Argument
467
468                         'file' - file to use (only .ogg supported at the moment)
469
470                 Initialisation Properties
471
472                         int in - in point
473                         int out - out point
474
475                 Read Only Properties
476
477                         double fps - this is fixed at 25 for PAL currently
478
479                 Dependencies
480
481                         libvorbisfile
482
483                 Known Bugs
484
485                         Fixed frame size (PAL audio chunks).
486                         Doesn't cover ogg files with multiple, differing sections.
487
488 Filters
489 -------
490
491         brightness
492         
493                 Description
494                 
495                         Shift the luma component using a constant value.
496                         
497                 Constructor Argument
498                 
499                         start - the constant floating point numeric value to apply.
500                               - the default is 0.
501                         
502                 Initialisation Properties
503                 
504                         int in - in point
505                         int out - out point
506                         double start - see Constructor Argument above.
507                         double end - the ending adjustment value. the filter interpolates
508                                      between the start and end adjustments over the 
509                                      duration of the effect.
510                                                  
511                 Read Only Properties
512                 
513                         none
514                         
515                 Dependencies
516                 
517                         none
518                         
519                 Known Bugs
520                 
521                         Does not go completely to black or white.
522                         
523         
524         channelcopy
525         
526                 Description
527                 
528                         Copy audio from one channel to another channel.
529                         
530                 Constructor Argument
531                 
532                         to - the 0-indexed channel to copy into, default is 1.
533                         
534                 Mutable Properties
535                 
536                         int to - see above
537                         int from - the channel from which to copy, default is 0.
538                         
539                 Dependencies
540                 
541                         none
542                         
543                 Known Bugs
544                 
545                         none
546                         
547
548
549         deinterlace
550         
551                 Description
552
553                         Deinterlace a frame consisting of two fields using bob, weave,
554                         greedy, one-field, and linear blend methods. This code is 
555                         appropriated from the Xine XV video output plugin.
556                 
557                 Constructor Argument
558
559                         method - a string containing the deinterlace method: bob, weave,
560                                  greedy, onefield, or linearblend. The default is
561                                          linearblend.
562                 
563                 Initialisation Properties
564
565                         int in - in point
566                         int out - out point
567                         
568                 Read Only Properties
569
570                         none
571                 
572                 Mutable Properties
573                 
574                         string method
575                         
576                 Details
577                 
578                         If the frame properties "progressive" or "consumer_progressive"
579                         are non-zero, then the filter is not applied. Also, if applied,
580                         this sets the frame property "progressive" to 1.
581
582                 Dependencies
583
584                         none
585                         
586                 Known Bugs
587
588                         Not a bug, but it only provides fair quality.
589                         
590                 
591         ffmpeg_dub
592         
593                 Description
594
595                     Use ffmpeg executable to substitute audio stream.
596                 
597                 Constructor Argument
598
599                         file - filename of a WAV, Ogg Vorbis (--enable-vorbis),
600                                MP3 (--enable-mp3lame), or AC-3 (--enable-a52) audio file.
601                 
602                 Initialisation Properties
603
604                         int in - in point
605                         int out - out point
606                 
607                 Read Only Properties
608                 
609                         string resource - file
610                         
611                 Dependencies
612
613                         ffmpeg plus for ffmpeg:
614                         libogg and libvorbis for Ogg Vorbis, libmp3lame for MP3, liba52 for AC-3.
615                         
616                 Known Bugs
617
618                         Uses pipes and is therefore not compatible with bluefish.
619                         
620
621         gamma
622         
623                 Description
624
625                         Adjust image luma using a non-linear power-law curve
626                         
627                 Constructor Argument
628
629                         gamma - a floating point value. The default is 1.0, or none.
630                 
631                 Initialisation Properties
632                 
633                         int in - in point
634                         int out - out point
635
636                 Mutable Properties
637
638                         double gamma - the exponential factor of the power-law curve
639                         
640                 Dependencies
641
642                         none
643                         
644                 Known Bugs
645
646                         none
647                         
648         
649         greyscale
650         
651                 Description
652
653                         Convert colour image to greyscale
654                         
655                 Constructor Argument
656
657                         none
658                         
659                 Initialisation Properties
660                 
661                         int in - in point
662                         int out - out point
663
664                 Read Only Properties
665
666                         none
667                         
668                 Dependencies
669
670                         none
671                         
672                 Known Bugs
673
674                         none
675                 
676         luma
677         
678                 Description
679                 
680                         Applies a luma transition between the current and next frames.
681                         Useful for transitions from a slideshow created using producer
682                         pixbuf.
683                         
684                 Constructor Argument
685                 
686                         file - a luma wipe
687                         
688                 Initialisation Properties
689                 
690                         int in - in point
691                         int out - out point
692                         
693                 Read Only Properties
694                 
695                         none
696                         
697                 Mutable Properties
698                 
699                         int period - how long to wait between success iterations of the
700                                      transition. For best results set this to a multiple
701                                      of ttl used in pixbuf. The default is 24.
702                                                  
703                         luma. - all properties beginning with "luma." are passed to the
704                                 encapsulated luma transition. For example, luma.out controls
705                                 the duration of the wipe.
706                         
707                 Dependencies
708                 
709                         transition_luma and its dependencies
710                         
711                 Known Bugs
712                 
713                         none
714                 
715         
716         mirror
717         
718                 Description
719                 
720                         Provides various mirror and image reversing effects.
721
722                 Constructor Argument
723                 
724                         mirror - horizontal, vertical, diagonal, flip, flop
725                         
726                 Initialisation Properties
727                 
728                         int reverse - being 0 or 1
729                         int in - in point
730                         int out - out point
731                         
732                 Read Only Properties
733                 
734                         none
735                         
736                 Mutable Properties
737                 
738                         none
739
740                 Dependencies
741                 
742                         none
743                         
744                 Known Bugs
745                 
746                         none
747
748
749         obscure
750         
751                 Description
752
753                         Obscuring filter.
754                         
755                 Constructor Argument
756
757                         none
758                         
759                 Initialisation Properties
760                 
761                         string start - in the format X,Y:WxH[:PWxPY]
762                                      - PWxPY is the size of the averaging region in pixels.
763                         string end - in the format X,Y:WxH[:PWxPY]
764                         int in - in point
765                         int out - out point
766
767                 Read Only Properties
768
769                         none
770                         
771                 Dependencies
772
773                         none
774
775                 Known Bugs
776
777                         none
778
779         region
780         
781                 Description
782                 
783                         Apply one or filters to a region of the video image. The region
784                         can be shaped as well using the alpha channel of another producer.
785                         
786                 Constructor Argument
787                 
788                         file - A file whose alpha channel will "shape"  the region.
789                              - The string "circle" is a shortcut but it requires pixbuf with
790                                the librsvg loader. The circle is automatically stretched
791                                to the region to create an ellipse.
792         
793                 Initialisation Properties
794
795                         int in - in point
796                         int out - out point
797                         plus and region transition properties
798                         
799                 Read Only Properties
800                 
801                         see the region transition
802                         
803                 Dependencies
804                 
805                         transition_region
806                         
807                 Known Bugs
808                 
809                         "circle" is unpredictable in the absence of the librsvg pixbuf loader.
810                         
811
812         resample
813
814                 Description
815
816                         Adjust an audio stream's sampling rate, and duplicate channels if 
817                         producer provides less than consumer requested.
818                         
819                         This filter is automatically invoked by Fezzik for the sake of
820                         normalisation over inputs and with the consumer.
821
822                 Constructor Argument
823
824                         frequency - a numeric value for the new sample rate
825
826                 Initialisation Properties
827
828                         int in - in point
829                         int out - out point
830
831                 Mutable Properties
832
833                         int frequency - the target sample rate
834
835                 Dependencies
836
837                         libresample
838
839                 Known Bugs
840
841                         Assumes 2 channels during libsamplerate initialisation. Untested
842                         with >2 channels.
843
844         rescale
845
846                 Description
847
848                         Scale the producer video frame size to match the consumer.
849                         This filter is automatically invoked by Fezzik in order to normalise
850                         sample aspect ratio.
851
852                 Constructor Argument
853
854                         interpolation - the rescaling method, one of:
855                                 nearest (lowest quality, fastest),
856                                 tiles,
857                                 bilinear (default; good quality, moderate speed),
858                                 hyper (best quality, slowest).
859
860                 Initialisation Properties
861
862                         int in - in point
863                         int out - out point
864
865                 Mutable Properties
866
867                         string interpolation - see constructor argument above
868
869                         If a property "consumer_aspect_ratio" exists on the frame, then
870                         rescaler normalises the producer's aspect ratio and maximises the
871                         size of the frame, but may not produce the consumer's requested
872                         dimension. Therefore, this option works best in conjunction with the
873                         resize filter. This behavior can be disabled by another service by
874                         either removing the property, setting it to zero, or setting
875                         frame property "distort" to 1.
876
877                 Dependencies
878
879                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
880
881                 Known Bugs
882
883                         none
884
885         resize
886         
887                 Description
888
889                         Image scaling and padding and field order adjustment.
890                                 
891                 Details
892                 
893                         Normally resize is used to pad the producer's
894                         output to what the consumer has requested after an upstream rescale
895                         filter first scales the image to maximise usage of the image area.
896                         This filter also adjusts the field order to lower field first
897                         if the frame property "top_field_first" has been set to 1.
898                         Therefore, when done, it sets the top_field_first to 0.
899                         This filter is automatically invoked by Fezzik as part of image
900                         sample aspect ratio normalisation.
901                         
902                 Constructor Argument
903
904                         scale - "affine" to use affine transform scaling, otherwise
905                                  center and pad.
906                         
907                 Initialisation Properties
908                 
909                         int in - in point
910                         int out - out point
911
912                 Read Only Properties
913
914                         none
915                         
916                 Dependencies
917
918                         none
919                         
920                 Known Bugs
921
922                         Assumes lower field first output.
923
924         volume
925
926                 Description
927
928                         Adjust an audio stream's volume level
929                         
930                 Constructor Argument
931
932                         gain - a string containing one of:
933                                  - a floating point value of the gain adjustment
934                                  - a numeric value with the suffix "dB" to adjust in terms of decibels
935                                  - "normalise" to normalise the volume to the target amplitude -12dBFS
936                         
937                 Initialisation Properties
938                 
939                         int in - in point
940                         int out - out point
941                         int window - the number of video frames over which to smooth normalisation.
942                                      defaults to 75.
943
944                 Mutable Properties
945
946                         string gain - same as constructor argument above
947
948                         string normalise - normalise the volume to the amplitude:
949                                 - a numeric value with the suffix "dB" to set amplitude in decibels
950                                 - a floating point value of the relative volume
951                                 - an unspecified value uses the default -12dBFS
952
953                         string limiter - limit all samples above:
954                                 - a numeric value with the suffix "dB"
955                                 - a floating point value ( dB = 20 * log10(x) )
956                                 - an unspecified value uses the default -6dBFS
957
958                         double max_gain - a floating point or decibel value of the maximum gain that
959                                 can be applied during normalisation.
960                                 - an unspecified value uses the default 20dB
961
962                         string end - a gain value just like the gain property above.
963                                      This causes the gain to be interpolated from 'gain' to 'end'
964                                      over the duration.
965
966                         int window - the size of the normalising smoothing buffer in video frame units.
967                                    - the smoothing buffer prevents erratic gain changes.
968                                    - the default value is 75 video frames. 
969
970                         gain can be applied as a factor to the normalise amplitude!
971                         
972                 Dependencies
973
974                         none
975                         
976                 Known Bugs
977
978                         none
979
980         watermark
981
982                 Description
983
984                         Add a watermark to the frames.
985
986                 Constructor Argument
987
988                         resource - the producer to use (ie: a .png)
989
990                 Initialisation Properties
991
992                         string resource - the producer to use
993                         string factory - producer required for the resource ('fezzik')
994                         string geometry - composite geometry
995                         string distort - control scaling
996                         int in - in point
997                         int out - out point
998
999                 Mutable Properties
1000
1001                         none
1002
1003                 Dependencies
1004
1005                         mlt core modules and optionally, fezzik
1006
1007                 Known Bugs
1008
1009                         none
1010
1011 Transitions
1012 -----------
1013
1014         composite
1015         
1016                 Description
1017
1018                         A key-framable alpha-channel compositor for two frames.
1019                         
1020                 Details
1021                 
1022                         Performs dissolves and luma wipes in addition to alpha compositing.
1023                         
1024                         By default, the aspect ratio of the B frame is respected and the
1025                         size portion of the geometry specification simply defines a 
1026                         bounding rectangle.
1027                 
1028                         This performs field-based rendering unless the A frame property
1029                         "progressive" or "consumer_progressive" or the transition property
1030                         "progressive" is set to 1.
1031                         
1032                 Constructor Argument
1033
1034                         string start - a geometry specification as X,Y:WxH[!][:mix]
1035                                      - X, Y, W, H are assumed to pixel units unless they
1036                                        have the suffix '%'
1037                                      - '!' is a shortcut to specify distort, see below.
1038                                      - mix is always a 2 digit percentage, defaults to 100.
1039                                                  - default is "85%,5%:10%x10%"
1040
1041                 Initialisation Properties
1042                         
1043                         string end - the ending size and position.
1044                         string key[F] - X,Y:WxH[:mix] - set a key frame for geometry between
1045                                         the in and out. F is a frame number and can be
1046                                         negative to make it relative to the out point.
1047                         int in - in point
1048                         int out - out point
1049                         string factory - The name of a factory service used as a non-PGM
1050                                          producer loader. The default is fezzik.
1051         
1052                 Read Only Properties
1053
1054                         none
1055
1056                 Mutable Properties
1057                         
1058                         int progressive - set to 1 to disable field-based rendering.
1059                         string distort - when set, causes the B frame image to fill the WxH
1060                                          completely with no regard to B's aspect ratio.
1061                         string halign - when not distorting, set the horizontal alignment
1062                                         of B within the geometry rectangle.
1063                                       - one of: left (0), centre (1), or right (2).
1064                                       - the default is left.
1065                         string valign - when not distorting, set the vertical alignment of 
1066                                         B within the geometry rectangle.
1067                                       - one of: top (0), middle (1), or bottom (2).
1068                                       - the default is top.
1069                         string luma - the luma map file name. If not supplied, a dissolve.
1070                         double softness - only when using a luma map, how soft to make the
1071                                           edges between A and B. 0.0 = no softness. 1.0 =
1072                                           too soft.
1073                         Any property starting with "luma." is passed to the non-PGM luma
1074                             producer.
1075
1076                 Dependencies
1077
1078                         none
1079                 
1080                 Known Bugs
1081
1082                         Assumes lower field first during field rendering.
1083
1084         luma
1085         
1086                 Description
1087
1088                         A generic dissolve and wipe transition processor.
1089
1090                 Details
1091
1092                         luma gets its name
1093                         from how it uses a grayscale "map" file. As the luma value varies
1094                         over time, a threshold filter is applied to the map to determine
1095                         what parts of frame A vs. frame B to show. It reads PGM files
1096                         up to 16 bits! Alternatively, it can use the first frame from any
1097                         producer that outputs yuv, but it will be limited to the luma
1098                         gamut of 220 values.
1099                         This performs field-based rendering unless the A frame property
1100                         "progressive" or "consumer_progressive" or the transition property
1101                         "progressive" is set to 1.
1102                 
1103                 Constructor Argument
1104
1105                         string resource - the luma map file name - either PGM or any other
1106                                           producable video. 
1107                                         - If not supplied, a dissolve.
1108
1109                 Initialisation Properties
1110                 
1111                         int in - in point
1112                         int out - out point
1113                         string factory - The name of a factory service used as a non-PGM
1114                                          producer loader. The default is Fezzik.
1115
1116                 Mutable Properties
1117
1118                         string resource - same as above
1119                         double softness - only when using a luma map, how soft to make the
1120                                           edges between A and B. 0.0 = no softness. 1.0 =
1121                                           too soft.
1122                         Any property starting with "producer." is passed to the non-PGM luma
1123                             producer.
1124                         
1125                 Read Only Properties
1126
1127                         none
1128                         
1129                 Dependencies
1130
1131                         none
1132                         
1133                 Known Bugs
1134                         
1135                         Assumes lower field first output.
1136
1137         mix
1138
1139                 Description
1140
1141                         An two stream audio mixer.
1142
1143                 Constructor Argument
1144
1145                         start - see below
1146
1147                 Initalisation Properties
1148
1149                         int in - in point
1150                         int out - out point
1151
1152                 Mutable Properties
1153
1154                         double start - the mix level to apply to the second frame.
1155                                      - any negative value causes an automatic crossfade from 0 to 1.
1156                         double end - the ending value of the mix level. mix level will be interpolated
1157                                      from start to end over the in-out range.
1158                         int reverse - set to 1 to reverse the direction of the mix.
1159
1160                 Read Only Properties
1161
1162                         none
1163
1164                 Dependencies
1165
1166                         none
1167
1168                 Known Bugs
1169
1170                         Samples from the longer of the two frames are discarded.
1171                         
1172         
1173         region
1174         
1175                 Description
1176                 
1177                         Apply zero or more filters to B frame as it is composited onto
1178                         a region of the A frame. The "shape" of the region can be defined
1179                         by the alpha channel of a third producer.
1180                         
1181                 Constructor Argument
1182
1183                         resource - a shape producer
1184                 
1185                 Initialisation Properties
1186                 
1187                         string resource - nothing is rectangle, "circle" is a pixbuf-
1188                             generated SVG circle, anything else is loaded by the factory.
1189                         string factory - the service that creates the shape producer.
1190                                        - the default is fezzik.
1191                         string filter[N] - one or more filters to apply. All filter
1192                                            properties are passed using the same filter "key"
1193                         Any property starting with "composite." is passed to the 
1194                             encapsulated composite transition.
1195                         
1196                 Read Only Properties
1197                 
1198                         none
1199                         
1200                 Dependencies
1201                 
1202                         transition_composite
1203                         
1204                 Known Bugs
1205                 
1206                         none
1207                         
1208
1209 Consumers
1210 ---------
1211
1212         bluefish (Proprietary)
1213         
1214                 Description
1215
1216                         BlueFish444 audio and video output module.
1217                 
1218                 Constructor Argument
1219
1220                         card - a numeric card id starting at 1, default is 1.
1221                         
1222                 Initialisation Properties
1223
1224                         string standard - "PAL" (default) or "NTSC"
1225                                         - default is based upon MLT_NORMALISATION 
1226                                                           environment variable, which defaults to PAL.
1227                         int frames - the number of DMA video frames. default is 4.
1228                                      minimum is 2. maximum on my system is 11.
1229                         int buffer - the number of frames to buffer within MLT, minimum 1, 
1230                                      default 25.
1231                         string rescale - a rescale method, see the Filters/rescale.
1232                         
1233                 Read Only Properties
1234
1235                         none
1236                 
1237                 Dependencies
1238
1239                         BlueVelvet SDK installed parallel to mlt in "bluefish."
1240                 
1241                 Known Bugs
1242
1243                         Does not work with any service that uses pipes!
1244                         
1245                         If mlt crashes, you might need to reload the BlueDriver kernel 
1246                         module due to unreleased DMA buffers.
1247                         
1248                         Only supports 2 channel audio at the moment.
1249                 
1250         libdv
1251         
1252                 Description
1253                 
1254                         libdv dv producer.
1255
1256                 Constructor Argument
1257
1258                         string target - the filename to write to, e.g. /dev/dv1394.
1259
1260                 Initialisation Properties
1261                 
1262                         int buffer - the number of frames to buffer, minimum 1, default 25.
1263                         string rescale - a rescale method, see the Filters/rescale.
1264                 
1265                 Mutable Properties
1266                 
1267                         int progressive - indicates whether to use progressive or field-
1268                                           based rendering, default 0 (off).
1269                         
1270                 Read Only Properties
1271                 
1272                         none
1273                         
1274                 Dependencies
1275                 
1276                         libdv
1277                         
1278                 Known Bugs
1279                 
1280                         none
1281
1282         sdl
1283
1284                 Description
1285
1286                         Simple DirectMedia Layer audio and video output module.
1287                         
1288                 Constructor Argument
1289
1290                         string video_standard - "PAL" (default), "NTSC", or "WxH"
1291                         
1292                 Initialisation Properties
1293                 
1294                         int buffer - the number of frames to buffer, minimum 1, default 25.
1295                         string rescale - a rescale method, see the Filters/rescale.
1296                                        - Hint: "none" works very good with SDL output.
1297                         
1298                 Mutable Properties
1299
1300                         double volume - audio level factor
1301                         int video_off - if 1, disable video output
1302                         int audio_off - if 1, disable audio output
1303                         int scale_overlay - if 1, resample video from source pixel aspect
1304                                             ratio to square pixels.
1305                         int progressive - indicates whether to use progressive or field-
1306                                           based rendering, default 0 (off).
1307                         
1308                 Read Only Properties
1309
1310                         none
1311                         
1312                 Dependencies
1313
1314                         libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
1315                 
1316                 Known Bugs
1317
1318                         none
1319
1320         westley
1321
1322                 Description
1323
1324                         Serialise the service network to XML.
1325                         See docs/westley.txt for more information.
1326                         
1327                 Constructor Argument
1328
1329                         resource - the name of a file in which to store the XML.
1330                                   - stdout is default.
1331                         
1332                 Initialisation Properties
1333
1334                         string resource - same as above.
1335                         
1336                 Dependencies
1337                 
1338                         libxml2
1339                         
1340                 Known Bugs
1341
1342                         Untested arbitrary nesting of multitracks and playlists.
1343                         Property "id" is generated as service type followed by number if
1344                         no property named "id" exists, but it fails to guarantee uniqueness.