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                         If you need to embed Pango markup in a westley XML file, then
 302                         enclose the value inside "<![CDATA[ ... ]]>".
 303
 304                         Pango has builtin scaling. It will rescale the originally rendered
 305                         title to whatever the consumer requests. Therefore, it will lose
 306                         its aspect ratio if so requested, and it is up to the consumer to
 307                         request a proper width and height that maintains the image aspect.
 308
 309                 Initialisation Properties
 310
 311                         int in - in point
 312                         int out - out point
 313
 314                 Mutable Properties
 315
 316                         string markup - a UTF-8 string containing Pango markup see:
 317                         http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
 318                                       - requires xml-like encoding special chars from:
 319                                         <, >, &   -to-   &lt;, &gt;, &amp;
 320                         string fgcolour - an RGBA colour specification of the text
 321                                           (i.e. 0xrrggbbaa)
 322                         string bgcolour - an RGBA colour of the background rectangle
 323                         string align - paragraph alignment: left, centre, right
 324                                      - also, numbers 0, 1 and 2 can be used respectively.
 325                         int pad - the number of pixels to pad the background rectangle
 326                                   beyond edges of text. default 0.
 327                         string markup - see constructor argument
 328                         string text - non-markup string in UTF-8 encoding (can contain
 329                                       markup chars un-encoded)
 330                         string font - the default typeface to use when not using markup.
 331                                       default "Sans 48". FreeType2 renders at 72 dpi.
 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. For westley XML, set the resource
 372                                  property value with inline XML embedded using a CDATA node
 373                                  ("<![CDATA[ ... ]]>").
 374
 375                 Details
 376
 377                         Pixbuf has builtin scaling. It will rescale the originally rendered
 378                         title to whatever the consumer requests. Therefore, it will lose
 379                         its aspect ratio if so requested, and it is up to the consumer to
 380                         request a proper width and height that maintains the image aspect.
 381
 382                 Initialisation Properties
 383
 384                         int in - in point
 385                         int out - out point
 386
 387                 Mutable Properties
 388
 389                         int ttl - how long (in frames) to repeat each picture in file
 390                                   sequences. default is 25.
 391
 392                 Read Only Properties
 393
 394                         string resource - file location. See Constructor Argument above.
 395                         int real_width - the original, unscaled width of the rendered title.
 396                         int real_height - the original, unscaled height of the title.
 397                         int width - the last requested scaled image width.
 398                         int height - the last requested scaled image height.
 399
 400                 Dependencies
 401
 402                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
 403
 404                 Known Bugs
 405
 406                         XXX: in/out settings are incorrectly handled.
 407
 408         ppm
 409
 410                 Description
 411
 412                         Reads a stream of contiguous PPM images.
 413
 414                 Constructor Argument
 415
 416                         command - a shell command to run something that produces ppm
 417                                   streams on stdout.
 418
 419                 Initialisation Properties
 420
 421                         none
 422
 423                 Read Only Properties
 424
 425                         string resource - the command
 426
 427                 Dependencies
 428
 429                         none
 430
 431                 Known Bugs
 432
 433                         Since it uses pipes, it is not compatible with bluefish.
 434
 435         westley
 436
 437                 Description
 438
 439                         Construct a service network from an XML description.
 440                         See docs/westley.txt.
 441
 442                 Constructor Argument
 443
 444                         file - an XML text file containing westley XML (schema pending)
 445
 446                 Read Only Properties
 447
 448                         string resource - file location
 449
 450                 Dependencies
 451
 452                         libxml2
 453
 454                 Known Bugs
 455
 456                         Non-referenced producers and playlists are not destroyed until the
 457                         network is destroyed.
 458                         A referenced producer or playlist must appear before the reference.
 459                         A filter that occurs before a producer has been defined causes a
 460                         segfault.
 461
 462         vorbis
 463
 464                 Description
 465
 466                         OGG Vorbis file reader.
 467
 468                 Constructor Argument
 469
 470                         'file' - file to use (only .ogg supported at the moment)
 471
 472                 Initialisation Properties
 473
 474                         int in - in point
 475                         int out - out point
 476
 477                 Read Only Properties
 478
 479                         double fps - this is fixed at 25 for PAL currently
 480
 481                 Dependencies
 482
 483                         libvorbisfile
 484
 485                 Known Bugs
 486
 487                         Fixed frame size (PAL audio chunks).
 488                         Doesn't cover ogg files with multiple, differing sections.
 489
 490 Filters
 491 -------
 492
 493         brightness
 494
 495                 Description
 496
 497                         Shift the luma component using a constant value.
 498
 499                 Constructor Argument
 500
 501                         start - the constant floating point numeric value to apply.
 502                               - the default is 0.
 503
 504                 Initialisation Properties
 505
 506                         int in - in point
 507                         int out - out point
 508                         double start - see Constructor Argument above.
 509                         double end - the ending adjustment value. the filter interpolates
 510                                      between the start and end adjustments over the
 511                                      duration of the effect.
 512
 513                 Read Only Properties
 514
 515                         none
 516
 517                 Dependencies
 518
 519                         none
 520
 521                 Known Bugs
 522
 523                         Does not go completely to black or white.
 524
 525
 526         channelcopy
 527
 528                 Description
 529
 530                         Copy audio from one channel to another channel.
 531
 532                 Constructor Argument
 533
 534                         to - the 0-indexed channel to copy into, default is 1.
 535
 536                 Mutable Properties
 537
 538                         int to - see above
 539                         int from - the channel from which to copy, default is 0.
 540
 541                 Dependencies
 542
 543                         none
 544
 545                 Known Bugs
 546
 547                         none
 548
 549
 550
 551         deinterlace
 552
 553                 Description
 554
 555                         Deinterlace a frame consisting of two fields using bob, weave,
 556                         greedy, one-field, and linear blend methods. This code is
 557                         appropriated from the Xine XV video output plugin.
 558
 559                 Constructor Argument
 560
 561                         method - a string containing the deinterlace method: bob, weave,
 562                                  greedy, onefield, or linearblend. The default is
 563                                          linearblend.
 564
 565                 Initialisation Properties
 566
 567                         int in - in point
 568                         int out - out point
 569
 570                 Read Only Properties
 571
 572                         none
 573
 574                 Mutable Properties
 575
 576                         string method
 577
 578                 Details
 579
 580                         If the frame properties "progressive" or "consumer_progressive"
 581                         are non-zero, then the filter is not applied. Also, if applied,
 582                         this sets the frame property "progressive" to 1.
 583
 584                 Dependencies
 585
 586                         none
 587
 588                 Known Bugs
 589
 590                         Not a bug, but it only provides fair quality.
 591
 592
 593         ffmpeg_dub
 594
 595                 Description
 596
 597                     Use ffmpeg executable to substitute audio stream.
 598
 599                 Constructor Argument
 600
 601                         file - filename of a WAV, Ogg Vorbis (--enable-vorbis),
 602                                MP3 (--enable-mp3lame), or AC-3 (--enable-a52) audio file.
 603
 604                 Initialisation Properties
 605
 606                         int in - in point
 607                         int out - out point
 608
 609                 Read Only Properties
 610
 611                         string resource - file
 612
 613                 Dependencies
 614
 615                         ffmpeg plus for ffmpeg:
 616                         libogg and libvorbis for Ogg Vorbis, libmp3lame for MP3, liba52 for AC-3.
 617
 618                 Known Bugs
 619
 620                         Uses pipes and is therefore not compatible with bluefish.
 621
 622
 623         gamma
 624
 625                 Description
 626
 627                         Adjust image luma using a non-linear power-law curve
 628
 629                 Constructor Argument
 630
 631                         gamma - a floating point value. The default is 1.0, or none.
 632
 633                 Initialisation Properties
 634
 635                         int in - in point
 636                         int out - out point
 637
 638                 Mutable Properties
 639
 640                         double gamma - the exponential factor of the power-law curve
 641
 642                 Dependencies
 643
 644                         none
 645
 646                 Known Bugs
 647
 648                         none
 649
 650
 651         greyscale
 652
 653                 Description
 654
 655                         Convert colour image to greyscale
 656
 657                 Constructor Argument
 658
 659                         none
 660
 661                 Initialisation Properties
 662
 663                         int in - in point
 664                         int out - out point
 665
 666                 Read Only Properties
 667
 668                         none
 669
 670                 Dependencies
 671
 672                         none
 673
 674                 Known Bugs
 675
 676                         none
 677
 678         luma
 679
 680                 Description
 681
 682                         Applies a luma transition between the current and next frames.
 683                         Useful for transitions from a slideshow created using producer
 684                         pixbuf.
 685
 686                 Constructor Argument
 687
 688                         file - a luma wipe
 689
 690                 Initialisation Properties
 691
 692                         int in - in point
 693                         int out - out point
 694
 695                 Read Only Properties
 696
 697                         none
 698
 699                 Mutable Properties
 700
 701                         int period - how long to wait between success iterations of the
 702                                      transition. For best results set this to a multiple
 703                                      of ttl used in pixbuf. The default is 24.
 704
 705                         luma. - all properties beginning with "luma." are passed to the
 706                                 encapsulated luma transition. For example, luma.out controls
 707                                 the duration of the wipe.
 708
 709                 Dependencies
 710
 711                         transition_luma and its dependencies
 712
 713                 Known Bugs
 714
 715                         none
 716
 717
 718         mirror
 719
 720                 Description
 721
 722                         Provides various mirror and image reversing effects.
 723
 724                 Constructor Argument
 725
 726                         mirror - horizontal, vertical, diagonal, flip, flop
 727
 728                 Initialisation Properties
 729
 730                         int reverse - being 0 or 1
 731                         int in - in point
 732                         int out - out point
 733
 734                 Read Only Properties
 735
 736                         none
 737
 738                 Mutable Properties
 739
 740                         none
 741
 742                 Dependencies
 743
 744                         none
 745
 746                 Known Bugs
 747
 748                         none
 749
 750
 751         obscure
 752
 753                 Description
 754
 755                         Obscuring filter.
 756
 757                 Constructor Argument
 758
 759                         none
 760
 761                 Initialisation Properties
 762
 763                         string start - in the format X,Y:WxH[:PWxPY]
 764                                      - PWxPY is the size of the averaging region in pixels.
 765                         string end - in the format X,Y:WxH[:PWxPY]
 766                         int in - in point
 767                         int out - out point
 768
 769                 Read Only Properties
 770
 771                         none
 772
 773                 Dependencies
 774
 775                         none
 776
 777                 Known Bugs
 778
 779                         none
 780
 781         region
 782
 783                 Description
 784
 785                         Apply one or filters to a region of the video image. The region
 786                         can be shaped as well using the alpha channel of another producer.
 787
 788                 Constructor Argument
 789
 790                         file - A file whose alpha channel will "shape"  the region.
 791                              - The string "circle" is a shortcut but it requires pixbuf with
 792                                the librsvg loader. The circle is automatically stretched
 793                                to the region to create an ellipse.
 794
 795                 Initialisation Properties
 796
 797                         int in - in point
 798                         int out - out point
 799                         plus and region transition properties
 800
 801                 Read Only Properties
 802
 803                         see the region transition
 804
 805                 Dependencies
 806
 807                         transition_region
 808
 809                 Known Bugs
 810
 811                         "circle" is unpredictable in the absence of the librsvg pixbuf loader.
 812
 813
 814         resample
 815
 816                 Description
 817
 818                         Adjust an audio stream's sampling rate, and duplicate channels if
 819                         producer provides less than consumer requested.
 820
 821                         This filter is automatically invoked by Fezzik for the sake of
 822                         normalisation over inputs and with the consumer.
 823
 824                 Constructor Argument
 825
 826                         frequency - a numeric value for the new sample rate
 827
 828                 Initialisation Properties
 829
 830                         int in - in point
 831                         int out - out point
 832
 833                 Mutable Properties
 834
 835                         int frequency - the target sample rate
 836
 837                 Dependencies
 838
 839                         libresample
 840
 841                 Known Bugs
 842
 843                         Assumes 2 channels during libsamplerate initialisation. Untested
 844                         with >2 channels.
 845
 846         rescale
 847
 848                 Description
 849
 850                         Scale the producer video frame size to match the consumer.
 851                         This filter is automatically invoked by Fezzik in order to normalise
 852                         sample aspect ratio.
 853
 854                 Constructor Argument
 855
 856                         interpolation - the rescaling method, one of:
 857                                 nearest (lowest quality, fastest),
 858                                 tiles,
 859                                 bilinear (default; good quality, moderate speed),
 860                                 hyper (best quality, slowest).
 861
 862                 Initialisation Properties
 863
 864                         int in - in point
 865                         int out - out point
 866
 867                 Mutable Properties
 868
 869                         string interpolation - see constructor argument above
 870
 871                         If a property "consumer_aspect_ratio" exists on the frame, then
 872                         rescaler normalises the producer's aspect ratio and maximises the
 873                         size of the frame, but may not produce the consumer's requested
 874                         dimension. Therefore, this option works best in conjunction with the
 875                         resize filter. This behavior can be disabled by another service by
 876                         either removing the property, setting it to zero, or setting
 877                         frame property "distort" to 1.
 878
 879                 Dependencies
 880
 881                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
 882
 883                 Known Bugs
 884
 885                         none
 886
 887         resize
 888
 889                 Description
 890
 891                         Image scaling and padding and field order adjustment.
 892
 893                 Details
 894
 895                         Normally resize is used to pad the producer's
 896                         output to what the consumer has requested after an upstream rescale
 897                         filter first scales the image to maximise usage of the image area.
 898                         This filter also adjusts the field order to lower field first
 899                         if the frame property "top_field_first" has been set to 1.
 900                         Therefore, when done, it sets the top_field_first to 0.
 901                         This filter is automatically invoked by Fezzik as part of image
 902                         sample aspect ratio normalisation.
 903
 904                 Constructor Argument
 905
 906                         scale - "affine" to use affine transform scaling, otherwise
 907                                  center and pad.
 908
 909                 Initialisation Properties
 910
 911                         int in - in point
 912                         int out - out point
 913
 914                 Read Only Properties
 915
 916                         none
 917
 918                 Dependencies
 919
 920                         none
 921
 922                 Known Bugs
 923
 924                         Assumes lower field first output.
 925
 926         volume
 927
 928                 Description
 929
 930                         Adjust an audio stream's volume level
 931
 932                 Constructor Argument
 933
 934                         gain - a string containing one of:
 935                                  - a floating point value of the gain adjustment
 936                                  - a numeric value with the suffix "dB" to adjust in terms of decibels
 937                                  - "normalise" to normalise the volume to the target amplitude -12dBFS
 938
 939                 Initialisation Properties
 940
 941                         int in - in point
 942                         int out - out point
 943                         int window - the number of video frames over which to smooth normalisation.
 944                                      defaults to 75.
 945
 946                 Mutable Properties
 947
 948                         string gain - same as constructor argument above
 949
 950                         string normalise - normalise the volume to the amplitude:
 951                                 - a numeric value with the suffix "dB" to set amplitude in decibels
 952                                 - a floating point value of the relative volume
 953                                 - an unspecified value uses the default -12dBFS
 954
 955                         string limiter - limit all samples above:
 956                                 - a numeric value with the suffix "dB"
 957                                 - a floating point value ( dB = 20 * log10(x) )
 958                                 - an unspecified value uses the default -6dBFS
 959
 960                         double max_gain - a floating point or decibel value of the maximum gain that
 961                                 can be applied during normalisation.
 962                                 - an unspecified value uses the default 20dB
 963
 964                         string end - a gain value just like the gain property above.
 965                                      This causes the gain to be interpolated from 'gain' to 'end'
 966                                      over the duration.
 967
 968                         int window - the size of the normalising smoothing buffer in video frame units.
 969                                    - the smoothing buffer prevents erratic gain changes.
 970                                    - the default value is 75 video frames.
 971
 972                         gain can be applied as a factor to the normalise amplitude!
 973
 974                 Dependencies
 975
 976                         none
 977
 978                 Known Bugs
 979
 980                         none
 981
 982         watermark
 983
 984                 Description
 985
 986                         Add a watermark to the frames.
 987
 988                 Constructor Argument
 989
 990                         resource - the producer to use (ie: a .png)
 991
 992                 Initialisation Properties
 993
 994                         string resource - the producer to use
 995                         string factory - producer required for the resource ('fezzik')
 996                         string geometry - composite geometry
 997                         string distort - control scaling
 998                         int in - in point
 999                         int out - out point
