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