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

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