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         obscure
 719
 720                 Description
 721
 722                         Obscuring filter.
 723
 724                 Constructor Argument
 725
 726                         none
 727
 728                 Initialisation Properties
 729
 730                         string start - in the format X,Y:WxH[:PWxPY]
 731                                      - PWxPY is the size of the averaging region in pixels.
 732                         string end - in the format X,Y:WxH[:PWxPY]
 733                         int in - in point
 734                         int out - out point
 735
 736                 Read Only Properties
 737
 738                         none
 739
 740                 Dependencies
 741
 742                         none
 743
 744                 Known Bugs
 745
 746                         none
 747
 748         region
 749
 750                 Description
 751
 752                         Apply one or filters to a region of the video image. The region
 753                         can be shaped as well using the alpha channel of another producer.
 754
 755                 Constructor Argument
 756
 757                         file - A file whose alpha channel will "shape"  the region.
 758                              - The string "circle" is a shortcut but it requires pixbuf with
 759                                the librsvg loader. The circle is automatically stretched
 760                                to the region to create an ellipse.
 761
 762                 Initialisation Properties
 763
 764                         int in - in point
 765                         int out - out point
 766                         plus and region transition properties
 767
 768                 Read Only Properties
 769
 770                         see the region transition
 771
 772                 Dependencies
 773
 774                         transition_region
 775
 776                 Known Bugs
 777
 778                         "circle" is unpredictable in the absence of the librsvg pixbuf loader.
 779
 780
 781         resample
 782
 783                 Description
 784
 785                         Adjust an audio stream's sampling rate, and duplicate channels if
 786                         producer provides less than consumer requested.
 787
 788                         This filter is automatically invoked by Fezzik for the sake of
 789                         normalisation over inputs and with the consumer.
 790
 791                 Constructor Argument
 792
 793                         frequency - a numeric value for the new sample rate
 794
 795                 Initialisation Properties
 796
 797                         int in - in point
 798                         int out - out point
 799
 800                 Mutable Properties
 801
 802                         int frequency - the target sample rate
 803
 804                 Dependencies
 805
 806                         libresample
 807
 808                 Known Bugs
 809
 810                         Assumes 2 channels during libsamplerate initialisation. Untested
 811                         with >2 channels.
 812
 813         rescale
 814
 815                 Description
 816
 817                         Scale the producer video frame size to match the consumer.
 818                         This filter is automatically invoked by Fezzik in order to normalise
 819                         sample aspect ratio.
 820
 821                 Constructor Argument
 822
 823                         interpolation - the rescaling method, one of:
 824                                 nearest (lowest quality, fastest),
 825                                 tiles,
 826                                 bilinear (default; good quality, moderate speed),
 827                                 hyper (best quality, slowest).
 828
 829                 Initialisation Properties
 830
 831                         int in - in point
 832                         int out - out point
 833
 834                 Mutable Properties
 835
 836                         string interpolation - see constructor argument above
 837
 838                         If a property "consumer_aspect_ratio" exists on the frame, then
 839                         rescaler normalises the producer's aspect ratio and maximises the
 840                         size of the frame, but may not produce the consumer's requested
 841                         dimension. Therefore, this option works best in conjunction with the
 842                         resize filter. This behavior can be disabled by another service by
 843                         either removing the property, setting it to zero, or setting
 844                         frame property "distort" to 1.
 845
 846                 Dependencies
 847
 848                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
 849
 850                 Known Bugs
 851
 852                         none
 853
 854         resize
 855
 856                 Description
 857
 858                         Image scaling and padding and field order adjustment.
 859
 860                 Details
 861
 862                         Normally resize is used to pad the producer's
 863                         output to what the consumer has requested after an upstream rescale
 864                         filter first scales the image to maximise usage of the image area.
 865                         This filter also adjusts the field order to lower field first
 866                         if the frame property "top_field_first" has been set to 1.
 867                         Therefore, when done, it sets the top_field_first to 0.
 868                         This filter is automatically invoked by Fezzik as part of image
 869                         sample aspect ratio normalisation.
 870
 871                 Constructor Argument
 872
 873                         scale - "affine" to use affine transform scaling, otherwise
 874                                  center and pad.
 875
 876                 Initialisation Properties
 877
 878                         int in - in point
 879                         int out - out point
 880
 881                 Read Only Properties
 882
 883                         none
 884
 885                 Dependencies
 886
 887                         none
 888
 889                 Known Bugs
 890
 891                         Assumes lower field first output.
 892
 893         volume
 894
 895                 Description
 896
 897                         Adjust an audio stream's volume level
 898
 899                 Constructor Argument
 900
 901                         gain - a string containing one of:
 902                                  - a floating point value of the gain adjustment
 903                                  - a numeric value with the suffix "dB" to adjust in terms of decibels
 904                                  - "normalise" to normalise the volume to the target amplitude -12dBFS
 905
 906                 Initialisation Properties
 907
 908                         int in - in point
 909                         int out - out point
 910                         int window - the number of video frames over which to smooth normalisation.
 911                                      defaults to 75.
 912
 913                 Mutable Properties
 914
 915                         string gain - same as constructor argument above
 916
 917                         string normalise - normalise the volume to the amplitude:
 918                                 - a numeric value with the suffix "dB" to set amplitude in decibels
 919                                 - a floating point value of the relative volume
 920                                 - an unspecified value uses the default -12dBFS
 921
 922                         string limiter - limit all samples above:
 923                                 - a numeric value with the suffix "dB"
 924                                 - a floating point value ( dB = 20 * log10(x) )
 925                                 - an unspecified value uses the default -6dBFS
 926
 927                         double max_gain - a floating point or decibel value of the maximum gain that
 928                                 can be applied during normalisation.
 929                                 - an unspecified value uses the default 20dB
 930
 931                         string end - a gain value just like the gain property above.
 932                                      This causes the gain to be interpolated from 'gain' to 'end'
 933                                      over the duration.
 934
 935                         int window - the size of the normalising smoothing buffer in video frame units.
 936                                    - the smoothing buffer prevents erratic gain changes.
 937                                    - the default value is 75 video frames.
 938
 939                         gain can be applied as a factor to the normalise amplitude!
 940
 941                 Dependencies
 942
 943                         none
 944
 945                 Known Bugs
 946
 947                         none
 948
 949         watermark
 950
 951                 Description
 952
 953                         Add a watermark to the frames.
 954
 955                 Constructor Argument
 956
 957                         resource - the producer to use (ie: a .png)
 958
 959                 Initialisation Properties
 960
 961                         string resource - the producer to use
 962                         string factory - producer required for the resource ('fezzik')
 963                         string geometry - composite geometry
 964                         string distort - control scaling
 965                         int in - in point
 966                         int out - out point
 967
 968                 Mutable Properties
 969
 970                         none
 971
 972                 Dependencies
 973
 974                         mlt core modules and optionally, fezzik
 975
 976                 Known Bugs
 977
 978                         none
 979
 980 Transitions
 981 -----------
 982
 983         composite
 984
 985                 Description
 986
 987                         A key-framable alpha-channel compositor for two frames.
 988
 989                 Details
 990
 991                         Performs dissolves and luma wipes in addition to alpha compositing.
 992
 993                         By default, the aspect ratio of the B frame is respected and the
 994                         size portion of the geometry specification simply defines a
 995                         bounding rectangle.
 996
 997                         This performs field-based rendering unless the A frame property
 998                         "progressive" or "consumer_progressive" or the transition property
 999                         "progressive" is set to 1.
