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