git.sesse.net Git - mlt/blob - docs/services.txt

   1 SERVICES
   2 --------
   3
   4 Services marked as "(Proprietary)" are not distributed with the GPL version
   5 of mlt.
   6
   7 Producers
   8 ---------
   9
  10         avformat
  11
  12                 Description
  13
  14                         ffmpeg libavformat based producer for video and audio.
  15
  16                 Constructor Argument
  17
  18                         'file' - a filename specification or URL in the form:
  19                              [{protocol}|{format}]:{resource}[?{format-parameter}[&{format-parameter}...]]
  20                                  For example, video4linux:/dev/video1?width:320&height:240
  21                                  Note: on the bash command line, & must be escaped as '\&'.
  22                                          Also, note the use of ':' instead of '=' for parameters.
  23                                  Use 'ffmpeg -formats' to see a list of supported protocols
  24                                  and formats.
  25
  26                 Details
  27
  28                         Format parameters only appear to be useful with 'video4linux' or
  29                         'audio_device' formats. For 'video4linux' the parameters are
  30                         width, height, frame_rate, frame_rate_base, and standard (ntsc|pal).
  31                         For 'audio_device' the parameters are channels and sample_rate.
  32
  33                 Initialisation Properties
  34
  35                         int video_index - index of video stream to use (-1 is off)
  36                         int audio_index - index of audio stream to use (-1 is off)
  37                         int in - in point
  38                         int out - out point
  39
  40                 Read Only Properties
  41
  42                         string resource - file location
  43                         double fps - this is fixed at 25 for PAL currently
  44                         double source_fps - the framerate of the resource
  45                         double aspect_ratio - sample aspect ratio of the resource
  46                                             - this is determined on every frame read
  47
  48                 Dependencies
  49
  50                         ffmpeg must be configured as --enable-shared and installed prior
  51                         to compilation of mlt.
  52
  53                 Known Bugs
  54
  55                         Audio sync discrepancy with some content.
  56                         Not all libavformat supported formats are seekable.
  57                         Ogg Vorbis is currently broken.
  58                         MPEG seeking is inaccurate - doesn't seek to i-frames so you may
  59                         get junk for a few frames.
  60                         RAW DV seeking not supported.
  61                         Fails to play beyond first frame of video of sources with PTS not
  62                         starting at 0 (video4linux).
  63
  64         fezzik
  65
  66                 Description
  67
  68                         A friendly giant that likes to rhyme and throw rocks
  69
  70                 Constructor Argument
  71
  72                         'file'  - a filename specification:
  73                                   [{mlt-service}:]{resource} | {mlt-service}
  74                                 - can also be the name of a producer service that can
  75                                           accept the resource specified post construction.
  76
  77                 Initialisation Properties
  78
  79                         int in - in point
  80                         int out - out point
  81                         + all producer initialising properties
  82
  83                 Read Only Properties
  84
  85                         string resource - file location
  86                         + all producer read only properties
  87
  88                 Details
  89
  90                         This producer is has two roles:
  91
  92                         1. it handles the mappings of all file names to the other
  93                         producers;
  94                         2. it attaches normalising filters (rescale, resize and resample)
  95                         to the producers (when necessary).
  96
  97                         This producer simplifies many aspects of use. Essentially, it
  98                         ensures that a consumer will receive images and audio precisely as
  99                         they request them.
 100
 101                 Dependencies
 102
 103                         all.
 104
 105                 Known Bugs
 106
 107                         None.
 108
 109
 110         colour
 111
 112                 Description
 113
 114                         A simple colour generator.
 115
 116                 Constructor Argument
 117
 118                         colour - A colour value is a hexadecimal representation of RGB plus
 119                                  alpha channel as 0xrrggbbaa.
 120                                - Also colours can be the words: white, black, red, green,
 121                                  or blue.
 122                                - The default colour is black.
 123
 124                 Initialisation Properties
 125
 126                         none
 127
 128                 Read Only Properties
 129
 130                         none
 131
 132                 Dependencies
 133
 134                         none
 135
 136                 Known Bugs
 137
 138                         none
 139
 140
 141         ffmpeg (DEPRECATED)
 142
 143                 Description
 144
 145                         Test case pipe based producer for video and audio.
 146
 147                 Constructor Argument
 148
 149                         'file'  - produce a/v from file
 150                         v4l             - produce a/v from video4linux and dsp device
 151
 152                 Initialisation Properties
 153
 154                         string video_type - "file" or "v4l"
 155                         string video_file - file or v4l device
 156                         string video_size - WxH of video to produce (default: "")
 157                         int video_loop - loop video until audio exhausted (default: 0)
 158                         string audio_type - "file" or "dsp"
 159                         string audio_file - file or dsp device
 160                         int audio_rate - audio frequency (default: 48000)
 161                         int audio_channels - audio channels (default: 2)
 162                         int audio_track - audio track to use (default: 0)
 163                         int audio_loop - loop audio until video exhausted (default: 0)
 164                         int in - in point
 165                         int out - out point
 166                         double fps - output frames per second (default: 25)
 167                         double aspect_ratio - aspect ratio of video
 168
 169                 Read Only Properties
 170
 171                         string resource - file or "v4l"
 172                         int end_of_clip - holds 1 when input is exhausted
 173
 174                 Dependencies
 175
 176                         ffmpeg executable.
 177
 178                 Known Bugs
 179
 180                         in point setting is broken.
 181
 182                         Implementation does not allow fast random access.
 183
 184         libdv
 185
 186                 Description
 187
 188                         libdv based decoder for video and audio.
 189
 190                 Constructor Argument
 191
 192                         'file'  - produce a/v from file
 193
 194                 Initialisation Properties
 195
 196                         int in - in point
 197                         int out - out point
 198
 199                 Read Only Properties
 200
 201                         string resource - file location
 202                         double fps - output frames per second
 203                         int length - duration of resource (in frames)
 204
 205                 Mutable Properties
 206
 207                         string quality - one of "best," "fast" or anything else chooses
 208                                          medium.
 209
 210                 Dependencies
 211
 212                         libdv.
 213
 214                 Known Bugs
 215
 216                         DVCPRO is incorrectly identified as 16:9 aspect ratio. You must use
 217                         libdv from CVS or a post 0.101 release.
 218
 219         mcdv (Proprietary)
 220
 221                 Description
 222
 223                         MainConcept based dv decoder for video and audio.
 224
 225                 Constructor Argument
 226
 227                         'file'  - produce a/v from file
 228
 229                 Initialisation Properties
 230
 231                         int in - in point
 232                         int out - out point
 233
 234                 Read Only Properties
 235
 236                         string resource - file location
 237                         double fps - output frames per second
 238                         int length - duration of resource (in frames)
 239
 240                 Dependencies
 241
 242                         MainConcept DV or DVCPRO SDK, libdv.
 243                         "dv_sdk" installed parallel to mlt.
 244
 245                 Known Bugs
 246
 247                         None
 248
 249         mcmpeg (Proprietary)
 250
 251                 Description
 252
 253                         MainConcept based mpeg decoder for video and audio.
 254
 255                 Constructor Argument
 256
 257                         'file'  - produce a/v from file
 258
 259                 Initialisation Properties
 260
 261                         int in - in point
 262                         int out - out point
 263
 264                 Read Only Properties
 265
 266                         string resource - file location
 267                         double fps - output frames per second
 268                         double aspect_ratio - sample aspect ratio of video
 269                         int length - duration of resource (in frames)
 270
 271                 Dependencies
 272
 273                         MainConcept MPEG SDK.
 274                         "mpeg_sdk_release" installed parallel to mlt.
 275
 276                 Known Bugs
 277
 278                         None.
 279
 280         pango
 281
 282                 Description
 283
 284                         A title generator that uses the Pango international text layout
 285                         and Freetype2 font renderer.
 286
 287                 Constructor Argument
 288
 289                         string file - a text file containing Pango markup, see:
 290                         http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
 291                                     - requires xml-like encoding special chars from:
 292                                       <, >, &   -to-   &lt;, &gt;, &amp;
 293
 294                 Details
 295
 296                         Supplying a filename with extension ".txt" causes the Fezzik
 297                         producer to load with pango. If the filename begins with "+" the
 298                         pango producer interprets the filename as pango text. This is a
 299                         shortcut to embed titles in inigo commands. For westley, it is
 300                         recommended that you embed the title text in the property value.
 301
 302                         Pango has builtin scaling. It will rescale the originally rendered
 303                         title to whatever the consumer requests. Therefore, it will lose
 304                         its aspect ratio if so requested, and it is up to the consumer to
 305                         request a proper width and height that maintains the image aspect.
 306
 307                 Initialisation Properties
 308
 309                         int in - in point
 310                         int out - out point
 311
 312                 Mutable Properties
 313
 314                         string markup - a string containing Pango markup see:
 315                         http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
 316                                       - requires xml-like encoding special chars from:
 317                                         <, >, &   -to-   &lt;, &gt;, &amp;
 318                         string fgcolour - an RGBA colour specification of the text
 319                                           (i.e. 0xrrggbbaa)
 320                         string bgcolour - an RGBA colour of the background rectangle
 321                         string align - paragraph alignment: left, centre, right
 322                                      - also, numbers 0, 1 and 2 can be used respectively.
 323                         int pad - the number of pixels to pad the background rectangle
 324                                   beyond edges of text. default 0.
 325                         string markup - see constructor argument
 326                         string text - non-markup string in UTF-8 encoding (can contain
 327                                       markup chars un-encoded)
 328                         string font - the default typeface to use when not using markup.
 329                                       default "Sans 48". FreeType2 renders at 72 dpi.
 330                         string encoding - the text encoding type of the input if not UTF-8.
 331                                         - see 'iconv --list' for a list of possible inputs.
 332
 333                 Read Only Properties
 334
 335                         string resource - the text/markup file or "pango" if no file.
 336                         int real_width - the original, unscaled width of the rendered title.
 337                         int real_height - the original, unscaled height of the title.
 338                         int width - the last requested scaled image width.
 339                         int height - the last requested scaled image height.
 340
 341                 Dependencies
 342
 343                         libpango-1.0, libpangoft2-1.0, libfreetype, libgdk_pixbuf-2.0,
 344                         libglib-2.0, libgobject-2.0, libgmodule-2.0, libfontconfig.
 345
 346                 Known Bugs
 347
 348                         The foreground and background Pango markup span attributes are not
 349                         supported.
 350                         Word wrapping is not supported.
 351
 352         pixbuf
 353
 354                 Description
 355
 356                         A still graphics to video generator using gdk-pixbuf
 357
 358                 Constructor Argument
 359
 360                         'file' - The name of a graphics file loadable by
 361                                  a gdk-pixbuf loader. see /usr/lib/gdk-pixbuf/loaders
 362                                  definitely png, jpeg, tiff, pnm, and xpm
 363                                - If "%" in filename, the filename is used with sprintf
 364                                  generate a filename from a counter for multi-file/flipbook
 365                                  animation. The file sequence ends when numeric
 366                                  discontinuity >100.
 367                                - If filename contains "/.all.", suffix with an extension to
 368                                  load all pictures with matching extension from a directory.
 369                                - If filename contains the string "<svg", then pixbuf tries
 370                                  to load the filename as inline SVG XML, which is convenient
 371                                  for inigo commands.
 372
 373                 Details
 374
 375                         Pixbuf has builtin scaling. It will rescale the originally rendered
 376                         title to whatever the consumer requests. Therefore, it will lose
 377                         its aspect ratio if so requested, and it is up to the consumer to
 378                         request a proper width and height that maintains the image aspect.
 379
 380                 Initialisation Properties
 381
 382                         int in - in point
 383                         int out - out point
 384
 385                 Mutable Properties
 386
 387                         int ttl - how long (in frames) to repeat each picture in file
 388                                   sequences. default is 25.
 389
 390                 Read Only Properties
 391
 392                         string resource - file location. See Constructor Argument above.
 393                         int real_width - the original, unscaled width of the rendered title.
 394                         int real_height - the original, unscaled height of the title.
 395                         int width - the last requested scaled image width.
 396                         int height - the last requested scaled image height.
 397
 398                 Dependencies
 399
 400                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
 401
 402                 Known Bugs
 403
 404                         XXX: in/out settings are incorrectly handled.
 405
 406         ppm
 407
 408                 Description
 409
 410                         Reads a stream of contiguous PPM images.
 411
 412                 Constructor Argument
 413
 414                         command - a shell command to run something that produces ppm
 415                                   streams on stdout.
 416
 417                 Initialisation Properties
 418
 419                         none
 420
 421                 Read Only Properties
 422
 423                         string resource - the command
 424
 425                 Dependencies
 426
 427                         none
 428
 429                 Known Bugs
 430
 431                         Since it uses pipes, it is not compatible with bluefish.
 432
 433         westley
 434
 435                 Description
 436
 437                         Construct a service network from an XML description.
 438                         See docs/westley.txt.
 439
 440                 Constructor Argument
 441
 442                         file - an XML text file containing westley XML (schema pending)
 443
 444                 Read Only Properties
 445
 446                         string resource - file location
 447
 448                 Dependencies
 449
 450                         libxml2
 451
 452                 Known Bugs
 453
 454                         Non-referenced producers and playlists are not destroyed until the
 455                         network is destroyed.
 456                         A referenced producer or playlist must appear before the reference.
 457                         A filter that occurs before a producer has been defined causes a
 458                         segfault.
 459
 460         vorbis
 461
 462                 Description
 463
 464                         OGG Vorbis file reader.
 465
 466                 Constructor Argument
 467
 468                         'file' - file to use (only .ogg supported at the moment)
 469
 470                 Initialisation Properties
 471
 472                         int in - in point
 473                         int out - out point
 474
 475                 Read Only Properties
 476
 477                         double fps - this is fixed at 25 for PAL currently
 478
 479                 Dependencies
 480
 481                         libvorbisfile
 482
 483                 Known Bugs
 484
 485                         Fixed frame size (PAL audio chunks).
 486                         Doesn't cover ogg files with multiple, differing sections.
 487
 488 Filters
 489 -------
 490
 491         brightness
 492
 493                 Description
 494
 495                         Shift the luma component using a constant value.
 496
 497                 Constructor Argument
 498
 499                         start - the constant floating point numeric value to apply.
 500                               - the default is 0.
 501
 502                 Initialisation Properties
 503
 504                         int in - in point
 505                         int out - out point
 506                         double start - see Constructor Argument above.
 507                         double end - the ending adjustment value. the filter interpolates
 508                                      between the start and end adjustments over the
 509                                      duration of the effect.
 510
 511                 Read Only Properties
 512
 513                         none
 514
 515                 Dependencies
 516
 517                         none
 518
 519                 Known Bugs
 520
 521                         Does not go completely to black or white.
 522
 523
 524         channelcopy
 525
 526                 Description
 527
 528                         Copy audio from one channel to another channel.
 529
 530                 Constructor Argument
 531
 532                         to - the 0-indexed channel to copy into, default is 1.
 533
 534                 Mutable Properties
 535
 536                         int to - see above
 537                         int from - the channel from which to copy, default is 0.
 538
 539                 Dependencies
 540
 541                         none
 542
 543                 Known Bugs
 544
 545                         none
 546
 547
 548
 549         deinterlace
 550
 551                 Description
 552
 553                         Deinterlace a frame consisting of two fields using bob, weave,
 554                         greedy, one-field, and linear blend methods. This code is
 555                         appropriated from the Xine XV video output plugin.
 556
 557                 Constructor Argument
 558
 559                         method - a string containing the deinterlace method: bob, weave,
 560                                  greedy, onefield, or linearblend. The default is
 561                                          linearblend.
 562
 563                 Initialisation Properties
 564
 565                         int in - in point
 566                         int out - out point
 567
 568                 Read Only Properties
 569
 570                         none
 571
 572                 Mutable Properties
 573
 574                         string method
 575
 576                 Details
 577
 578                         If the frame properties "progressive" or "consumer_progressive"
 579                         are non-zero, then the filter is not applied. Also, if applied,
 580                         this sets the frame property "progressive" to 1.
 581
 582                 Dependencies
 583
 584                         none
 585
 586                 Known Bugs
 587
 588                         Not a bug, but it only provides fair quality.
 589
 590
 591         ffmpeg_dub
 592
 593                 Description
 594
 595                     Use ffmpeg executable to substitute audio stream.
 596
 597                 Constructor Argument
 598
 599                         file - filename of a WAV, Ogg Vorbis (--enable-vorbis),
 600                                MP3 (--enable-mp3lame), or AC-3 (--enable-a52) audio file.
 601
 602                 Initialisation Properties
 603
 604                         int in - in point
 605                         int out - out point
 606
 607                 Read Only Properties
 608
 609                         string resource - file
 610
 611                 Dependencies
 612
 613                         ffmpeg plus for ffmpeg:
 614                         libogg and libvorbis for Ogg Vorbis, libmp3lame for MP3, liba52 for AC-3.
 615
 616                 Known Bugs
 617
 618                         Uses pipes and is therefore not compatible with bluefish.
 619
 620
 621         gamma
 622
 623                 Description
 624
 625                         Adjust image luma using a non-linear power-law curve
 626
 627                 Constructor Argument
 628
 629                         gamma - a floating point value. The default is 1.0, or none.
 630
 631                 Initialisation Properties
 632
 633                         int in - in point
 634                         int out - out point
 635
 636                 Mutable Properties
 637
 638                         double gamma - the exponential factor of the power-law curve
 639
 640                 Dependencies
 641
 642                         none
 643
 644                 Known Bugs
 645
 646                         none
 647
 648
 649         greyscale
 650
 651                 Description
 652
 653                         Convert colour image to greyscale
 654
 655                 Constructor Argument
 656
 657                         none
 658
 659                 Initialisation Properties
 660
 661                         int in - in point
 662                         int out - out point
 663
 664                 Read Only Properties
 665
 666                         none
 667
 668                 Dependencies
 669
 670                         none
 671
 672                 Known Bugs
 673
 674                         none
 675
 676         luma
 677
 678                 Description
 679
 680                         Applies a luma transition between the current and next frames.
 681                         Useful for transitions from a slideshow created using producer
 682                         pixbuf.
 683
 684                 Constructor Argument
 685
 686                         file - a luma wipe
 687
 688                 Initialisation Properties
 689
 690                         int in - in point
 691                         int out - out point
 692
 693                 Read Only Properties
 694
 695                         none
 696
 697                 Mutable Properties
 698
 699                         int period - how long to wait between success iterations of the
 700                                      transition. For best results set this to a multiple
 701                                      of ttl used in pixbuf. The default is 24.
 702
 703                         luma. - all properties beginning with "luma." are passed to the
 704                                 encapsulated luma transition. For example, luma.out controls
 705                                 the duration of the wipe.
 706
 707                 Dependencies
 708
 709                         transition_luma and its dependencies
 710
 711                 Known Bugs
 712
 713                         none
 714
 715
 716         mirror
 717
 718                 Description
 719
 720                         Provides various mirror and image reversing effects.
 721
 722                 Constructor Argument
 723
 724                         mirror - horizontal, vertical, diagonal, flip, flop
 725
 726                 Initialisation Properties
 727
 728                         int reverse - being 0 or 1
 729                         int in - in point
 730                         int out - out point
 731
 732                 Read Only Properties
 733
 734                         none
 735
 736                 Mutable Properties
 737
 738                         none
 739
 740                 Dependencies
 741
 742                         none
 743
 744                 Known Bugs
 745
 746                         none
 747
 748
 749         obscure
 750
 751                 Description
 752
 753                         Obscuring filter.
 754
 755                 Constructor Argument
 756
 757                         none
 758
 759                 Initialisation Properties
 760
 761                         string start - in the format X,Y:WxH[:PWxPY]
 762                                      - PWxPY is the size of the averaging region in pixels.
 763                         string end - in the format X,Y:WxH[:PWxPY]
 764                         int in - in point
 765                         int out - out point
 766
 767                 Read Only Properties
 768
 769                         none
 770
 771                 Dependencies
 772
 773                         none
 774
 775                 Known Bugs
 776
 777                         none
 778
 779         region
 780
 781                 Description
 782
 783                         Apply one or filters to a region of the video image. The region
 784                         can be shaped as well using the alpha channel of another producer.
 785
 786                 Constructor Argument
 787
 788                         file - A file whose alpha channel will "shape"  the region.
 789                              - The string "circle" is a shortcut but it requires pixbuf with
 790                                the librsvg loader. The circle is automatically stretched
 791                                to the region to create an ellipse.
 792
 793                 Initialisation Properties
 794
 795                         int in - in point
 796                         int out - out point
 797                         plus and region transition properties
 798
 799                 Read Only Properties
 800
 801                         see the region transition
 802
 803                 Dependencies
 804
 805                         transition_region
 806
 807                 Known Bugs
 808
 809                         "circle" is unpredictable in the absence of the librsvg pixbuf loader.
 810
 811
 812         resample
 813
 814                 Description
 815
 816                         Adjust an audio stream's sampling rate, and duplicate channels if
 817                         producer provides less than consumer requested.
 818
 819                         This filter is automatically invoked by Fezzik for the sake of
 820                         normalisation over inputs and with the consumer.
 821
 822                 Constructor Argument
 823
 824                         frequency - a numeric value for the new sample rate
 825
 826                 Initialisation Properties
 827
 828                         int in - in point
 829                         int out - out point
 830
 831                 Mutable Properties
 832
 833                         int frequency - the target sample rate
 834
 835                 Dependencies
 836
 837                         libresample
 838
 839                 Known Bugs
 840
 841                         Assumes 2 channels during libsamplerate initialisation. Untested
 842                         with >2 channels.
 843
 844         rescale
 845
 846                 Description
 847
 848                         Scale the producer video frame size to match the consumer.
 849                         This filter is automatically invoked by Fezzik in order to normalise
 850                         sample aspect ratio.
 851
 852                 Constructor Argument
 853
 854                         interpolation - the rescaling method, one of:
 855                                 nearest (lowest quality, fastest),
 856                                 tiles,
 857                                 bilinear (default; good quality, moderate speed),
 858                                 hyper (best quality, slowest).
 859
 860                 Initialisation Properties
 861
 862                         int in - in point
 863                         int out - out point
 864
 865                 Mutable Properties
 866
 867                         string interpolation - see constructor argument above
 868
 869                         If a property "consumer_aspect_ratio" exists on the frame, then
 870                         rescaler normalises the producer's aspect ratio and maximises the
 871                         size of the frame, but may not produce the consumer's requested
 872                         dimension. Therefore, this option works best in conjunction with the
 873                         resize filter. This behavior can be disabled by another service by
 874                         either removing the property, setting it to zero, or setting
 875                         frame property "distort" to 1.
 876
 877                 Dependencies
 878
 879                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
 880
 881                 Known Bugs
 882
 883                         none
 884
 885         resize
 886
 887                 Description
 888
 889                         Image scaling and padding and field order adjustment.
 890
 891                 Details
 892
 893                         Normally resize is used to pad the producer's
 894                         output to what the consumer has requested after an upstream rescale
 895                         filter first scales the image to maximise usage of the image area.
 896                         This filter also adjusts the field order to lower field first
 897                         if the frame property "top_field_first" has been set to 1.
 898                         Therefore, when done, it sets the top_field_first to 0.
 899                         This filter is automatically invoked by Fezzik as part of image
 900                         sample aspect ratio normalisation.
 901
 902                 Constructor Argument
 903
 904                         scale - "affine" to use affine transform scaling, otherwise
 905                                  center and pad.
 906
 907                 Initialisation Properties
 908
 909                         int in - in point
 910                         int out - out point
 911
 912                 Read Only Properties
 913
 914                         none
 915
 916                 Dependencies
 917
 918                         none
 919
 920                 Known Bugs
 921
 922                         Assumes lower field first output.
 923
 924         volume
 925
 926                 Description
 927
 928                         Adjust an audio stream's volume level
 929
 930                 Constructor Argument
 931
 932                         gain - a string containing one of:
 933                                  - a floating point value of the gain adjustment
 934                                  - a numeric value with the suffix "dB" to adjust in terms of decibels
 935                                  - "normalise" to normalise the volume to the target amplitude -12dBFS
 936
 937                 Initialisation Properties
 938
 939                         int in - in point
 940                         int out - out point
 941                         int window - the number of video frames over which to smooth normalisation.
 942                                      defaults to 75.
 943
 944                 Mutable Properties
 945
 946                         string gain - same as constructor argument above
 947
 948                         string normalise - normalise the volume to the amplitude:
 949                                 - a numeric value with the suffix "dB" to set amplitude in decibels
 950                                 - a floating point value of the relative volume
 951                                 - an unspecified value uses the default -12dBFS
 952
 953                         string limiter - limit all samples above:
 954                                 - a numeric value with the suffix "dB"
 955                                 - a floating point value ( dB = 20 * log10(x) )
 956                                 - an unspecified value uses the default -6dBFS
 957
 958                         double max_gain - a floating point or decibel value of the maximum gain that
 959                                 can be applied during normalisation.
 960                                 - an unspecified value uses the default 20dB
 961
 962                         string end - a gain value just like the gain property above.
 963                                      This causes the gain to be interpolated from 'gain' to 'end'
 964                                      over the duration.
 965
 966                         int window - the size of the normalising smoothing buffer in video frame units.
 967                                    - the smoothing buffer prevents erratic gain changes.
 968                                    - the default value is 75 video frames.
 969
 970                         gain can be applied as a factor to the normalise amplitude!
 971
 972                 Dependencies
 973
 974                         none
 975
 976                 Known Bugs
 977
 978                         none
 979
 980         watermark
 981
 982                 Description
 983
 984                         Add a watermark to the frames.
 985
 986                 Constructor Argument
 987
 988                         resource - the producer to use (ie: a .png)
 989
 990                 Initialisation Properties
 991
 992                         string resource - the producer to use
 993                         string factory - producer required for the resource ('fezzik')
 994                         string geometry - composite geometry
 995                         string distort - control scaling
 996                         int in - in point
 997                         int out - out point
 998
 999                 Mutable Properties
