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

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