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                         string end - a gain value just like the gain property above.
 605                                      This causes the gain to be interpolated from 'gain' to 'end'
 606                                      over the duration.
 607
 608                         int window - the size of the normalising smoothing buffer in video frame units.
 609                                    - the smoothing buffer prevents erratic gain changes.
 610                                    - the default value is 75 video frames.
 611
 612                         gain can be applied as a factor to the normalise amplitude!
 613
 614                 Dependencies
 615
 616                         none
 617
 618                 Known Bugs
 619
 620                         none
 621
 622         resample
 623
 624                 Description
 625
 626                         Adjust an audio stream's sampling rate
 627
 628                 Constructor Argument
 629
 630                         frequency - a numeric value for the new sample rate
 631
 632                 Initialisation Properties
 633
 634                         int in - in point
 635                         int out - out point
 636
 637                 Mutable Properties
 638
 639                         int frequency - the target sample rate
 640
 641                 Dependencies
 642
 643                         libresample
 644
 645                 Known Bugs
 646
 647                         none
 648
 649         rescale
 650
 651                 Description
 652
 653                         Scale the producer video frame size to match the consumer.
 654
 655                 Constructor Argument
 656
 657                         interpolation - the rescaling method, one of:
 658                                 nearest (lowest quality, fastest),
 659                                 tiles,
 660                                 bilinear (good quality, moderate speed),
 661                                 hyper (best quality, slowest)
 662
 663                 Initialisation Properties
 664
 665                         int in - in point
 666                         int out - out point
 667
 668                 Mutable Properties
 669
 670                         string interpolation - see constructor argument above
 671
 672                         If a property "consumer_aspect_ratio" exists on the frame, then
 673                         rescaler normalises the producer's aspect ratio and maximises the
 674                         size of the frame, but may not produce the consumer's requested
 675                         dimension. Therefore, this option works best in conjunction with the
 676                         resize filter. This behavior can be disabled by another service by
 677                         either removing the property, setting it to zero, or setting
 678                         frame property "distort" to 1.
 679
 680                 Dependencies
 681
 682                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
 683
 684                 Known Bugs
 685
 686                         none
 687
 688 Transitions
 689 -----------
 690
 691         composite
 692
 693                 Description
 694
 695                         An alpha-channel based compositor for two frames.
 696
 697                 Constructor Argument
 698
 699                         string start - X,Y:WxH[:mix]
 700
 701                 Initialisation Properties
 702
 703                         string end - X,Y:WxH[:mix]
 704                         int in - in point
 705                         int out - out point
 706
 707                 Read Only Properties
 708
 709                         none
 710
 711                 Dependencies
 712
 713                         none
 714
 715                 Known Bugs
 716
 717                         Need to add field-based rendering.
 718
 719         luma
 720
 721                 Description
 722
 723                         A generic dissolve and wipe transition processor. It gets its name
 724                         from how it uses a grayscale "map" file. As the luma value varies
 725                         over time, a threshold filter is applied to the map to determine
 726                         what parts of frame A vs. frame B to show. It only reads PGM
 727                         files, but it does handle 16 bit PGM. This performs field-based
 728                         rendering.
 729
 730                 Constructor Argument
 731
 732                         string resource - the luma map file name. If not supplied, a dissolve.
 733
 734                 Initialisation Properties
 735
 736                         int in - in point
 737                         int out - out point
 738
 739                 Mutable Properties
 740
 741                         string resource - same as above
 742                         double softness - only when using a luma map, how soft to make the
 743                                           edges between A and B. 0.0 = no softness. 1.0 =
 744                                           too soft.
 745
 746                 Read Only Properties
 747
 748                         none
 749
 750                 Dependencies
 751
 752                         none
 753
 754                 Known Bugs
 755
 756                         The luma map must be the same size as the B frame.
 757                         The PGM parser does not handle comments.
 758
 759         mix
 760
 761                 Description
 762
 763                         An two stream audio mixer.
 764
 765                 Constructor Argument
 766
 767                         start - see below
 768
 769                 Initalisation Properties
 770
 771                         int in - in point
 772                         int out - out point
 773
 774                 Mutable Properties
 775
 776                         double start - the mix level to apply to the second frame.
 777                                      - any negative value causes an automatic crossfade from 0 to 1.
 778                         double end - the ending value of the mix level. mix level will be interpolated
 779                                      from start to end over the in-out range.
 780                         int reverse - set to 1 to reverse the direction of the mix.
 781
 782                 Read Only Properties
 783
 784                         none
 785
 786                 Dependencies
 787
 788                         none
 789
 790                 Known Bugs
 791
 792                         Samples from the longer of the two frames are discarded.
 793
 794 Consumers
 795 ---------
 796
 797         bluefish
 798
 799                 Description
 800
 801                         BlueFish444 audio and video output module.
 802
 803                 Constructor Argument
 804
 805                         string video_standard - "PAL" (default) or "NTSC"
 806
 807                 Initialisation Properties
 808
 809                         int video_standard - 0 = PAL, 1 = NTSC
 810
 811                 Read Only Properties
 812
 813                         none
 814
 815                 Dependencies
 816
 817                         BlueVelvet SDK installed parallel to mlt in "bluefish."
 818
 819                 Known Bugs
 820
 821                         Does not work with any service that uses pipes!
 822
 823                         If mlt crashes, you must reload the BlueDriver kernel module
 824                         due to unreleased DMA buffers.
 825
 826                         Needs an argument or property for multi-card address.
 827
 828         ffmpeg
 829
 830                 Description
 831                 Constructor Argument
 832                 Initialisation Properties
 833                 Read Only Properties
 834                 Dependencies
 835                 Known Bugs
 836
 837         libdv
 838
 839                 Description
 840
 841                         libdv dv producer.
 842
 843                 Constructor Argument
 844
 845                         string video_standard - "PAL" (default) or "NTSC"
 846
 847                 Initialisation Properties
 848                 Read Only Properties
 849                 Dependencies
 850                 Known Bugs
 851
 852         sdl
 853
 854                 Description
 855
 856                         Simple DirectMedia Layer audio and video output module.
 857
 858                 Constructor Argument
 859
 860                         string video_standard - "PAL" (default), "NTSC", or "WxH"
 861
 862                 Mutable Properties
 863
 864                         double volume - audio level factor
 865                         int video_off - if 1, disable video output
 866                         int audio_off - if 1, disable audio output
 867                         int scale_overlay - if 1, resample video from source pixel aspect
 868                                             ratio to square pixels.
 869
 870                 Read Only Properties
 871
 872                         none
 873
 874                 Dependencies
 875
 876                         libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
 877
 878                 Known Bugs
 879
 880                         NTSC handling needs tightening up - sdl:NTSC is the only valid
 881                         constructor for NTSC playback at the moment.
 882
 883         westley
 884
 885                 Description
 886
 887                         Serialise the service network to XML.
 888
 889                 Constructor Argument
 890
 891                         resource - the name of a file in which to store the XML.
 892                                 stdout is used if not supplied.
 893
 894                 Initialisation Properties
 895
 896                         string resource - same as above.
 897
 898                 Dependencies
 899
 900                         libxml2
 901
 902                 Known Bugs
 903
 904                         Untested arbitrary nesting of multitracks and playlists.
 905                         Property "id" is generated as service type followed by number if
 906                         no property named "id" exists, but it fails to guarantee uniqueness.
 907