6500f5ff831ca600b64f7a965812408c46a6986d
[melted] / docs / services.txt
1 Producers
2 ---------
3
4         avformat
5
6                 Description
7
8                         ffmpeg libavformat based producer for video and audio.
9
10                 Constructor Argument
11
12                         'file' - producer a/v from file
13
14                 Initialisation Properties
15
16                         int video_index - index of video stream to use (-1 is off)
17                         int audio_index - index of audio stream to use (-1 is off)
18                         int in - in point
19                         int out - out point
20
21                 Read Only Properties
22
23                         double fps - this is fixed at 25 for PAL currently
24                         double aspect_ratio - this is determined on the first frame read
25
26                 Dependencies
27
28                         ffmpeg must be configured as --enable-shared and installed prior
29                         to compilation of mlt.
30
31                 Known Bugs
32
33                         Audio sync discrepancy with some content.
34                         Not all libavformat supported formats are seekable.
35                         ogg is currently broken.
36                         mpeg seeking is inaccurate - doesn't seek to i-frames so you may
37                         get junk for a few frames.
38
39         fezzik
40
41                 Description
42
43                         A friendly giant that likes to rhyme and throw rocks
44
45                 Constructor Argument
46
47                         'file'  - produce a/v from file
48
49                 Initialisation Properties
50
51                         int in - in point
52                         int out - out point
53                         + all producer initialising properties
54
55                 Read Only Properties
56
57                         string resource - file location
58                         + all producer read only properties
59
60                 Details
61
62                         This producer is has two roles:
63
64                         1. it handles the mappings of all file names to the other
65                         producers;
66                         2. it attaches normalising filters (rescale, resize and resample)
67                         to the producers (when necessary).
68
69                         This producer simplifies many aspects of use. Essentially, it
70                         ensures that a consumer will receive images and audio precisely as
71                         they request them. 
72
73                 Dependencies
74
75                         all.
76
77                 Known Bugs
78
79                         None.
80
81         ffmpeg
82
83                 Description
84
85                         Test case pipe based producer for video and audio.
86
87                 Constructor Argument
88
89                         'file'  - produce a/v from file
90                         v4l             - produce a/v from video4linux and dsp device
91
92                 Initialisation Properties
93
94                         string video_type - "file" or "v4l"
95                         string video_file - file or v4l device
96                         string video_size - WxH of video to produce (default: "")
97                         int video_loop - loop video until audio exhausted (default: 0)
98                         string audio_type - "file" or "dsp"
99                         string audio_file - file or dsp device
100                         int audio_rate - audio frequency (default: 48000)
101                         int audio_channels - audio channels (default: 2)
102                         int audio_track - audio track to use (default: 0)
103                         int audio_loop - loop audio until video exhausted (default: 0)
104                         int in - in point
105                         int out - out point
106                         double fps - output frames per second (default: 25)
107                         double aspect_ratio - aspect ratio of video
108
109                 Read Only Properties
110
111                         string resource - file or "v4l"
112                         int end_of_clip - holds 1 when input is exhausted
113
114                 Dependencies
115
116                         ffmpeg executable.
117
118                 Known Bugs
119
120                         in point setting is broken.
121
122                         Implementation does not allow fast random access.
123
124         libdv
125
126                 Description
127
128                         libdv based decoder for video and audio.
129
130                 Constructor Argument
131
132                         'file'  - produce a/v from file
133
134                 Initialisation Properties
135
136                         int in - in point
137                         int out - out point
138
139                 Read Only Properties
140
141                         string resource - file location
142                         double fps - output frames per second
143                         double aspect_ratio - aspect ratio of video]
144                         int length - duration of resource (in frames)
145
146                 Dependencies
147
148                         libdv.
149
150                 Known Bugs
151
152                         None.
153
154         mcdv
155
156                 Description
157
158                         Mainconcept based dv decoder for video and audio.
159
160                 Constructor Argument
161
162                         'file'  - produce a/v from file
163
164                 Initialisation Properties
165
166                         int in - in point
167                         int out - out point
168
169                 Read Only Properties
170
171                         string resource - file location
172                         double fps - output frames per second
173                         double aspect_ratio - aspect ratio of video
174                         int length - duration of resource (in frames)
175
176                 Dependencies
177
178                         mainconcept dv sdk and libdv.
179                         "dv_sdk" installed parallel to mlt.
180
181                 Known Bugs
182
183                         Can be problematic with some NTSC DV files?
184
185         mcmpeg
186
187                 Description
188
189                         Mainconcept based mpeg decoder for video and audio.
190
191                 Constructor Argument
192
193                         'file'  - produce a/v from file
194
195                 Initialisation Properties
196
197                         int in - in point
198                         int out - out point
199
200                 Read Only Properties
201
202                         string resource - file location
203                         double fps - output frames per second
204                         double aspect_ratio - aspect ratio of video
205
206                 Dependencies
207
208                         mainconcept mpeg sdk.
209                         "mpeg_sdk_demo" installed parallel to mlt.
210
211                 Known Bugs
212
213                         None.
214
215         pango
216
217                 Description
218
219                         A title generator that uses the Pango international text layout
220                         and Freetype2 font renderer.
221
222                 Constructor Argument
223
224                         string file - a text file containing Pango markup, see:
225                                    http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
226                                    - requires xml-like encoding special chars: <, >, & to &lt;, &gt;, &amp;
227
228                 Initialisation Properties
229
230                         int in - in point
231                         int out - out point
232
233                 Mutable Properties
234
235                         int video_standard - enum mlt_video_standard from mlt_frame.h
236                                              PAL = 0, NTSC = 1
237                                              this determines proper pixel aspect ratio
238
239                         string markup - a string containing Pango markup see:
240                                         http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
241                                       - requires xml-like encoding special chars: <, >, & to &lt;, &gt;, &amp;
242
243                         string fgcolour - an rgba colour specification of the text (i.e. 0xrrggbbaa)
244                         string bgcolour - an rgba colour of the background rectangle
245                         int align - paragraph alignment: 0 = left, 1 = center, 2 = right
246                         int pad - the number of pixels to pad the background rectangle beyond edges of text
247                                   default 0
248                         string markup - see constructor argument
249                         string text - non-markup text (can contain markup chars un-encoded)
250                         string font - the default typeface to use when not using markup
251                                       default "Sans 48"
252
253                 Read Only Properties
254
255                         string resource - the text/markup file or "pango" if no file
256
257                 Dependencies
258
259                         libpango-1.0, libpangoft2-1.0, libfreetype, libgdk_pixbuf-2.0, libglib-2.0,
260                         libgobject-2.0, libgmodule-2.0, libfontconfig
261
262                 Known Bugs
263
264                         no frame-alignment functionality
265
266         pixbuf
267
268                 Description
269
270                         A graphics overlay generator using gdk-pixbuf
271
272                 Constructor Argument
273
274                         'file' - The name of a graphics file loadable by
275                                  a gdk-pixbuf loader. see /usr/lib/gdk-pixbuf/loaders
276                                  definitely png, jpeg, tiff, pnm, and xpm
277                                - If "%" in filename, the filename is used with sprintf
278                                  generate a filename from a counter for multi-file/flipbook animation.
279                                  The file sequence ends when numeric discontinuity >100.
280                                - If filename contains "/.all.", suffix with an extension to load
281                                  all pictures with matching extension from a directory
282
283                 Initialisation Properties
284
285                         int in - in point
286                         int out - out point
287
288                 Mutable Properties
289
290                         int video_standard - enum mlt_video_standard from mlt_frame.h
291                                              PAL = 0, NTSC = 1
292                                              this determines proper pixel aspect ratio
293                         double ttl - how long (seconds) to repeat each picture in file sequences
294
295                 Read Only Properties
296
297                         string resource - file location
298
299                 Dependencies
300
301                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
302
303                 Known Bugs
304
305                         in/out settings are incorrectly handled.
306
307         ppm
308         
309                 Description
310
311                         Reads a stream of contiguous PPM images.
312                         
313                 Constructor Argument
314
315                         command - a shell command to run something that produces ppm
316                                   streams on stdout.
317                         
318                 Initialisation Properties
319
320                         none
321                         
322                 Read Only Properties
323
324                         string resource - the command
325                         
326                 Dependencies
327
328                         none
329                         
330                 Known Bugs
331
332                         Since it uses pipes, it is not compatible with bluefish.
333
334         westley
335
336                 Description
337
338                         Construct a service network from an XML description.
339
340                 Constructor Argument
341
342                         file - an XML text file containing westley XML (schema pending)
343
344                 Read Only Properties
345
346                         string resource - file location
347
348                 Dependencies
349
350                         libxml2
351
352                 Known Bugs
353
354                         Non-referenced producers and playlists are not destroyed.
355                         A referenced producer or playlist must appear before the reference.
356
357         vorbis
358
359                 Description
360
361                         OGG Vorbis file reader.
362
363                 Constructor Argument
364
365                         'file' - file to use (only .ogg supported at the moment)
366
367                 Initialisation Properties
368
369                         int in - in point
370                         int out - out point
371
372                 Read Only Properties
373
374                         double fps - this is fixed at 25 for PAL currently
375
376                 Dependencies
377
378                         libvorbisfile
379
380                 Known Bugs
381
382                         Fixed frame size (PAL audio chunks).
383                         Doesn't cover ogg files with multiple, differing sections.
384
385 Filters
386 -------
387
388         deinterlace
389         
390                 Description
391
392                         Deinterlace a frame consisting of two fields by linearly blending.
393                 
394                 Constructor Argument
395
396                         none
397                 
398                 Initialisation Properties
399
400                         int in - in point
401                         int out - out point
402
403                 Read Only Properties
404
405                         none
406                 
407                 Dependencies
408
409                         none
410                         
411                 Known Bugs
412
413                         Not a bug, but it only provides fair quality at a fair performance;
414                                 i.e., it excels at neither.
415                 
416         ffmpeg_dub
417         
418                 Description
419
420                     Use ffmpeg executable to substitute audio stream.
421                 
422                 Constructor Argument
423
424                         file - filename of a WAV, Ogg Vorbis (--enable-vorbis),
425                                MP3 (--enable-mp3lame), or AC-3 (--enable-a52) audio file.
426                 
427                 Initialisation Properties
428
429                         int in - in point
430                         int out - out point
431                 
432                 Read Only Properties
433                 
434                         string resource - file
435                         
436                 Dependencies
437
438                         ffmpeg plus for ffmpeg:
439                         libogg and libvorbis for Ogg Vorbis, libmp3lame for MP3, liba52 for AC-3.
440                         
441                 Known Bugs
442
443                         Uses pipes and is therefore not compatible with bluefish.
444
445         gamma
446         
447                 Description
448
449                         Adjust image luma using a non-linear power-law curve
450                         
451                 Constructor Argument
452
453                         gamma - a floating point value
454                 
455                 Initialisation Properties
456                 
457                         int in - in point
458                         int out - out point
459
460                 Mutable Properties
461
462                         double gamma - the exponential factor of the power-law curve
463                         
464                 Dependencies
465
466                         none
467                         
468                 Known Bugs
469
470                         none
471         
472         greyscale
473         
474                 Description
475
476                         Convert colour image to greyscale
477                         
478                 Constructor Argument
479
480                         none
481                         
482                 Initialisation Properties
483                 
484                         int in - in point
485                         int out - out point
486
487                 Read Only Properties
488
489                         none
490                         
491                 Dependencies
492
493                         none
494                         
495                 Known Bugs
496
497                         none
498                 
499         obscure
500         
501                 Description
502
503                         Obscuring filter.
504                         
505                 Constructor Argument
506
507                         none
508                         
509                 Initialisation Properties
510                 
511                         string start - in the format X,Y:WxH[:PWxPY]
512                         string end - in the format X,Y:WxH[:PWxPY]
513                         int in - in point
514                         int out - out point
515
516                 Read Only Properties
517
518                         none
519                         
520                 Dependencies
521
522                         none
523
524                 Known Bugs
525
526                         none
527
528         resize
529         
530                 Description
531
532                         Image scaling and padding
533                         
534                 Constructor Argument
535
536                         scale - "affine" to use affine transform scaling, otherwise
537                                  center and pad.
538                         
539                 Initialisation Properties
540                 
541                         int in - in point
542                         int out - out point
543
544                 Read Only Properties
545
546                         none
547                         
548                 Dependencies
549
550                         none
551                         
552                 Known Bugs
553
554                         none
555
556         resample
557
558                 Description
559
560                         Adjust an audio stream's sampling rate
561
562                 Constructor Argument
563
564                         frequency - a numeric value for the new sample rate
565
566                 Initialisation Properties
567
568                         int in - in point
569                         int out - out point
570
571                 Mutable Properties
572
573                         int frequency - the target sample rate
574
575                 Dependencies
576
577                         libresample
578
579                 Known Bugs
580
581                         none
582
583         rescale
584
585                 Description
586
587                         Scale the producer video frame size to match the consumer.
588
589                 Constructor Argument
590
591                         interpolation - the rescaling method, one of:
592                                 nearest (lowest quality, fastest),
593                                 tiles,
594                                 bilinear (good quality, moderate speed),
595                                 hyper (best quality, slowest)
596
597                 Initialisation Properties
598
599                         int in - in point
600                         int out - out point
601
602                 Mutable Properties
603
604                         string interpolation - see constructor argument above
605
606                         If a property "consumer_aspect_ratio" exists on the frame, then
607                         rescaler normalises the producer's aspect ratio and maximises the
608                         size of the frame, but may not produce the consumer's requested
609                         dimension. Therefore, this option works best in conjunction with the
610                         resize filter. This behavior can be disabled by another service by
611                         either removing the property, setting it to zero, or setting
612                         frame property "distort" to 1.
613
614                 Dependencies
615
616                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
617
618                 Known Bugs
619
620                         none
621
622         volume
623
624                 Description
625
626                         Adjust an audio stream's volume level
627                         
628                 Constructor Argument
629
630                         gain - a string containing one of:
631                                  - a floating point value of the gain adjustment
632                                  - a numeric value with the suffix "dB" to adjust in terms of decibels
633                                  - "normalise" to normalise the volume to the target amplitude -12dBFS
634                         
635                 Initialisation Properties
636                 
637                         int in - in point
638                         int out - out point
639                         int window - the number of video frames over which to smooth normalisation.
640                                      defaults to 75.
641
642                 Mutable Properties
643
644                         string gain - same as constructor argument above
645
646                         string normalise - normalise the volume to the amplitude:
647                                 - a numeric value with the suffix "dB" to set amplitude in decibels
648                                 - a floating point value of the relative volume
649                                 - an unspecified value uses the default -12dBFS
650
651                         string limiter - limit all samples above:
652                                 - a numeric value with the suffix "dB"
653                                 - a floating point value ( dB = 20 * log10(x) )
654                                 - an unspecified value uses the default -6dBFS
655
656                         double max_gain - a floating point or decibel value of the maximum gain that
657                                 can be applied during normalisation.
658                                 - an unspecified value uses the default 20dB
659
660                         string end - a gain value just like the gain property above.
661                                      This causes the gain to be interpolated from 'gain' to 'end'
662                                      over the duration.
663
664                         int window - the size of the normalising smoothing buffer in video frame units.
665                                    - the smoothing buffer prevents erratic gain changes.
666                                    - the default value is 75 video frames. 
667
668                         gain can be applied as a factor to the normalise amplitude!
669                         
670                 Dependencies
671
672                         none
673                         
674                 Known Bugs
675
676                         none
677
678         watermark
679
680                 Description
681
682                         Add a watermark to the frames.
683
684                 Constructor Argument
685
686                         resource - the producer to use (ie: a .png)
687
688                 Initialisation Properties
689
690                         string resource - the producer to use
691                         string factory - producer required for the resource ('fezzik')
692                         string geometry - composite geometry
693                         string distort - control scaling
694                         int in - in point
695                         int out - out point
696
697                 Mutable Properties
698
699                         none
700
701                 Dependencies
702
703                         mlt core modules and optionally, fezzik
704
705                 Known Bugs
706
707                         none
708
709 Transitions
710 -----------
711
712         composite
713         
714                 Description
715
716                         An alpha-channel based compositor for two frames.
717                         
718                 Constructor Argument
719
720                         string start - X,Y:WxH[:mix]
721
722                 Initialisation Properties
723                         
724                         string end - X,Y:WxH[:mix]
725                         int in - in point
726                         int out - out point
727         
728                 Read Only Properties
729
730                         none
731                 
732                 Dependencies
733
734                         none
735                 
736                 Known Bugs
737
738                         Need to add field-based rendering.
739
740         luma
741         
742                 Description
743
744                         A generic dissolve and wipe transition processor. It gets its name
745                         from how it uses a grayscale "map" file. As the luma value varies
746                         over time, a threshold filter is applied to the map to determine
747                         what parts of frame A vs. frame B to show. It only reads PGM
748                         files, but it does handle 16 bit PGM. This performs field-based
749                         rendering.
750                 
751                 Constructor Argument
752
753                         string resource - the luma map file name. If not supplied, a dissolve.
754
755                 Initialisation Properties
756                 
757                         int in - in point
758                         int out - out point
759
760                 Mutable Properties
761
762                         string resource - same as above
763                         double softness - only when using a luma map, how soft to make the
764                                           edges between A and B. 0.0 = no softness. 1.0 =
765                                           too soft.
766                         
767                 Read Only Properties
768
769                         none
770                         
771                 Dependencies
772
773                         none
774                         
775                 Known Bugs
776
777                         The luma map must be the same size as the B frame.
778                         The PGM parser does not handle comments.
779
780         mix
781
782                 Description
783
784                         An two stream audio mixer.
785
786                 Constructor Argument
787
788                         start - see below
789
790                 Initalisation Properties
791
792                         int in - in point
793                         int out - out point
794
795                 Mutable Properties
796
797                         double start - the mix level to apply to the second frame.
798                                      - any negative value causes an automatic crossfade from 0 to 1.
799                         double end - the ending value of the mix level. mix level will be interpolated
800                                      from start to end over the in-out range.
801                         int reverse - set to 1 to reverse the direction of the mix.
802
803                 Read Only Properties
804
805                         none
806
807                 Dependencies
808
809                         none
810
811                 Known Bugs
812
813                         Samples from the longer of the two frames are discarded.
814
815 Consumers
816 ---------
817
818         bluefish
819         
820                 Description
821
822                         BlueFish444 audio and video output module.
823                 
824                 Constructor Argument
825
826                         string video_standard - "PAL" (default) or "NTSC"
827                         
828                 Initialisation Properties
829
830                         int video_standard - 0 = PAL, 1 = NTSC
831                         
832                 Read Only Properties
833
834                         none
835                 
836                 Dependencies
837
838                         BlueVelvet SDK installed parallel to mlt in "bluefish."
839                 
840                 Known Bugs
841
842                         Does not work with any service that uses pipes!
843                         
844                         If mlt crashes, you must reload the BlueDriver kernel module
845                         due to unreleased DMA buffers.
846                         
847                         Needs an argument or property for multi-card address.
848                 
849         ffmpeg
850         
851                 Description
852                 Constructor Argument
853                 Initialisation Properties
854                 Read Only Properties
855                 Dependencies
856                 Known Bugs
857
858         libdv
859         
860                 Description
861                 
862                         libdv dv producer.
863
864                 Constructor Argument
865
866                         string video_standard - "PAL" (default) or "NTSC"
867
868                 Initialisation Properties
869                 Read Only Properties
870                 Dependencies
871                 Known Bugs
872
873         sdl
874
875                 Description
876
877                         Simple DirectMedia Layer audio and video output module.
878                         
879                 Constructor Argument
880
881                         string video_standard - "PAL" (default), "NTSC", or "WxH"
882                         
883                 Mutable Properties
884
885                         double volume - audio level factor
886                         int video_off - if 1, disable video output
887                         int audio_off - if 1, disable audio output
888                         int scale_overlay - if 1, resample video from source pixel aspect
889                                             ratio to square pixels.
890                         
891                 Read Only Properties
892
893                         none
894                         
895                 Dependencies
896
897                         libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
898                 
899                 Known Bugs
900
901                         NTSC handling needs tightening up - sdl:NTSC is the only valid
902                         constructor for NTSC playback at the moment.
903
904         westley
905
906                 Description
907
908                         Serialise the service network to XML.
909                         
910                 Constructor Argument
911
912                         resource - the name of a file in which to store the XML.
913                                 stdout is used if not supplied.
914                         
915                 Initialisation Properties
916
917                         string resource - same as above.
918                         
919                 Dependencies
920                 
921                         libxml2
922                         
923                 Known Bugs
924
925                         Untested arbitrary nesting of multitracks and playlists.
926                         Property "id" is generated as service type followed by number if
927                         no property named "id" exists, but it fails to guarantee uniqueness.
928