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