1000
1001                 Constructor Argument
1002
1003                         string start - a geometry specification as X,Y:WxH[!][:mix]
1004                                      - X, Y, W, H are assumed to pixel units unless they
1005                                        have the suffix '%'
1006                                      - '!' is a shortcut to specify distort, see below.
1007                                      - mix is always a 2 digit percentage, defaults to 100.
1008                                                  - default is "85%,5%:10%x10%"
1009
1010                 Initialisation Properties
1011
1012                         string end - the ending size and position.
1013                         string key[F] - X,Y:WxH[:mix] - set a key frame for geometry between
1014                                         the in and out. F is a frame number and can be
1015                                         negative to make it relative to the out point.
1016                         int in - in point
1017                         int out - out point
1018                         string factory - The name of a factory service used as a non-PGM
1019                                          producer loader. The default is fezzik.
1020
1021                 Read Only Properties
1022
1023                         none
1024
1025                 Mutable Properties
1026
1027                         int progressive - set to 1 to disable field-based rendering.
1028                         string distort - when set, causes the B frame image to fill the WxH
1029                                          completely with no regard to B's aspect ratio.
1030                         string halign - when not distorting, set the horizontal alignment
1031                                         of B within the geometry rectangle.
1032                                       - one of: left (0), centre (1), or right (2).
1033                                       - the default is left.
1034                         string valign - when not distorting, set the vertical alignment of
1035                                         B within the geometry rectangle.
1036                                       - one of: top (0), middle (1), or bottom (2).
1037                                       - the default is top.
1038                         string luma - the luma map file name. If not supplied, a dissolve.
1039                         double softness - only when using a luma map, how soft to make the
1040                                           edges between A and B. 0.0 = no softness. 1.0 =
1041                                           too soft.
1042                         Any property starting with "luma." is passed to the non-PGM luma
1043                             producer.
1044
1045                 Dependencies
1046
1047                         none
1048
1049                 Known Bugs
1050
1051                         Assumes lower field first during field rendering.
1052
1053         luma
1054
1055                 Description
1056
1057                         A generic dissolve and wipe transition processor.
1058
1059                 Details
1060
1061                         luma gets its name
1062                         from how it uses a grayscale "map" file. As the luma value varies
1063                         over time, a threshold filter is applied to the map to determine
1064                         what parts of frame A vs. frame B to show. It reads PGM files
1065                         up to 16 bits! Alternatively, it can use the first frame from any
1066                         producer that outputs yuv, but it will be limited to the luma
1067                         gamut of 220 values.
1068                         This performs field-based rendering unless the A frame property
1069                         "progressive" or "consumer_progressive" or the transition property
1070                         "progressive" is set to 1.
1071
1072                 Constructor Argument
1073
1074                         string resource - the luma map file name - either PGM or any other
1075                                           producable video.
1076                                         - If not supplied, a dissolve.
1077
1078                 Initialisation Properties
1079
1080                         int in - in point
1081                         int out - out point
1082                         string factory - The name of a factory service used as a non-PGM
1083                                          producer loader. The default is Fezzik.
1084
1085                 Mutable Properties
1086
1087                         string resource - same as above
1088                         double softness - only when using a luma map, how soft to make the
1089                                           edges between A and B. 0.0 = no softness. 1.0 =
1090                                           too soft.
1091                         Any property starting with "producer." is passed to the non-PGM luma
1092                             producer.
1093
1094                 Read Only Properties
1095
1096                         none
1097
1098                 Dependencies
1099
1100                         none
1101
1102                 Known Bugs
1103
1104                         Assumes lower field first output.
1105
1106         mix
1107
1108                 Description
1109
1110                         An two stream audio mixer.
1111
1112                 Constructor Argument
1113
1114                         start - see below
1115
1116                 Initalisation Properties
1117
1118                         int in - in point
1119                         int out - out point
1120
1121                 Mutable Properties
1122
1123                         double start - the mix level to apply to the second frame.
1124                                      - any negative value causes an automatic crossfade from 0 to 1.
1125                         double end - the ending value of the mix level. mix level will be interpolated
1126                                      from start to end over the in-out range.
1127                         int reverse - set to 1 to reverse the direction of the mix.
1128
1129                 Read Only Properties
1130
1131                         none
1132
1133                 Dependencies
1134
1135                         none
1136
1137                 Known Bugs
1138
1139                         Samples from the longer of the two frames are discarded.
1140
1141
1142         region
1143
1144                 Description
1145
1146                         Apply zero or more filters to B frame as it is composited onto
1147                         a region of the A frame. The "shape" of the region can be defined
1148                         by the alpha channel of a third producer.
1149
1150                 Constructor Argument
1151
1152                         resource - a shape producer
1153
1154                 Initialisation Properties
1155
1156                         string resource - nothing is rectangle, "circle" is a pixbuf-
1157                             generated SVG circle, anything else is loaded by the factory.
1158                         string factory - the service that creates the shape producer.
1159                                        - the default is fezzik.
1160                         string filter[N] - one or more filters to apply. All filter
1161                                            properties are passed using the same filter "key"
1162                         Any property starting with "composite." is passed to the
1163                             encapsulated composite transition.
1164
1165                 Read Only Properties
1166
1167                         none
1168
1169                 Dependencies
1170
1171                         transition_composite
1172
1173                 Known Bugs
1174
1175                         none
1176
1177
1178 Consumers
1179 ---------
1180
1181         bluefish (Proprietary)
1182
1183                 Description
1184
1185                         BlueFish444 audio and video output module.
1186
1187                 Constructor Argument
1188
1189                         string video_standard - "PAL" (default) or "NTSC"
1190
1191                 Initialisation Properties
1192
1193                         int video_standard - 0 = PAL, 1 = NTSC
1194
1195                 Read Only Properties
1196
1197                         none
1198
1199                 Dependencies
1200
1201                         BlueVelvet SDK installed parallel to mlt in "bluefish."
1202
1203                 Known Bugs
1204
1205                         Does not work with any service that uses pipes!
1206
1207                         If mlt crashes, you must reload the BlueDriver kernel module
1208                         due to unreleased DMA buffers.
1209
1210                         Needs an argument or property for multi-card address.
1211
1212         libdv
1213
1214                 Description
1215
1216                         libdv dv producer.
1217
1218                 Constructor Argument
1219
1220                         string target - the filename to write to, e.g. /dev/dv1394.
1221
1222                 Initialisation Properties
1223
1224                         int buffer - the number of frames to buffer, minimum 1, default 25.
1225                         string rescale - a rescale method, see the Filters/rescale.
1226
1227                 Mutable Properties
1228
1229                         int progressive - indicates whether to use progressive or field-
1230                                           based rendering, default 0 (off).
1231
1232                 Read Only Properties
1233
1234                         none
1235
1236                 Dependencies
1237
1238                         libdv
1239
1240                 Known Bugs
1241
1242                         none
1243
1244         sdl
1245
1246                 Description
1247
1248                         Simple DirectMedia Layer audio and video output module.
1249
1250                 Constructor Argument
1251
1252                         string video_standard - "PAL" (default), "NTSC", or "WxH"
1253
1254                 Initialisation Properties
1255
1256                         int buffer - the number of frames to buffer, minimum 1, default 25.
1257                         string rescale - a rescale method, see the Filters/rescale.
1258                                        - Hint: "none" works very good with SDL output.
1259
1260                 Mutable Properties
1261
1262                         double volume - audio level factor
1263                         int video_off - if 1, disable video output
1264                         int audio_off - if 1, disable audio output
1265                         int scale_overlay - if 1, resample video from source pixel aspect
1266                                             ratio to square pixels.
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                         libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
1277
1278                 Known Bugs
1279
1280                         none
1281
1282         westley
1283
1284                 Description
1285
1286                         Serialise the service network to XML.
1287                         See docs/westley.txt for more information.
1288
1289                 Constructor Argument
1290
1291                         resource - the name of a file in which to store the XML.
1292                                   - stdout is default.
1293
1294                 Initialisation Properties
1295
1296                         string resource - same as above.
1297
1298                 Dependencies
1299
1300                         libxml2
1301
1302                 Known Bugs
1303
1304                         Untested arbitrary nesting of multitracks and playlists.
1305                         Property "id" is generated as service type followed by number if
1306                         no property named "id" exists, but it fails to guarantee uniqueness.