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

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