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

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