git.sesse.net Git - mlt/blob - 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                         int window - the number of video frames over which to smooth normalisation.
 527                                      defaults to 75.
 528
 529                 Mutable Properties
 530
 531                         string gain - same as constructor argument above
 532
 533                         string normalise - normalise the volume to the amplitude:
 534                                 - a numeric value with the suffix "dB" to set amplitude in decibels
 535                                 - a floating point value of the relative volume
 536                                 - an unspecified value uses the default -12dBFS
 537
 538                         string limiter - limit all samples above:
 539                                 - a numeric value with the suffix "dB"
 540                                 - a floating point value ( dB = 20 * log10(x) )
 541                                 - an unspecified value uses the default -6dBFS
 542
 543                         double max_gain - a floating point or decibel value of the maximum gain that
 544                                 can be applied during normalisation.
 545                                 - an unspecified value uses the default 20dB
 546
 547                 Dependencies
 548
 549                         none
 550
 551                 Known Bugs
 552
 553                         none
 554
 555         resample
 556
 557                 Description
 558
 559                         Adjust an audio stream's sampling rate
 560
 561                 Constructor Argument
 562
 563                         frequency - a numeric value for the new sample rate
 564
 565                 Initialisation Properties
 566
 567                         int in - in point
 568                         int out - out point
 569
 570                 Mutable Properties
 571
 572                         int frequency - the target sample rate
 573
 574                 Dependencies
 575
 576                         libresample
 577
 578                 Known Bugs
 579
 580                         none
 581
 582         rescale
 583
 584                 Description
 585
 586                         Scale the producer video frame size to match the consumer.
 587
 588                 Constructor Argument
 589
 590                         interpolation - the rescaling method, one of:
 591                                 nearest (lowest quality, fastest),
 592                                 tiles,
 593                                 bilinear (good quality, moderate speed),
 594                                 hyper (best quality, slowest)
 595
 596                 Initialisation Properties
 597
 598                         int in - in point
 599                         int out - out point
 600
 601                 Mutable Properties
 602
 603                         string interpolation - see constructor argument above
 604
 605                 Dependencies
 606
 607                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
 608
 609                 Known Bugs
 610
 611                         none
 612
 613 Transitions
 614 -----------
 615
 616         composite
 617
 618                 Description
 619
 620                         An alpha-channel based compositor for two frames.
 621
 622                 Constructor Argument
 623
 624                         mix - see below
 625
 626                 Initialisation Properties
 627
 628                         int in - in point
 629                         int out - out point
 630
 631                 Mutable Properties
 632
 633                         int x - the horizontal offset from the left edge of the frame
 634                         int y - the vertical offset from the top edge of the frame
 635                         double mix - the opacity factor to apply to the second frame
 636                                      (used in addition to alpha channel).
 637                                    - any negative value causes an automatic dissolve
 638
 639                 Read Only Properties
 640
 641                         none
 642
 643                 Dependencies
 644
 645                         none
 646
 647                 Known Bugs
 648
 649                         Need to add field-based rendering.
 650
 651         luma
 652
 653                 Description
 654
 655                         A generic dissolve and wipe transition processor. It gets its name
 656                         from how it uses a grayscale "map" file. As the luma value varies
 657                         over time, a threshold filter is applied to the map to determine
 658                         what parts of frame A vs. frame B to show. It only reads PGM
 659                         files, but it does handle 16 bit PGM. This performs field-based
 660                         rendering.
 661
 662                 Constructor Argument
 663
 664                         string resource - the luma map file name. If not supplied, a dissolve.
 665
 666                 Initialisation Properties
 667
 668                         int in - in point
 669                         int out - out point
 670
 671                 Mutable Properties
 672
 673                         string resource - same as above
 674                         double softness - only when using a luma map, how soft to make the
 675                                           edges between A and B. 0.0 = no softness. 1.0 =
 676                                           too soft.
 677
 678                 Read Only Properties
 679
 680                         none
 681
 682                 Dependencies
 683
 684                         none
 685
 686                 Known Bugs
 687
 688                         The luma map must be the same size as the B frame.
 689                         The PGM parser does not handle comments.
 690
 691         mix
 692
 693                 Description
 694
 695                         An two stream audio mixer.
 696
 697                 Constructor Argument
 698
 699                         mix - see below
 700
 701                 Initalisation Properties
 702
 703                         int in - in point
 704                         int out - out point
 705
 706                 Mutable Properties
 707
 708                         double mix - the mix level to apply to the second frame.
 709                                    - any negative value causes an automatic crossfade.
 710
 711                 Read Only Properties
 712
 713                         none
 714
 715                 Dependencies
 716
 717                         none
 718
 719                 Known Bugs
 720
 721                         Samples from the longer of the two frames are discarded.
 722
 723 Consumers
 724 ---------
 725
 726         bluefish
 727
 728                 Description
 729
 730                         BlueFish444 audio and video output module.
 731
 732                 Constructor Argument
 733
 734                         string video_standard - "PAL" (default) or "NTSC"
 735
 736                 Initialisation Properties
 737
 738                         int video_standard - 0 = PAL, 1 = NTSC
 739
 740                 Read Only Properties
 741
 742                         none
 743
 744                 Dependencies
 745
 746                         BlueVelvet SDK installed parallel to mlt in "bluefish."
 747
 748                 Known Bugs
 749
 750                         Does not work with any service that uses pipes!
 751
 752                         If mlt crashes, you must reload the BlueDriver kernel module
 753                         due to unreleased DMA buffers.
 754
 755                         Needs an argument or property for multi-card address.
 756
 757         ffmpeg
 758
 759                 Description
 760                 Constructor Argument
 761                 Initialisation Properties
 762                 Read Only Properties
 763                 Dependencies
 764                 Known Bugs
 765
 766         libdv
 767
 768                 Description
 769
 770                         libdv dv producer.
 771
 772                 Constructor Argument
 773
 774                         string video_standard - "PAL" (default) or "NTSC"
 775
 776                 Initialisation Properties
 777                 Read Only Properties
 778                 Dependencies
 779                 Known Bugs
 780
 781         sdl
 782
 783                 Description
 784
 785                         Simple DirectMedia Layer audio and video output module.
 786
 787                 Constructor Argument
 788
 789                         string video_standard - "PAL" (default), "NTSC", or "WxH"
 790
 791                 Mutable Properties
 792
 793                         double volume - audio level factor
 794                         int video_off - if 1, disable video output
 795                         int audio_off - if 1, disable audio output
 796                         int scale_overlay - if 1, resample video from source pixel aspect
 797                                             ratio to square pixels.
 798
 799                 Read Only Properties
 800
 801                         none
 802
 803                 Dependencies
 804
 805                         libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
 806
 807                 Known Bugs
 808
 809                         NTSC handling needs tightening up - sdl:NTSC is the only valid
 810                         constructor for NTSC playback at the moment.
 811
 812         westley
 813
 814                 Description
 815
 816                         Serialise the service network to XML.
 817
 818                 Constructor Argument
 819
 820                         resource - the name of a file in which to store the XML.
 821                                 stdout is used if not supplied.
 822
 823                 Initialisation Properties
 824
 825                         string resource - same as above.
 826
 827                 Dependencies
 828
 829                         libxml2
 830
 831                 Known Bugs
 832
 833                         Untested arbitrary nesting of multitracks and playlists.
 834                         Property "id" is generated as service type followed by number if
 835                         no property named "id" exists, but it fails to guarantee uniqueness.
 836