0477176507a5b7ac69f7e333b92a4c5774f5f90a
[melted] / docs / services.txt
1 Producers
2 ---------
3
4         ffmpeg
5
6                 Description
7
8                         Test case pipe based producer for video and audio.
9
10                 Constructor Argument
11
12                         'file'  - produce a/v from file
13                         v4l             - produce a/v from video4linux and dsp device
14
15                 Initialisation Properties
16
17                         string video_type - "file" or "v4l"
18                         string video_file - file or v4l device
19                         string video_size - WxH of video to produce (default: "")
20                         int video_loop - loop video until audio exhausted (default: 0)
21                         string audio_type - "file" or "dsp"
22                         string audio_file - file or dsp device
23                         int audio_rate - audio frequency (default: 48000)
24                         int audio_channels - audio channels (default: 2)
25                         int audio_track - audio track to use (default: 0)
26                         int audio_loop - loop audio until video exhausted (default: 0)
27                         intint in - in point
28                         int out - out point
29                         double fps - output frames per second (default: 25)
30                         double aspect_ratio - aspect ratio of video
31
32                 Read Only Properties
33
34                         string resource - file or "v4l"
35                         int end_of_clip - holds 1 when input is exhausted
36
37                 Dependencies
38
39                         ffmpeg executable.
40
41                 Known Bugs
42
43                         in point setting is broken.
44
45                         Implementation does not allow fast random access.
46
47         libdv
48
49                 Description
50
51                         libdv based decoder for video and audio.
52
53                 Constructor Argument
54
55                         'file'  - produce a/v from file
56
57                 Initialisation Properties
58
59                         int in - in point
60                         int out - out point
61
62                 Read Only Properties
63
64                         string resource - file location
65                         double fps - output frames per second
66                         double aspect_ratio - aspect ratio of video]
67                         int length - duration of resource (in frames)
68
69                 Dependencies
70
71                         libdv.
72
73                 Known Bugs
74
75                         None.
76
77         mcdv
78
79                 Description
80
81                         Mainconcept based dv decoder for video and audio.
82
83                 Constructor Argument
84
85                         'file'  - produce a/v from file
86
87                 Initialisation Properties
88
89                         int in - in point
90                         int out - out point
91
92                 Read Only Properties
93
94                         string resource - file location
95                         double fps - output frames per second
96                         double aspect_ratio - aspect ratio of video
97                         int length - duration of resource (in frames)
98
99                 Dependencies
100
101                         mainconcept dv sdk and libdv.
102                         "dv_sdk" installed parallel to mlt.
103
104                 Known Bugs
105
106                         Can be problematic with source NTSC DV files? really? yes - try
107                         playing pond.dv...
108
109         mcmpeg
110
111                 Description
112
113                         Mainconcept based mpeg decoder for video and audio.
114
115                 Constructor Argument
116
117                         'file'  - produce a/v from file
118
119                 Initialisation Properties
120
121                         int in - in point
122                         int out - out point
123
124                 Read Only Properties
125
126                         string resource - file location
127                         double fps - output frames per second
128                         double aspect_ratio - aspect ratio of video
129
130                 Dependencies
131
132                         mainconcept mpeg sdk.
133                         "mpeg_sdk_demo" installed parallel to mlt.
134
135                 Known Bugs
136
137                         None.
138
139         pango
140
141                 Description
142
143                         A title generator that uses the Pango international text layout
144                         and Freetype2 font renderer.
145
146                 Constructor Argument
147
148                         string file - a text file containing Pango markup, see:
149                                    http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
150                                    - requires xml-like encoding special chars: <, >, & to &lt;, &gt;, &amp;
151
152                 Initialisation Properties
153
154                         int in - in point
155                         int out - out point
156
157                 Mutable Properties
158
159                         int video_standard - enum mlt_video_standard from mlt_frame.h
160                                              PAL = 0, NTSC = 1
161                                              this determines proper pixel aspect ratio
162
163                         string markup - a string containing Pango markup see:
164                                         http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
165                                       - requires xml-like encoding special chars: <, >, & to &lt;, &gt;, &amp;
166
167                         int fgcolor - an rgba color specification of the text (i.e. 0xrrggbbaa)
168                         int bgcolor - an rgba color of the background rectangle
169                         int align - paragraph alignment: 0 = left, 1 = center, 2 = right
170                         int pad - the number of pixels to pad the background rectangle beyond edges of text
171                                   default 0
172                         string markup - see constructor argument
173                         string text - non-markup text (can contain markup chars un-encoded)
174                         string font - the default typeface to use when not using markup
175                                       default "Sans 48"
176                         int x - the horizontal position of the title on the frame
177                                 default 0
178                         int y - the vertical position of the title on the frame
179                                 default 0
180                         double mix - the overall opacity control of the generated title
181                                      default 1.0
182
183                 Read Only Properties
184
185                         string resource - the text/markup file or "pango" if no file
186
187                 Dependencies
188
189                         libpango-1.0, libpangoft2-1.0, libfreetype, libgdk_pixbuf-2.0, libglib-2.0,
190                         libgobject-2.0, libgmodule-2.0, libfontconfig
191
192                 Known Bugs
193
194                         no frame-alignment functionality
195
196         pixbuf
197
198                 Description
199
200                         A graphics overlay generator using gdk-pixbuf
201
202                 Constructor Argument
203
204                         'file' - The name of a graphics file loadable by
205                                  a gdk-pixbuf loader. see /usr/lib/gdk-pixbuf/loaders
206                                  definitely png, jpeg, tiff, pnm, and xpm
207                                - If "%" in filename, the filename is used with sprintf
208                                  generate a filename from a counter for multi-file/flipbook animation.
209                                  The file sequence ends when numeric discontinuity >100.
210                                - If filename contains "/.all.", suffix with an extension to load
211                                  all pictures with matching extension from a directory
212
213                 Initialisation Properties
214
215                         int in - in point
216                         int out - out point
217
218                 Mutable Properties
219
220                         int video_standard - enum mlt_video_standard from mlt_frame.h
221                                              PAL = 0, NTSC = 1
222                                              this determines proper pixel aspect ratio
223                         double ttl - how long (seconds) to repeat each picture in file sequences
224                         int x - the horizontal offset from the left edge of the frame
225                         int y - the vertical offset from the top edge of the frame
226                         double mix - the opacity factor to apply to the second frame
227                                      (used in addition to alpha channel).
228
229
230                 Read Only Properties
231
232                         string resource - file location
233
234                 Dependencies
235
236                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
237
238                 Known Bugs
239
240                         in/out settings are incorrectly handled.
241
242         ppm
243         
244                 Description
245
246                         Reads a stream of contiguous PPM images.
247                         
248                 Constructor Argument
249
250                         command - a shell command to run something that produces ppm
251                                   streams on stdout.
252                         
253                 Initialisation Properties
254
255                         none
256                         
257                 Read Only Properties
258
259                         string resource - the command
260                         
261                 Dependencies
262
263                         none
264                         
265                 Known Bugs
266
267                         Since it uses pipes, it is not compatible with bluefish.
268
269
270 Filters
271 -------
272
273         deinterlace
274         
275                 Description
276
277                         Deinterlace a frame consisting of two fields by linearly blending.
278                 
279                 Constructor Argument
280
281                         none
282                 
283                 Initialisation Properties
284
285                         int in - in point
286                         int out - out point
287
288                 Read Only Properties
289
290                         none
291                 
292                 Dependencies
293
294                         none
295                         
296                 Known Bugs
297
298                         Not a bug, but it only provides fair quality at a fair performance;
299                                 i.e., it excels at neither.
300                 
301         ffmpeg_dub
302         
303                 Description
304
305                         Use ffmpeg executable to substitute audio stream.
306                 
307                 Constructor Argument
308
309                         file - filename of a WAV, Ogg Vorbis (--enable-vorbis),
310                                MP3 (--enable-mp3lame), or AC-3 (--enable-a52) audio file.
311                 
312                 Initialisation Properties
313
314                         int in - in point
315                         int out - out point
316                 
317                 Read Only Properties
318                 
319                         string resource - file
320                         
321                 Dependencies
322
323                         ffmpeg plus for ffmpeg:
324                         libogg and libvorbis for Ogg Vorbis, libmp3lame for MP3, liba52 for AC-3.
325                         
326                 Known Bugs
327
328                         Uses pipes and is therefore not compatible with bluefish.
329
330         gamma
331         
332                 Description
333
334                         Adjust image luma using a non-linear power-law curve
335                         
336                 Constructor Argument
337
338                         gamma - a floating point value
339                 
340                 Initialisation Properties
341                 
342                         int in - in point
343                         int out - out point
344
345                 Mutable Properties
346
347                         double gamma - the exponential factor of the power-law curve
348                         
349                 Dependencies
350
351                         none
352                         
353                 Known Bugs
354
355                         none
356         
357         greyscale
358         
359                 Description
360
361                         Convert color image to greyscale
362                         
363                 Constructor Argument
364
365                         none
366                         
367                 Initialisation Properties
368                 
369                         int in - in point
370                         int out - out point
371
372                 Read Only Properties
373
374                         none
375                         
376                 Dependencies
377
378                         none
379                         
380                 Known Bugs
381
382                         none
383                 
384         resize
385         
386                 Description
387
388                         Image scaling and padding
389                         
390                 Constructor Argument
391
392                         scale - "affine" to use affine transform scaling, otherwise
393                                  center and pad.
394                         
395                 Initialisation Properties
396                 
397                         int in - in point
398                         int out - out point
399
400                 Read Only Properties
401
402                         none
403                         
404                 Dependencies
405
406                         none
407                         
408                 Known Bugs
409
410                         none
411
412         volume
413
414                 Description
415
416                         Adjust an audio stream's volume level
417                         
418                 Constructor Argument
419
420                         volume - a floating point value of the factor
421                         
422                 Initialisation Properties
423                 
424                         int in - in point
425                         int out - out point
426
427                 Mutable Properties
428
429                         double volume - the factor applied to each sample
430                         
431                 Dependencies
432
433                         none
434                         
435                 Known Bugs
436
437                         none
438
439         resample
440
441                 Description
442
443                         Adjust an audio stream's sampling rate
444
445                 Constructor Argument
446
447                         frequency - a numeric value for the new sample rate
448
449                 Initialisation Properties
450
451                         int in - in point
452                         int out - out point
453
454                 Mutable Properties
455
456                         int frequency - the target sample rate
457
458                 Dependencies
459
460                         libresample
461
462                 Known Bugs
463
464                         none
465
466 Transitions
467 -----------
468
469         composite
470         
471                 Description
472
473                         An alpha-channel based compositor for two frames.
474                         
475                 Constructor Argument
476
477                         mix - see below
478
479                 Initialisation Properties
480                         
481                         int in - in point
482                         int out - out point
483
484                 Mutable Properties
485
486                         int x - the horizontal offset from the left edge of the frame
487                         int y - the vertical offset from the top edge of the frame
488                         double mix - the opacity factor to apply to the second frame
489                                      (used in addition to alpha channel).
490                                    - any negative value causes an automatic dissolve
491                 
492                 Read Only Properties
493
494                         none
495                 
496                 Dependencies
497
498                         none
499                 
500                 Known Bugs
501
502                         Need to add field-based rendering.
503
504         luma
505         
506                 Description
507
508                         A generic dissolve and wipe transition processor. It gets its name
509                         from how it uses a grayscale "map" file. As the luma value varies
510                         over time, a threshold filter is applied to the map to determine
511                         what parts of frame A vs. frame B to show. It only reads PGM
512                         files, but it does handle 16 bit PGM. This performs field-based
513                         rendering.
514                 
515                 Constructor Argument
516
517                         string file - the luma map file name. If not supplied, a dissolve.
518
519                 Initialisation Properties
520                 
521                         int in - in point
522                         int out - out point
523
524                 Mutable Properties
525
526                         string filename - same as above
527                         double softness - only when using a luma map, how soft to make the
528                                           edges between A and B. 0.0 = no softness. 1.0 =
529                                           too soft.
530                         
531                 Read Only Properties
532
533                         none
534                         
535                 Dependencies
536
537                         none
538                         
539                 Known Bugs
540
541                         The luma map must be the same size as the B frame.
542
543         mix
544
545                 Description
546
547                         An two stream audio mixer.
548
549                 Constructor Argument
550
551                         mix - see below
552
553                 Initalisation Properties
554
555                         int in - in point
556                         int out - out point
557
558                 Mutable Properties
559
560                         double mix - the mix level to apply to the second frame.
561                                    - any negative value causes an automatic crossfade.
562
563                 Read Only Properties
564
565                         none
566
567                 Dependencies
568
569                         none
570
571                 Known Bugs
572
573                         Samples from the longer of the two frames are discarded.
574
575 Consumers
576 ---------
577
578         bluefish
579         
580                 Description
581
582                         BlueFish444 audio and video output module.
583                 
584                 Constructor Argument
585
586                         string video_standard - "PAL" (default) or "NTSC"
587                         
588                 Initialisation Properties
589
590                         int video_standard - 0 = PAL, 1 = NTSC
591                         
592                 Read Only Properties
593
594                         none
595                 
596                 Dependencies
597
598                         BlueVelvet SDK installed parallel to mlt in "bluefish."
599                 
600                 Known Bugs
601
602                         Does not work with any service that uses pipes!
603                         
604                         If mlt crashes, you must reload the BlueDriver kernel module
605                         due to unreleased DMA buffers.
606                         
607                         Needs an argument or property for multi-card address.
608                 
609         ffmpeg
610         
611                 Description
612                 Constructor Argument
613                 Initialisation Properties
614                 Read Only Properties
615                 Dependencies
616                 Known Bugs
617
618         sdl
619                 Description
620
621                         Simple DirectMedia Layer audio and video output module.
622                         
623                 Constructor Argument
624
625                         string video_standard - "PAL" (default), "NTSC", or "WxH"
626                         
627                 Mutable Properties
628
629                         double volume - audio level factor
630                         int video_off - if 1, disable video output
631                         int audio_off - if 1, disable audio output
632                         int scale_overlay - if 1, resample video from source pixel aspect
633                                             ratio to square pixels.
634                         
635                 Read Only Properties
636
637                         none
638                         
639                 Dependencies
640
641                         libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
642                 
643                 Known Bugs
644
645                         NTSC handling needs tightening up - sdl:NTSC is the only valid
646                         constructor for NTSC playback at the moment.
647