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

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