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