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