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