8cbed80ff102fd468353060416936c4be7991356
[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         vorbis
317
318                 Description
319
320                         OGG Vorbis file reader.
321
322                 Constructor Argument
323
324                         'file' - file to use (only .ogg supported at the moment)
325
326                 Initialisation Properties
327
328                         int in - in point
329                         int out - out point
330
331                 Read Only Properties
332
333                         double fps - this is fixed at 25 for PAL currently
334
335                 Dependencies
336
337                         libvorbisfile
338
339                 Known Bugs
340
341                         Fixed frame size (PAL audio chunks).
342                         Doesn't cover ogg files with multiple, differing sections.
343
344
345 Filters
346 -------
347
348         deinterlace
349         
350                 Description
351
352                         Deinterlace a frame consisting of two fields by linearly blending.
353                 
354                 Constructor Argument
355
356                         none
357                 
358                 Initialisation Properties
359
360                         int in - in point
361                         int out - out point
362
363                 Read Only Properties
364
365                         none
366                 
367                 Dependencies
368
369                         none
370                         
371                 Known Bugs
372
373                         Not a bug, but it only provides fair quality at a fair performance;
374                                 i.e., it excels at neither.
375                 
376         ffmpeg_dub
377         
378                 Description
379
380                         Use ffmpeg executable to substitute audio stream.
381                 
382                 Constructor Argument
383
384                         file - filename of a WAV, Ogg Vorbis (--enable-vorbis),
385                                MP3 (--enable-mp3lame), or AC-3 (--enable-a52) audio file.
386                 
387                 Initialisation Properties
388
389                         int in - in point
390                         int out - out point
391                 
392                 Read Only Properties
393                 
394                         string resource - file
395                         
396                 Dependencies
397
398                         ffmpeg plus for ffmpeg:
399                         libogg and libvorbis for Ogg Vorbis, libmp3lame for MP3, liba52 for AC-3.
400                         
401                 Known Bugs
402
403                         Uses pipes and is therefore not compatible with bluefish.
404
405         gamma
406         
407                 Description
408
409                         Adjust image luma using a non-linear power-law curve
410                         
411                 Constructor Argument
412
413                         gamma - a floating point value
414                 
415                 Initialisation Properties
416                 
417                         int in - in point
418                         int out - out point
419
420                 Mutable Properties
421
422                         double gamma - the exponential factor of the power-law curve
423                         
424                 Dependencies
425
426                         none
427                         
428                 Known Bugs
429
430                         none
431         
432         greyscale
433         
434                 Description
435
436                         Convert color image to greyscale
437                         
438                 Constructor Argument
439
440                         none
441                         
442                 Initialisation Properties
443                 
444                         int in - in point
445                         int out - out point
446
447                 Read Only Properties
448
449                         none
450                         
451                 Dependencies
452
453                         none
454                         
455                 Known Bugs
456
457                         none
458                 
459         resize
460         
461                 Description
462
463                         Image scaling and padding
464                         
465                 Constructor Argument
466
467                         scale - "affine" to use affine transform scaling, otherwise
468                                  center and pad.
469                         
470                 Initialisation Properties
471                 
472                         int in - in point
473                         int out - out point
474
475                 Read Only Properties
476
477                         none
478                         
479                 Dependencies
480
481                         none
482                         
483                 Known Bugs
484
485                         none
486
487         volume
488
489                 Description
490
491                         Adjust an audio stream's volume level
492                         
493                 Constructor Argument
494
495                         volume - a floating point value of the factor
496                         
497                 Initialisation Properties
498                 
499                         int in - in point
500                         int out - out point
501
502                 Mutable Properties
503
504                         double volume - the factor applied to each sample
505                         
506                 Dependencies
507
508                         none
509                         
510                 Known Bugs
511
512                         none
513
514         resample
515
516                 Description
517
518                         Adjust an audio stream's sampling rate
519
520                 Constructor Argument
521
522                         frequency - a numeric value for the new sample rate
523
524                 Initialisation Properties
525
526                         int in - in point
527                         int out - out point
528
529                 Mutable Properties
530
531                         int frequency - the target sample rate
532
533                 Dependencies
534
535                         libresample
536
537                 Known Bugs
538
539                         none
540
541 Transitions
542 -----------
543
544         composite
545         
546                 Description
547
548                         An alpha-channel based compositor for two frames.
549                         
550                 Constructor Argument
551
552                         mix - see below
553
554                 Initialisation Properties
555                         
556                         int in - in point
557                         int out - out point
558
559                 Mutable Properties
560
561                         int x - the horizontal offset from the left edge of the frame
562                         int y - the vertical offset from the top edge of the frame
563                         double mix - the opacity factor to apply to the second frame
564                                      (used in addition to alpha channel).
565                                    - any negative value causes an automatic dissolve
566                 
567                 Read Only Properties
568
569                         none
570                 
571                 Dependencies
572
573                         none
574                 
575                 Known Bugs
576
577                         Need to add field-based rendering.
578
579         luma
580         
581                 Description
582
583                         A generic dissolve and wipe transition processor. It gets its name
584                         from how it uses a grayscale "map" file. As the luma value varies
585                         over time, a threshold filter is applied to the map to determine
586                         what parts of frame A vs. frame B to show. It only reads PGM
587                         files, but it does handle 16 bit PGM. This performs field-based
588                         rendering.
589                 
590                 Constructor Argument
591
592                         string file - the luma map file name. If not supplied, a dissolve.
593
594                 Initialisation Properties
595                 
596                         int in - in point
597                         int out - out point
598
599                 Mutable Properties
600
601                         string filename - same as above
602                         double softness - only when using a luma map, how soft to make the
603                                           edges between A and B. 0.0 = no softness. 1.0 =
604                                           too soft.
605                         
606                 Read Only Properties
607
608                         none
609                         
610                 Dependencies
611
612                         none
613                         
614                 Known Bugs
615
616                         The luma map must be the same size as the B frame.
617                         The PGM parser does not handle comments.
618
619         mix
620
621                 Description
622
623                         An two stream audio mixer.
624
625                 Constructor Argument
626
627                         mix - see below
628
629                 Initalisation Properties
630
631                         int in - in point
632                         int out - out point
633
634                 Mutable Properties
635
636                         double mix - the mix level to apply to the second frame.
637                                    - any negative value causes an automatic crossfade.
638
639                 Read Only Properties
640
641                         none
642
643                 Dependencies
644
645                         none
646
647                 Known Bugs
648
649                         Samples from the longer of the two frames are discarded.
650
651 Consumers
652 ---------
653
654         bluefish
655         
656                 Description
657
658                         BlueFish444 audio and video output module.
659                 
660                 Constructor Argument
661
662                         string video_standard - "PAL" (default) or "NTSC"
663                         
664                 Initialisation Properties
665
666                         int video_standard - 0 = PAL, 1 = NTSC
667                         
668                 Read Only Properties
669
670                         none
671                 
672                 Dependencies
673
674                         BlueVelvet SDK installed parallel to mlt in "bluefish."
675                 
676                 Known Bugs
677
678                         Does not work with any service that uses pipes!
679                         
680                         If mlt crashes, you must reload the BlueDriver kernel module
681                         due to unreleased DMA buffers.
682                         
683                         Needs an argument or property for multi-card address.
684                 
685         ffmpeg
686         
687                 Description
688                 Constructor Argument
689                 Initialisation Properties
690                 Read Only Properties
691                 Dependencies
692                 Known Bugs
693
694         libdv
695         
696                 Description
697                 
698                         libdv dv producer.
699
700                 Constructor Argument
701
702                         string video_standard - "PAL" (default) or "NTSC"
703
704                 Initialisation Properties
705                 Read Only Properties
706                 Dependencies
707                 Known Bugs
708
709         sdl
710
711                 Description
712
713                         Simple DirectMedia Layer audio and video output module.
714                         
715                 Constructor Argument
716
717                         string video_standard - "PAL" (default), "NTSC", or "WxH"
718                         
719                 Mutable Properties
720
721                         double volume - audio level factor
722                         int video_off - if 1, disable video output
723                         int audio_off - if 1, disable audio output
724                         int scale_overlay - if 1, resample video from source pixel aspect
725                                             ratio to square pixels.
726                         
727                 Read Only Properties
728
729                         none
730                         
731                 Dependencies
732
733                         libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
734                 
735                 Known Bugs
736
737                         NTSC handling needs tightening up - sdl:NTSC is the only valid
738                         constructor for NTSC playback at the moment.
739