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