1000
1001                         none
1002
1003                 Dependencies
1004
1005                         mlt core modules and optionally, fezzik
1006
1007                 Known Bugs
1008
1009                         none
1010
1011 Transitions
1012 -----------
1013
1014         composite
1015
1016                 Description
1017
1018                         A key-framable alpha-channel compositor for two frames.
1019
1020                 Details
1021
1022                         Performs dissolves and luma wipes in addition to alpha compositing.
1023
1024                         By default, the aspect ratio of the B frame is respected and the
1025                         size portion of the geometry specification simply defines a
1026                         bounding rectangle.
1027
1028                         This performs field-based rendering unless the A frame property
1029                         "progressive" or "consumer_progressive" or the transition property
1030                         "progressive" is set to 1.
1031
1032                 Constructor Argument
1033
1034                         string start - a geometry specification as X,Y:WxH[!][:mix]
1035                                      - X, Y, W, H are assumed to pixel units unless they
1036                                        have the suffix '%'
1037                                      - '!' is a shortcut to specify distort, see below.
1038                                      - mix is always a 2 digit percentage, defaults to 100.
1039                                                  - default is "85%,5%:10%x10%"
1040
1041                 Initialisation Properties
1042
1043                         string end - the ending size and position.
1044                         string key[F] - X,Y:WxH[:mix] - set a key frame for geometry between
1045                                         the in and out. F is a frame number and can be
1046                                         negative to make it relative to the out point.
1047                         int in - in point
1048                         int out - out point
1049                         string factory - The name of a factory service used as a non-PGM
1050                                          producer loader. The default is fezzik.
1051
1052                 Read Only Properties
1053
1054                         none
1055
1056                 Mutable Properties
1057
1058                         int progressive - set to 1 to disable field-based rendering.
1059                         string distort - when set, causes the B frame image to fill the WxH
1060                                          completely with no regard to B's aspect ratio.
1061                         string halign - when not distorting, set the horizontal alignment
1062                                         of B within the geometry rectangle.
1063                                       - one of: left (0), centre (1), or right (2).
1064                                       - the default is left.
1065                         string valign - when not distorting, set the vertical alignment of
1066                                         B within the geometry rectangle.
1067                                       - one of: top (0), middle (1), or bottom (2).
1068                                       - the default is top.
1069                         string luma - the luma map file name. If not supplied, a dissolve.
1070                         double softness - only when using a luma map, how soft to make the
1071                                           edges between A and B. 0.0 = no softness. 1.0 =
1072                                           too soft.
1073                         Any property starting with "luma." is passed to the non-PGM luma
1074                             producer.
1075
1076                 Dependencies
1077
1078                         none
1079
1080                 Known Bugs
1081
1082                         Assumes lower field first during field rendering.
1083
1084         luma
1085
1086                 Description
1087
1088                         A generic dissolve and wipe transition processor.
1089
1090                 Details
1091
1092                         luma gets its name
1093                         from how it uses a grayscale "map" file. As the luma value varies
1094                         over time, a threshold filter is applied to the map to determine
1095                         what parts of frame A vs. frame B to show. It reads PGM files
1096                         up to 16 bits! Alternatively, it can use the first frame from any
1097                         producer that outputs yuv, but it will be limited to the luma
1098                         gamut of 220 values.
1099                         This performs field-based rendering unless the A frame property
1100                         "progressive" or "consumer_progressive" or the transition property
1101                         "progressive" is set to 1.
1102
1103                 Constructor Argument
1104
1105                         string resource - the luma map file name - either PGM or any other
1106                                           producable video.
1107                                         - If not supplied, a dissolve.
1108
1109                 Initialisation Properties
1110
1111                         int in - in point
1112                         int out - out point
1113                         string factory - The name of a factory service used as a non-PGM
1114                                          producer loader. The default is Fezzik.
1115
1116                 Mutable Properties
1117
1118                         string resource - same as above
1119                         double softness - only when using a luma map, how soft to make the
1120                                           edges between A and B. 0.0 = no softness. 1.0 =
1121                                           too soft.
1122                         Any property starting with "producer." is passed to the non-PGM luma
1123                             producer.
1124
1125                 Read Only Properties
1126
1127                         none
1128
1129                 Dependencies
1130
1131                         none
1132
1133                 Known Bugs
1134
1135                         Assumes lower field first output.
1136
1137         mix
1138
1139                 Description
1140
1141                         An two stream audio mixer.
1142
1143                 Constructor Argument
1144
1145                         start - see below
1146
1147                 Initalisation Properties
1148
1149                         int in - in point
1150                         int out - out point
1151
1152                 Mutable Properties
1153
1154                         double start - the mix level to apply to the second frame.
1155                                      - any negative value causes an automatic crossfade from 0 to 1.
1156                         double end - the ending value of the mix level. mix level will be interpolated
1157                                      from start to end over the in-out range.
1158                         int reverse - set to 1 to reverse the direction of the mix.
1159
1160                 Read Only Properties
1161
1162                         none
1163
1164                 Dependencies
1165
1166                         none
1167
1168                 Known Bugs
1169
1170                         Samples from the longer of the two frames are discarded.
1171
1172
1173         region
1174
1175                 Description
1176
1177                         Apply zero or more filters to B frame as it is composited onto
1178                         a region of the A frame. The "shape" of the region can be defined
1179                         by the alpha channel of a third producer.
1180
1181                 Constructor Argument
1182
1183                         resource - a shape producer
1184
1185                 Initialisation Properties
1186
1187                         string resource - nothing is rectangle, "circle" is a pixbuf-
1188                             generated SVG circle, anything else is loaded by the factory.
1189                         string factory - the service that creates the shape producer.
1190                                        - the default is fezzik.
1191                         string filter[N] - one or more filters to apply. All filter
1192                                            properties are passed using the same filter "key"
1193                         Any property starting with "composite." is passed to the
1194                             encapsulated composite transition.
1195
1196                 Read Only Properties
1197
1198                         none
1199
1200                 Dependencies
1201
1202                         transition_composite
1203
1204                 Known Bugs
1205
1206                         none
1207
1208
1209 Consumers
1210 ---------
1211
1212         bluefish (Proprietary)
1213
1214                 Description
1215
1216                         BlueFish444 audio and video output module.
1217
1218                 Constructor Argument
1219
1220                         card - a numeric card id starting at 1, default is 1.
1221
1222                 Initialisation Properties
1223
1224                         string standard - "PAL" (default) or "NTSC"
1225                                         - default is based upon MLT_NORMALISATION
1226                                                           environment variable, which defaults to PAL.
1227                         int frames - the number of DMA video frames. default is 4.
1228                                      minimum is 2. maximum on my system is 11.
1229                         int buffer - the number of frames to buffer within MLT, minimum 1,
1230                                      default 25.
1231                         string rescale - a rescale method, see the Filters/rescale.
1232
1233                 Read Only Properties
1234
1235                         none
1236
1237                 Dependencies
1238
1239                         BlueVelvet SDK installed parallel to mlt in "bluefish."
1240
1241                 Known Bugs
1242
1243                         Does not work with any service that uses pipes!
1244
1245                         If mlt crashes, you might need to reload the BlueDriver kernel
1246                         module due to unreleased DMA buffers.
1247
1248                         Only supports 2 channel audio at the moment.
1249
1250         libdv
1251
1252                 Description
1253
1254                         libdv dv producer.
1255
1256                 Constructor Argument
1257
1258                         string target - the filename to write to, e.g. /dev/dv1394.
1259
1260                 Initialisation Properties
1261
1262                         int buffer - the number of frames to buffer, minimum 1, default 25.
1263                         string rescale - a rescale method, see the Filters/rescale.
1264
1265                 Mutable Properties
1266
1267                         int progressive - indicates whether to use progressive or field-
1268                                           based rendering, default 0 (off).
1269
1270                 Read Only Properties
1271
1272                         none
1273
1274                 Dependencies
1275
1276                         libdv
1277
1278                 Known Bugs
1279
1280                         none
1281
1282         sdl
1283
1284                 Description
1285
1286                         Simple DirectMedia Layer audio and video output module.
1287
1288                 Constructor Argument
1289
1290                         string video_standard - "PAL" (default), "NTSC", or "WxH"
1291
1292                 Initialisation Properties
1293
1294                         int buffer - the number of frames to buffer, minimum 1, default 25.
1295                         string rescale - a rescale method, see the Filters/rescale.
1296                                        - Hint: "none" works very good with SDL output.
1297
1298                 Mutable Properties
1299
1300                         double volume - audio level factor
1301                         int video_off - if 1, disable video output
1302                         int audio_off - if 1, disable audio output
1303                         int scale_overlay - if 1, resample video from source pixel aspect
1304                                             ratio to square pixels.
1305                         int progressive - indicates whether to use progressive or field-
1306                                           based rendering, default 0 (off).
1307
1308                 Read Only Properties
1309
1310                         none
1311
1312                 Dependencies
1313
1314                         libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
1315
1316                 Known Bugs
1317
1318                         none
1319
1320         westley
1321
1322                 Description
1323
1324                         Serialise the service network to XML.
1325                         See docs/westley.txt for more information.
1326
1327                 Constructor Argument
1328
1329                         resource - the name of a file in which to store the XML.
1330                                   - stdout is default.
1331
1332                 Initialisation Properties
1333
1334                         string resource - same as above.
1335
1336                 Dependencies
1337
1338                         libxml2
1339
1340                 Known Bugs
1341
1342                         Untested arbitrary nesting of multitracks and playlists.
1343                         Property "id" is generated as service type followed by number if
1344                         no property named "id" exists, but it fails to guarantee uniqueness.