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

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