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-11-07
   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         jackrack
 692
 693             Description
 694
 695                 Creates Jack ports and runs a JackRack project to process audio
 696                         through a stack of LADSPA filters.
 697
 698             Constructor Argument
 699
 700                 src - a JackRack file
 701
 702                 Details
 703
 704                         If you are using a consumer that uses ALSA, then you should start
 705                         jacks with the dummy driver: jackd -d dummy.
 706                         I also recommend using a period size of 2048: -p 2048.
 707
 708                         jackd -ddummy -r48000 -p2048
 709
 710             Initialisation Properties
 711
 712                 int in - in point
 713                 int out - out point
 714
 715                         The following can be used without a rack file in order to connect
 716                         filter_jackrack to a running instance of JackRack:
 717                         string out_1 - Jack port to connect MLT's output port (JackRack's input)
 718                         string out_2 - Jack port to connect MLT's output port (JackRack's input)
 719                         string in_1 - Jack port to connect MLT's input port (JackRack's output)
 720                         string in_2 - Jack port to connect MLT's input port (JackRack's output)
 721
 722             Read Only Properties
 723
 724                 none
 725
 726             Mutable Properties
 727
 728                         none
 729
 730             Dependencies
 731
 732                 Jack, LADSPA, glib-2.0, libxml2
 733
 734             Known Bugs
 735
 736                 no encapsulated resampling and jack runs at a fixed frequency
 737
 738         luma
 739
 740             Description
 741
 742                 Applies a luma transition between the current and next frames.
 743                 Useful for transitions from a slideshow created using producer
 744                 pixbuf.
 745
 746             Constructor Argument
 747
 748                 file - a luma wipe
 749
 750             Initialisation Properties
 751
 752                 int in - in point
 753                 int out - out point
 754
 755             Read Only Properties
 756
 757                 none
 758
 759             Mutable Properties
 760
 761                 int period - how long to wait between success iterations of the
 762                              transition. For best results set this to a multiple
 763                              of ttl used in pixbuf. The default is 24.
 764
 765                 luma. - all properties beginning with "luma." are passed to the
 766                         encapsulated luma transition. For example, luma.out controls
 767                         the duration of the wipe.
 768
 769             Dependencies
 770
 771                 transition_luma and its dependencies
 772
 773             Known Bugs
 774
 775                 none
 776
 777         mcrescale
 778
 779             Description
 780
 781                 Scale the producer video frame size to match the consumer.
 782                 This filter is designed for use as a Fezzik normaliser.
 783
 784             Constructor Argument
 785
 786                 interpolation - the rescaling method, one of:
 787                     nearest (lowest quality, fastest),
 788                     bilinear (default; good quality, moderate speed),
 789                     hyper (best quality, slowest).
 790
 791             Initialisation Properties
 792
 793                 int in - in point
 794                 int out - out point
 795
 796             Mutable Properties
 797
 798                 string interpolation - see constructor argument above
 799
 800                 If a property "consumer_aspect_ratio" exists on the frame, then
 801                 rescaler normalises the producer's aspect ratio and maximises the
 802                 size of the frame, but may not produce the consumer's requested
 803                 dimension. Therefore, this option works best in conjunction with the
 804                 resize filter. This behavior can be disabled by another service by
 805                 either removing the property, setting it to zero, or setting
 806                 frame property "distort" to 1.
 807
 808             Dependencies
 809
 810                 the mainconcept rescaling sdk.
 811
 812             Known Bugs
 813
 814                 none
 815
 816         mirror
 817
 818             Description
 819
 820                 Provides various mirror and image reversing effects.
 821
 822             Constructor Argument
 823
 824                 mirror - horizontal, vertical, diagonal, flip, flop
 825
 826             Initialisation Properties
 827
 828                 int reverse - being 0 or 1
 829                 int in - in point
 830                 int out - out point
 831
 832             Read Only Properties
 833
 834                 none
 835
 836             Mutable Properties
 837
 838                 none
 839
 840             Dependencies
 841
 842                 none
 843
 844             Known Bugs
 845
 846                 none
 847
 848
 849         obscure
 850
 851             Description
 852
 853                 Obscuring filter.
 854
 855             Constructor Argument
 856
 857                 none
 858
 859             Initialisation Properties
 860
 861                 string start - in the format X,Y:WxH[:PWxPY]
 862                              - PWxPY is the size of the averaging region in pixels.
 863                 string end - in the format X,Y:WxH[:PWxPY]
 864                 int in - in point
 865                 int out - out point
 866
 867             Read Only Properties
 868
 869                 none
 870
 871             Dependencies
 872
 873                 none
 874
 875             Known Bugs
 876
 877                 none
 878
 879         region
 880
 881             Description
 882
 883                 Apply one or more filters to a region of the video image. The region
 884                 can be shaped as well using the alpha channel of another producer.
 885
 886             Constructor Argument
 887
 888                 resource - A file whose alpha channel will "shape"  the region.
 889                      - The string "circle" is a shortcut but it requires pixbuf with
 890                        the librsvg loader. The circle is automatically stretched
 891                        to the region to create an ellipse.
 892
 893             Initialisation Properties
 894
 895                 int in - in point
 896                 int out - out point
 897                 plus and region transition properties
 898
 899             Read Only Properties
 900
 901                 see the region transition
 902
 903             Dependencies
 904
 905                 transition_region
 906
 907             Known Bugs
 908
 909                 "circle" is unpredictable in the absence of the librsvg pixbuf loader.
 910
 911
 912         resample
 913
 914             Description
 915
 916                 Adjust an audio stream's sampling rate, and duplicate channels if
 917                 producer provides less than consumer requested.
 918
 919                 This filter is automatically invoked by Fezzik for the sake of
 920                 normalisation over inputs and with the consumer.
 921
 922             Constructor Argument
 923
 924                 frequency - a numeric value for the new sample rate
 925
 926             Initialisation Properties
 927
 928                 int in - in point
 929                 int out - out point
 930
 931             Mutable Properties
 932
 933                 int frequency - the target sample rate
 934
 935             Dependencies
 936
 937                 libresample
 938
 939             Known Bugs
 940
 941                 Assumes 2 channels during libsamplerate initialisation. Untested
 942                 with >2 channels.
 943
 944         rescale
 945
 946             Description
 947
 948                 Scale the producer video frame size to match the consumer.
 949                 This filter is designed for use as a Fezzik normaliser.
 950
 951             Constructor Argument
 952
 953                 None.
 954
 955             Initialisation Properties
 956
 957                 int in - in point
 958                 int out - out point
 959
 960             Mutable Properties
 961
 962                 If a property "consumer_aspect_ratio" exists on the frame, then
 963                 rescaler normalises the producer's aspect ratio and maximises the
 964                 size of the frame, but may not produce the consumer's requested
 965                 dimension. Therefore, this option works best in conjunction with the
 966                 resize filter. This behavior can be disabled by another service by
 967                 either removing the property, setting it to zero, or setting
 968                 frame property "distort" to 1.
 969
 970             Dependencies
 971
 972                 none
 973
 974             Known Bugs
 975
 976                 none but... it only implements a nearest neighbour scaling - it is
 977                         used as the base class for the gtkrescale and mcrescale filters.
 978
 979         resize
 980
 981             Description
 982
 983                 Image scaling and padding and field order adjustment.
 984
 985             Details
 986
 987                 Normally resize is used to pad the producer's
 988                 output to what the consumer has requested after an upstream rescale
 989                 filter first scales the image to maximise usage of the image area.
 990                 This filter also adjusts the field order to lower field first
 991                 if the frame property "top_field_first" has been set to 1.
 992                 Therefore, when done, it sets the top_field_first to 0.
 993                 This filter is automatically invoked by Fezzik as part of image
 994                 sample aspect ratio normalisation.
 995
 996             Constructor Argument
 997
 998                 scale - "affine" to use affine transform scaling, otherwise
 999                          center and pad.
