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