1000
1001                 Mutable Properties
1002
1003                         none
1004
1005                 Dependencies
1006
1007                         mlt core modules and optionally, fezzik
1008
1009                 Known Bugs
1010
1011                         none
1012
1013 Transitions
1014 -----------
1015
1016         composite
1017
1018                 Description
1019
1020                         A key-framable alpha-channel compositor for two frames.
1021
1022                 Details
1023
1024                         Performs dissolves and luma wipes in addition to alpha compositing.
1025
1026                         By default, the aspect ratio of the B frame is respected and the
1027                         size portion of the geometry specification simply defines a
1028                         bounding rectangle.
1029
1030                         This performs field-based rendering unless the A frame property
1031                         "progressive" or "consumer_progressive" or the transition property
1032                         "progressive" is set to 1.
1033
1034                 Constructor Argument
1035
1036                         string start - a geometry specification as X,Y:WxH[!][:mix]
1037                                      - X, Y, W, H are assumed to pixel units unless they
1038                                        have the suffix '%'
1039                                      - '!' is a shortcut to specify distort, see below.
1040                                      - mix is always a 2 digit percentage, defaults to 100.
1041                                                  - default is "85%,5%:10%x10%"
1042
1043                 Initialisation Properties
1044
1045                         string end - the ending size and position.
1046                         string key[F] - X,Y:WxH[:mix] - set a key frame for geometry between
1047                                         the in and out. F is a frame number and can be
1048                                         negative to make it relative to the out point.
1049                         int in - in point
1050                         int out - out point
1051                         string factory - The name of a factory service used as a non-PGM
1052                                          producer loader. The default is fezzik.
1053
1054                 Read Only Properties
1055
1056                         none
1057
1058                 Mutable Properties
1059
1060                         int progressive - set to 1 to disable field-based rendering.
1061                         string distort - when set, causes the B frame image to fill the WxH
1062                                          completely with no regard to B's aspect ratio.
1063                         string halign - when not distorting, set the horizontal alignment
1064                                         of B within the geometry rectangle.
1065                                       - one of: left (0), centre (1), or right (2).
1066                                       - the default is left.
1067                         string valign - when not distorting, set the vertical alignment of
1068                                         B within the geometry rectangle.
1069                                       - one of: top (0), middle (1), or bottom (2).
1070                                       - the default is top.
1071                         string luma - the luma map file name. If not supplied, a dissolve.
1072                         double softness - only when using a luma map, how soft to make the
1073                                           edges between A and B. 0.0 = no softness. 1.0 =
1074                                           too soft.
1075                         Any property starting with "luma." is passed to the non-PGM luma
1076                             producer.
1077
1078                 Dependencies
1079
1080                         none
1081
1082                 Known Bugs
1083
1084                         Assumes lower field first during field rendering.
1085
1086         luma
1087
1088                 Description
1089
1090                         A generic dissolve and wipe transition processor.
1091
1092                 Details
1093
1094                         luma gets its name
1095                         from how it uses a grayscale "map" file. As the luma value varies
1096                         over time, a threshold filter is applied to the map to determine
1097                         what parts of frame A vs. frame B to show. It reads PGM files
1098                         up to 16 bits! Alternatively, it can use the first frame from any
1099                         producer that outputs yuv, but it will be limited to the luma
1100                         gamut of 220 values.
1101                         This performs field-based rendering unless the A frame property
1102                         "progressive" or "consumer_progressive" or the transition property
1103                         "progressive" is set to 1.
1104
1105                 Constructor Argument
1106
1107                         string resource - the luma map file name - either PGM or any other
1108                                           producable video.
1109                                         - If not supplied, a dissolve.
1110
1111                 Initialisation Properties
1112
1113                         int in - in point
1114                         int out - out point
1115                         string factory - The name of a factory service used as a non-PGM
1116                                          producer loader. The default is Fezzik.
1117
1118                 Mutable Properties
1119
1120                         string resource - same as above
1121                         double softness - only when using a luma map, how soft to make the
1122                                           edges between A and B. 0.0 = no softness. 1.0 =
1123                                           too soft.
1124                         Any property starting with "producer." is passed to the non-PGM luma
1125                             producer.
1126
1127                 Read Only Properties
1128
1129                         none
1130
1131                 Dependencies
1132
1133                         none
1134
1135                 Known Bugs
1136
1137                         Assumes lower field first output.
1138
1139         mix
1140
1141                 Description
1142
1143                         An two stream audio mixer.
1144
1145                 Constructor Argument
1146
1147                         start - see below
1148
1149                 Initalisation Properties
1150
1151                         int in - in point
1152                         int out - out point
1153
1154                 Mutable Properties
1155
1156                         double start - the mix level to apply to the second frame.
1157                                      - any negative value causes an automatic crossfade from 0 to 1.
1158                         double end - the ending value of the mix level. mix level will be interpolated
1159                                      from start to end over the in-out range.
1160                         int reverse - set to 1 to reverse the direction of the mix.
1161
1162                 Read Only Properties
1163
1164                         none
1165
1166                 Dependencies
1167
1168                         none
1169
1170                 Known Bugs
1171
1172                         Samples from the longer of the two frames are discarded.
1173
1174
1175         region
1176
1177                 Description
1178
1179                         Apply zero or more filters to B frame as it is composited onto
1180                         a region of the A frame. The "shape" of the region can be defined
1181                         by the alpha channel of a third producer.
1182
1183                 Constructor Argument
1184
1185                         resource - a shape producer
1186
1187                 Initialisation Properties
1188
1189                         string resource - nothing is rectangle, "circle" is a pixbuf-
1190                             generated SVG circle, anything else is loaded by the factory.
1191                         string factory - the service that creates the shape producer.
1192                                        - the default is fezzik.
1193                         string filter[N] - one or more filters to apply. All filter
1194                                            properties are passed using the same filter "key"
1195                         Any property starting with "composite." is passed to the
1196                             encapsulated composite transition.
1197
1198                 Read Only Properties
1199
1200                         none
1201
1202                 Dependencies
1203
1204                         transition_composite
1205
1206                 Known Bugs
1207
1208                         none
1209
1210
1211 Consumers
1212 ---------
1213
1214         bluefish (Proprietary)
1215
1216                 Description
1217
1218                         BlueFish444 audio and video output module.
1219
1220                 Constructor Argument
1221
1222                         string video_standard - "PAL" (default) or "NTSC"
1223
1224                 Initialisation Properties
1225
1226                         int video_standard - 0 = PAL, 1 = NTSC
1227
1228                 Read Only Properties
1229
1230                         none
1231
1232                 Dependencies
1233
1234                         BlueVelvet SDK installed parallel to mlt in "bluefish."
1235
1236                 Known Bugs
1237
1238                         Does not work with any service that uses pipes!
1239
1240                         If mlt crashes, you must reload the BlueDriver kernel module
1241                         due to unreleased DMA buffers.
1242
1243                         Needs an argument or property for multi-card address.
1244
1245         libdv
1246
1247                 Description
1248
1249                         libdv dv producer.
1250
1251                 Constructor Argument
1252
1253                         string target - the filename to write to, e.g. /dev/dv1394.
1254
1255                 Initialisation Properties
1256
1257                         int buffer - the number of frames to buffer, minimum 1, default 25.
1258                         string rescale - a rescale method, see the Filters/rescale.
1259
1260                 Mutable Properties
1261
1262                         int progressive - indicates whether to use progressive or field-
1263                                           based rendering, default 0 (off).
1264
1265                 Read Only Properties
1266
1267                         none
1268
1269                 Dependencies
1270
1271                         libdv
1272
1273                 Known Bugs
1274
1275                         none
1276
1277         sdl
1278
1279                 Description
1280
1281                         Simple DirectMedia Layer audio and video output module.
1282
1283                 Constructor Argument
1284
1285                         string video_standard - "PAL" (default), "NTSC", or "WxH"
1286
1287                 Initialisation Properties
1288
1289                         int buffer - the number of frames to buffer, minimum 1, default 25.
1290                         string rescale - a rescale method, see the Filters/rescale.
1291                                        - Hint: "none" works very good with SDL output.
1292
1293                 Mutable Properties
1294
1295                         double volume - audio level factor
1296                         int video_off - if 1, disable video output
1297                         int audio_off - if 1, disable audio output
1298                         int scale_overlay - if 1, resample video from source pixel aspect
1299                                             ratio to square pixels.
1300                         int progressive - indicates whether to use progressive or field-
1301                                           based rendering, default 0 (off).
1302
1303                 Read Only Properties
1304
1305                         none
1306
1307                 Dependencies
1308
1309                         libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
1310
1311                 Known Bugs
1312
1313                         none
1314
1315         westley
1316
1317                 Description
1318
1319                         Serialise the service network to XML.
1320                         See docs/westley.txt for more information.
1321
1322                 Constructor Argument
1323
1324                         resource - the name of a file in which to store the XML.
1325                                   - stdout is default.
1326
1327                 Initialisation Properties
1328
1329                         string resource - same as above.
1330
1331                 Dependencies
1332
1333                         libxml2
1334
1335                 Known Bugs
1336
1337                         Untested arbitrary nesting of multitracks and playlists.
1338                         Property "id" is generated as service type followed by number if
1339                         no property named "id" exists, but it fails to guarantee uniqueness.