research.m1stereo.tv/gitweb/ - melted/blob - docs/services.txt

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