1000
1001             Initialisation Properties
1002
1003                 int in - in point
1004                 int out - out point
1005
1006             Read Only Properties
1007
1008                 none
1009
1010             Dependencies
1011
1012                 none
1013
1014             Known Bugs
1015
1016                 Assumes lower field first output.
1017
1018         volume
1019
1020             Description
1021
1022                 Adjust an audio stream's volume level
1023                                 - based on the 'normalize' utility
1024
1025             Constructor Argument
1026
1027                 gain - a string containing one of:
1028                      - a floating point value of the gain adjustment
1029                      - a numeric value with the suffix "dB" to adjust in terms of decibels
1030                      - "normalise" to normalise the volume to the target amplitude -12dBFS
1031
1032             Initialisation Properties
1033
1034                 int in - in point
1035                 int out - out point
1036                 int window - the number of video frames over which to smooth normalisation.
1037                              defaults to 75.
1038
1039             Mutable Properties
1040
1041                 string gain - same as constructor argument above
1042
1043                 string normalise - normalise the volume to the amplitude:
1044                     - a numeric value with the suffix "dB" to set amplitude in decibels
1045                     - a floating point value of the relative volume
1046                     - an unspecified value uses the default -12dBFS
1047
1048                 string limiter - limit all samples above:
1049                     - a numeric value with the suffix "dB"
1050                     - a floating point value ( dB = 20 * log10(x) )
1051                     - an unspecified value uses the default -6dBFS
1052
1053                 double max_gain - a floating point or decibel value of the maximum gain that
1054                     can be applied during normalisation.
1055                     - an unspecified value uses the default 20dB
1056
1057                 string end - a gain value just like the gain property above.
1058                              This causes the gain to be interpolated from 'gain' to 'end'
1059                              over the duration.
1060
1061                 int window - the size of the normalising smoothing buffer in video frame units.
1062                            - the smoothing buffer prevents erratic gain changes.
1063                            - the default value is 75 video frames.
1064
1065                 gain can be applied as a factor to the normalise amplitude!
1066
1067             Dependencies
1068
1069                 none
1070
1071             Known Bugs
1072
1073                 none
1074
1075         watermark
1076
1077             Description
1078
1079                 Add a watermark to the frames.
1080
1081             Constructor Argument
1082
1083                 resource - the producer to use (ie: a .png)
1084
1085             Initialisation Properties
1086
1087                 string resource - the producer to use
1088                 string factory - producer required for the resource ('fezzik')
1089                 string geometry - composite geometry
1090                 string distort - control scaling
1091                 int in - in point
1092                 int out - out point
1093
1094             Mutable Properties
1095
1096                 none
1097
1098             Dependencies
1099
1100                 mlt core modules and optionally, fezzik
1101
1102             Known Bugs
1103
1104                 none
1105
1106 Transitions
1107 -----------
1108
1109         composite
1110
1111             Description
1112
1113                 A key-framable alpha-channel compositor for two frames.
1114
1115             Details
1116
1117                 Performs dissolves and luma wipes in addition to alpha compositing.
1118
1119                 By default, the aspect ratio of the B frame is respected and the
1120                 size portion of the geometry specification simply defines a
1121                 bounding rectangle.
1122
1123                 This performs field-based rendering unless the A frame property
1124                 "progressive" or "consumer_progressive" or the transition property
1125                 "progressive" is set to 1.
1126
1127             Constructor Argument
1128
1129                         none[*]
1130
1131             Initialisation Properties
1132
1133                 int in - in point
1134                 int out - out point
1135                 string factory - The name of a factory service used as a non-PGM
1136                                  producer loader. The default is fezzik.
1137
1138             Read Only Properties
1139
1140                 none
1141
1142             Mutable Properties
1143
1144
1145                         string geometry - key frame specification
1146                                                         - this is a ; delimited form of the deprecated start,
1147                                                           key[n], end properties
1148                 int progressive - set to 1 to disable field-based rendering.
1149                 string distort - when set, causes the B frame image to fill the WxH
1150                                  completely with no regard to B's aspect ratio.
1151                 string halign - when not distorting, set the horizontal alignment
1152                                 of B within the geometry rectangle.
1153                               - one of: left (0), centre (1), or right (2).
1154                               - the default is left.
1155                 string valign - when not distorting, set the vertical alignment of
1156                                 B within the geometry rectangle.
1157                               - one of: top (0), middle (1), or bottom (2).
1158                               - the default is top.
1159                 string luma - the luma map file name. If not supplied, a dissolve.
1160                 double softness - only when using a luma map, how soft to make the
1161                                   edges between A and B. 0.0 = no softness. 1.0 =
1162                                   too soft.
1163                 Any property starting with "luma." is passed to the non-PGM luma
1164                     producer.
1165
1166                 Deprecated Properties
1167
1168                 string start - a geometry specification as X,Y:WxH[!][:mix]
1169                              - X, Y, W, H are assumed to pixel units unless they
1170                                have the suffix '%'
1171                              - '!' is a shortcut to specify distort, see below.
1172                              - mix is always a 2 digit percentage, defaults to 100.
1173                              - default is "85%,5%:10%x10%"
1174                 string end - the ending size and position.
1175                 string key[F] - X,Y:WxH[:mix] - set a key frame for geometry between
1176                                 the in and out. F is a frame number and can be
1177                                 negative to make it relative to the out point.
1178
1179             Dependencies
1180
1181                 none
1182
1183             Known Bugs
1184
1185                 Assumes lower field first during field rendering.
1186
1187         luma
1188
1189             Description
1190
1191                 A generic dissolve and wipe transition processor.
1192
1193             Details
1194
1195                 luma gets its name
1196                 from how it uses a grayscale "map" file. As the luma value varies
1197                 over time, a threshold filter is applied to the map to determine
1198                 what parts of frame A vs. frame B to show. It reads PGM files
1199                 up to 16 bits! Alternatively, it can use the first frame from any
1200                 producer that outputs yuv, but it will be limited to the luma
1201                 gamut of 220 values.
1202                 This performs field-based rendering unless the A frame property
1203                 "progressive" or "consumer_progressive" or the transition property
1204                 "progressive" is set to 1.
1205
1206             Constructor Argument
1207
1208                 string resource - the luma map file name - either PGM or any other
1209                                   producable video.
1210                                 - If not supplied, a dissolve.
1211
1212             Initialisation Properties
1213
1214                 int in - in point
1215                 int out - out point
1216                 string factory - The name of a factory service used as a non-PGM
1217                                  producer loader. The default is Fezzik.
1218
1219             Mutable Properties
1220
1221                 string resource - same as above
1222                 double softness - only when using a luma map, how soft to make the
1223                                   edges between A and B. 0.0 = no softness. 1.0 =
1224                                   too soft.
1225                 int reverse - reverse the direction of the transition.
1226                 Any property starting with "producer." is passed to the non-PGM luma
1227                     producer.
1228
1229             Read Only Properties
1230
1231                 none
1232
1233             Dependencies
1234
1235                 none
1236
1237             Known Bugs
1238
1239                 Assumes lower field first output.
1240
1241         mix
1242
1243             Description
1244
1245                 An two stream audio mixer.
1246
1247             Constructor Argument
1248
1249                 start - see below
1250
1251             Initalisation Properties
1252
1253                 int in - in point
1254                 int out - out point
1255
1256             Mutable Properties
1257
1258                 double start - the mix level to apply to the second frame.
1259                              - any negative value causes an automatic crossfade from 0 to 1.
1260                 double end - the ending value of the mix level. mix level will be interpolated
1261                              from start to end over the in-out range.
1262                 int reverse - set to 1 to reverse the direction of the mix.
1263
1264             Read Only Properties
1265
1266                 none
1267
1268             Dependencies
1269
1270                 none
1271
1272             Known Bugs
1273
1274                 Samples from the longer of the two frames are discarded.
1275
1276
1277         region
1278
1279             Description
1280
1281                 Apply zero or more filters to B frame as it is composited onto
1282                 a region of the A frame. The "shape" of the region can be defined
1283                 by the alpha channel of a third producer.
1284
1285             Constructor Argument
1286
1287                 resource - a shape producer
1288
1289             Initialisation Properties
1290
1291                 string resource - nothing is rectangle, "circle" is a pixbuf-
1292                     generated SVG circle, anything else is loaded by the factory.
1293                 string factory - the service that creates the shape producer.
1294                                - the default is fezzik.
1295                 string filter[N] - one or more filters to apply. All filter
1296                                    properties are passed using the same filter "key"
1297                 Any property starting with "composite." is passed to the
1298                     encapsulated composite transition.
1299
1300             Read Only Properties
1301
1302                 none
1303
1304             Dependencies
1305
1306                 transition_composite
1307
1308             Known Bugs
1309
1310                 none
1311
1312
1313 Consumers
1314 ---------
1315
1316         avformat
1317
1318             Description
1319
1320                 Multiformat transcoding consumer.
1321
1322             Constructor Argument
1323
1324                 string target - the filename to write to, e.g. test.mpeg.
1325
1326             Initialisation Properties
1327
1328                 int buffer - the number of frames to buffer, minimum 1, default 25.
1329                 string rescale - a rescale method, see the Filters/rescale.
1330                 int progressive - indicates whether to use progressive or field-
1331                                   based rendering, default 0 (off).
1332
1333             Read Only Properties
1334
1335                 none
1336
1337             Dependencies
1338
1339                 libavformat
1340
1341             Known Bugs
1342
1343                 Plenty.
1344
1345         bluefish (Proprietary)
1346
1347             Description
1348
1349                 BlueFish444 audio and video output module.
1350
1351             Constructor Argument
1352
1353                 card - a numeric card id starting at 1, default is 1.
1354
1355             Initialisation Properties
1356
1357                 string standard - "PAL" (default) or "NTSC"
1358                                 - default is based upon MLT_NORMALISATION
1359                                   environment variable, which defaults to PAL.
1360                 int frames - the number of DMA video frames. default is 8.
1361                              minimum is 2. maximum on my system is 11.
1362                 int buffer - the number of frames to buffer within MLT, minimum 1,
1363                              default 25.
1364                 string rescale - a rescale method, see the Filters/rescale.
1365
1366             Read Only Properties
1367
1368                 none
1369
1370             Dependencies
1371
1372                 BlueVelvet SDK installed parallel to mlt in "bluefish."
1373
1374             Known Bugs
1375
1376                 Does not work with any service that uses pipes!
1377
1378                 If mlt crashes, you might need to reload the BlueDriver kernel
1379                 module due to unreleased DMA buffers.
1380
1381                 Only supports 2 channel audio at the moment.
1382
1383         libdv
1384
1385             Description
1386
1387                 libdv dv producer.
1388
1389             Constructor Argument
1390
1391                 string target - the filename to write to, e.g. /dev/dv1394.
1392
1393             Initialisation Properties
1394
1395                 int buffer - the number of frames to buffer, minimum 1, default 25.
1396                 string rescale - a rescale method, see the Filters/rescale.
1397
1398             Mutable Properties
1399
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                 libdv
1410
1411             Known Bugs
1412
1413                 none
1414
1415         mcmpeg
1416
1417             Description
1418
1419                 Mainconcept MPEG encoder.
1420
1421             Constructor Argument
1422
1423                 string target - the filename to write to.
1424
1425             Initialisation Properties
1426
1427                 int buffer - the number of frames to buffer, minimum 1, default 25.
1428                 string rescale - a rescale method, see the Filters/rescale.
1429                 string format - vcd [default], svcd or dvd provide base settings
1430                 int motion_search_type - 0 to 16 - reduces quality/cpu usage
1431                 int gop - group of picture size (default: format dependent)
1432
1433             Mutable Properties
1434
1435                 int progressive - indicates whether to use progressive or field-
1436                                   based rendering, default 0 (off).
1437
1438             Read Only Properties
1439
1440                 none
1441
1442             Dependencies
1443
1444                 Mainconcept MPEG SDK
1445
1446             Known Bugs
1447
1448                 none
1449
1450         sdl
1451
1452             Description
1453
1454                 Simple DirectMedia Layer audio and video output module.
1455
1456             Constructor Argument
1457
1458                 string video_standard - "PAL" (default), "NTSC", or "WxH"
1459
1460             Initialisation Properties
1461
1462                 int buffer - the number of frames to buffer, minimum 1, default 25.
1463                 string rescale - a rescale method, see the Filters/rescale.
1464                                - Hint: "none" works very good with SDL output.
1465
1466             Mutable Properties
1467
1468                 double volume - audio level factor
1469                 int video_off - if 1, disable video output
1470                 int audio_off - if 1, disable audio output
1471                         int resize - TODO
1472                 int progressive - indicates whether to use progressive or field-
1473                                   based rendering, default 0 (off).
1474                 int audio_buffer - size of the sdl audio buffer (default: 1024)
1475
1476             Read Only Properties
1477
1478                 none
1479
1480             Dependencies
1481
1482                 libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
1483
1484             Known Bugs
1485
1486                 none
1487
1488         westley
1489
1490             Description
1491
1492                 Serialise the service network to XML.
1493                 See docs/westley.txt for more information.
1494
1495             Constructor Argument
1496
1497                 resource - the name of a file in which to store the XML.
1498                           - stdout is default.
1499
1500             Initialisation Properties
1501
1502                 string resource - same as above.
1503
1504             Dependencies
1505
1506                 libxml2
1507
1508             Known Bugs
1509
1510                 Untested arbitrary nesting of multitracks and playlists.
1511                 Property "id" is generated as service type followed by number if
1512                 no property named "id" exists, but it fails to guarantee uniqueness.