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

   1 Producers
   2 ---------
   3
   4         avformat
   5
   6                 Description
   7
   8                         ffmpeg libavformat based producer for video and audio.
   9
  10                 Constructor Argument
  11
  12                         'file' - producer a/v from file
  13
  14                 Initialisation Properties
  15
  16                         int video_index - index of video stream to use (-1 is off)
  17                         int audio_index - index of audio stream to use (-1 is off)
  18                         int in - in point
  19                         int out - out point
  20
  21                 Read Only Properties
  22
  23                         double fps - this is fixed at 25 for PAL currently
  24                         double aspect_ratio - this is determined on the first frame read
  25
  26                 Dependencies
  27
  28                         ffmpeg must be configured as --enable-shared and installed prior
  29                         to compilation of mlt.
  30
  31                 Oddities
  32
  33                         MPEG video remains elusive.
  34
  35                 Known Bugs
  36
  37                         Fixed frame rate.
  38                         Audio sync discrepancy with some content.
  39                         Not all libavformat supported formats are seekable.
  40                         ogg is currently broken.
  41                         mpeg seeking is inaccurate - doesn't seek to i-frames so you may
  42                         get junk for a few frames.
  43
  44         fezzik
  45
  46                 Description
  47
  48                         A friendly giant that likes to rhyme and throw rocks
  49
  50                 Constructor Argument
  51
  52                         'file'  - produce a/v from file
  53
  54                 Initialisation Properties
  55
  56                         int in - in point
  57                         int out - out point
  58                         + all producer initialising properties
  59
  60                 Read Only Properties
  61
  62                         string resource - file location
  63                         + all producer read only properties
  64
  65                 Details
  66
  67                         This producer is has two roles:
  68
  69                         1. it handles the mappings of all file names to the other
  70                         producers;
  71                         2. it attaches normalising filters (rescale, resize and resample)
  72                         to the producers (when necessary).
  73
  74                         This producer simplifies many aspects of use. Essentially, it
  75                         ensures that a consumer will receive images and audio precisely as
  76                         they request them.
  77
  78                 Dependencies
  79
  80                         all.
  81
  82                 Known Bugs
  83
  84                         None.
  85
  86         ffmpeg
  87
  88                 Description
  89
  90                         Test case pipe based producer for video and audio.
  91
  92                 Constructor Argument
  93
  94                         'file'  - produce a/v from file
  95                         v4l             - produce a/v from video4linux and dsp device
  96
  97                 Initialisation Properties
  98
  99                         string video_type - "file" or "v4l"
 100                         string video_file - file or v4l device
 101                         string video_size - WxH of video to produce (default: "")
 102                         int video_loop - loop video until audio exhausted (default: 0)
 103                         string audio_type - "file" or "dsp"
 104                         string audio_file - file or dsp device
 105                         int audio_rate - audio frequency (default: 48000)
 106                         int audio_channels - audio channels (default: 2)
 107                         int audio_track - audio track to use (default: 0)
 108                         int audio_loop - loop audio until video exhausted (default: 0)
 109                         int in - in point
 110                         int out - out point
 111                         double fps - output frames per second (default: 25)
 112                         double aspect_ratio - aspect ratio of video
 113
 114                 Read Only Properties
 115
 116                         string resource - file or "v4l"
 117                         int end_of_clip - holds 1 when input is exhausted
 118
 119                 Dependencies
 120
 121                         ffmpeg executable.
 122
 123                 Known Bugs
 124
 125                         in point setting is broken.
 126
 127                         Implementation does not allow fast random access.
 128
 129         libdv
 130
 131                 Description
 132
 133                         libdv based decoder for video and audio.
 134
 135                 Constructor Argument
 136
 137                         'file'  - produce a/v from file
 138
 139                 Initialisation Properties
 140
 141                         int in - in point
 142                         int out - out point
 143
 144                 Read Only Properties
 145
 146                         string resource - file location
 147                         double fps - output frames per second
 148                         double aspect_ratio - aspect ratio of video]
 149                         int length - duration of resource (in frames)
 150
 151                 Dependencies
 152
 153                         libdv.
 154
 155                 Known Bugs
 156
 157                         None.
 158
 159         mcdv
 160
 161                 Description
 162
 163                         Mainconcept based dv decoder for video and audio.
 164
 165                 Constructor Argument
 166
 167                         'file'  - produce a/v from file
 168
 169                 Initialisation Properties
 170
 171                         int in - in point
 172                         int out - out point
 173
 174                 Read Only Properties
 175
 176                         string resource - file location
 177                         double fps - output frames per second
 178                         double aspect_ratio - aspect ratio of video
 179                         int length - duration of resource (in frames)
 180
 181                 Dependencies
 182
 183                         mainconcept dv sdk and libdv.
 184                         "dv_sdk" installed parallel to mlt.
 185
 186                 Known Bugs
 187
 188                         Can be problematic with some NTSC DV files?
 189
 190         mcmpeg
 191
 192                 Description
 193
 194                         Mainconcept based mpeg decoder for video and audio.
 195
 196                 Constructor Argument
 197
 198                         'file'  - produce a/v from file
 199
 200                 Initialisation Properties
 201
 202                         int in - in point
 203                         int out - out point
 204
 205                 Read Only Properties
 206
 207                         string resource - file location
 208                         double fps - output frames per second
 209                         double aspect_ratio - aspect ratio of video
 210
 211                 Dependencies
 212
 213                         mainconcept mpeg sdk.
 214                         "mpeg_sdk_demo" installed parallel to mlt.
 215
 216                 Known Bugs
 217
 218                         None.
 219
 220         pango
 221
 222                 Description
 223
 224                         A title generator that uses the Pango international text layout
 225                         and Freetype2 font renderer.
 226
 227                 Constructor Argument
 228
 229                         string file - a text file containing Pango markup, see:
 230                                    http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
 231                                    - requires xml-like encoding special chars: <, >, & to &lt;, &gt;, &amp;
 232
 233                 Initialisation Properties
 234
 235                         int in - in point
 236                         int out - out point
 237
 238                 Mutable Properties
 239
 240                         int video_standard - enum mlt_video_standard from mlt_frame.h
 241                                              PAL = 0, NTSC = 1
 242                                              this determines proper pixel aspect ratio
 243
 244                         string markup - a string containing Pango markup see:
 245                                         http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
 246                                       - requires xml-like encoding special chars: <, >, & to &lt;, &gt;, &amp;
 247
 248                         string fgcolour - an rgba colour specification of the text (i.e. 0xrrggbbaa)
 249                         string bgcolour - an rgba colour of the background rectangle
 250                         int align - paragraph alignment: 0 = left, 1 = center, 2 = right
 251                         int pad - the number of pixels to pad the background rectangle beyond edges of text
 252                                   default 0
 253                         string markup - see constructor argument
 254                         string text - non-markup text (can contain markup chars un-encoded)
 255                         string font - the default typeface to use when not using markup
 256                                       default "Sans 48"
 257
 258                 Read Only Properties
 259
 260                         string resource - the text/markup file or "pango" if no file
 261
 262                 Dependencies
 263
 264                         libpango-1.0, libpangoft2-1.0, libfreetype, libgdk_pixbuf-2.0, libglib-2.0,
 265                         libgobject-2.0, libgmodule-2.0, libfontconfig
 266
 267                 Known Bugs
 268
 269                         no frame-alignment functionality
 270
 271         pixbuf
 272
 273                 Description
 274
 275                         A graphics overlay generator using gdk-pixbuf
 276
 277                 Constructor Argument
 278
 279                         'file' - The name of a graphics file loadable by
 280                                  a gdk-pixbuf loader. see /usr/lib/gdk-pixbuf/loaders
 281                                  definitely png, jpeg, tiff, pnm, and xpm
 282                                - If "%" in filename, the filename is used with sprintf
 283                                  generate a filename from a counter for multi-file/flipbook animation.
 284                                  The file sequence ends when numeric discontinuity >100.
 285                                - If filename contains "/.all.", suffix with an extension to load
 286                                  all pictures with matching extension from a directory
 287
 288                 Initialisation Properties
 289
 290                         int in - in point
 291                         int out - out point
 292
 293                 Mutable Properties
 294
 295                         int video_standard - enum mlt_video_standard from mlt_frame.h
 296                                              PAL = 0, NTSC = 1
 297                                              this determines proper pixel aspect ratio
 298                         double ttl - how long (seconds) to repeat each picture in file sequences
 299
 300                 Read Only Properties
 301
 302                         string resource - file location
 303
 304                 Dependencies
 305
 306                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
 307
 308                 Known Bugs
 309
 310                         in/out settings are incorrectly handled.
 311
 312         ppm
 313
 314                 Description
 315
 316                         Reads a stream of contiguous PPM images.
 317
 318                 Constructor Argument
 319
 320                         command - a shell command to run something that produces ppm
 321                                   streams on stdout.
 322
 323                 Initialisation Properties
 324
 325                         none
 326
 327                 Read Only Properties
 328
 329                         string resource - the command
 330
 331                 Dependencies
 332
 333                         none
 334
 335                 Known Bugs
 336
 337                         Since it uses pipes, it is not compatible with bluefish.
 338
 339         westley
 340
 341                 Description
 342
 343                         Construct a service network from an XML description.
 344
 345                 Constructor Argument
 346
 347                         file - an XML text file containing westley XML (schema pending)
 348
 349                 Read Only Properties
 350
 351                         string resource - file location
 352
 353                 Dependencies
 354
 355                         libxml2
 356
 357                 Known Bugs
 358
 359                         Non-referenced producers and playlists are not destroyed.
 360                         A referenced producer or playlist must appear before the reference.
 361
 362         vorbis
 363
 364                 Description
 365
 366                         OGG Vorbis file reader.
 367
 368                 Constructor Argument
 369
 370                         'file' - file to use (only .ogg supported at the moment)
 371
 372                 Initialisation Properties
 373
 374                         int in - in point
 375                         int out - out point
 376
 377                 Read Only Properties
 378
 379                         double fps - this is fixed at 25 for PAL currently
 380
 381                 Dependencies
 382
 383                         libvorbisfile
 384
 385                 Known Bugs
 386
 387                         Fixed frame size (PAL audio chunks).
 388                         Doesn't cover ogg files with multiple, differing sections.
 389
 390 Filters
 391 -------
 392
 393         deinterlace
 394
 395                 Description
 396
 397                         Deinterlace a frame consisting of two fields by linearly blending.
 398
 399                 Constructor Argument
 400
 401                         none
 402
 403                 Initialisation Properties
 404
 405                         int in - in point
 406                         int out - out point
 407
 408                 Read Only Properties
 409
 410                         none
 411
 412                 Dependencies
 413
 414                         none
 415
 416                 Known Bugs
 417
 418                         Not a bug, but it only provides fair quality at a fair performance;
 419                                 i.e., it excels at neither.
 420
 421         ffmpeg_dub
 422
 423                 Description
 424
 425                     Use ffmpeg executable to substitute audio stream.
 426
 427                 Constructor Argument
 428
 429                         file - filename of a WAV, Ogg Vorbis (--enable-vorbis),
 430                                MP3 (--enable-mp3lame), or AC-3 (--enable-a52) audio file.
 431
 432                 Initialisation Properties
 433
 434                         int in - in point
 435                         int out - out point
 436
 437                 Read Only Properties
 438
 439                         string resource - file
 440
 441                 Dependencies
 442
 443                         ffmpeg plus for ffmpeg:
 444                         libogg and libvorbis for Ogg Vorbis, libmp3lame for MP3, liba52 for AC-3.
 445
 446                 Known Bugs
 447
 448                         Uses pipes and is therefore not compatible with bluefish.
 449
 450         gamma
 451
 452                 Description
 453
 454                         Adjust image luma using a non-linear power-law curve
 455
 456                 Constructor Argument
 457
 458                         gamma - a floating point value
 459
 460                 Initialisation Properties
 461
 462                         int in - in point
 463                         int out - out point
 464
 465                 Mutable Properties
 466
 467                         double gamma - the exponential factor of the power-law curve
 468
 469                 Dependencies
 470
 471                         none
 472
 473                 Known Bugs
 474
 475                         none
 476
 477         greyscale
 478
 479                 Description
 480
 481                         Convert colour image to greyscale
 482
 483                 Constructor Argument
 484
 485                         none
 486
 487                 Initialisation Properties
 488
 489                         int in - in point
 490                         int out - out point
 491
 492                 Read Only Properties
 493
 494                         none
 495
 496                 Dependencies
 497
 498                         none
 499
 500                 Known Bugs
 501
 502                         none
 503
 504         obscure
 505
 506                 Description
 507
 508                         Obscuring filter.
 509
 510                 Constructor Argument
 511
 512                         none
 513
 514                 Initialisation Properties
 515
 516                         string start - in the format X,Y:WxH[:PWxPY]
 517                         string end - in the format X,Y:WxH[:PWxPY]
 518                         int in - in point
 519                         int out - out point
 520
 521                 Read Only Properties
 522
 523                         none
 524
 525                 Dependencies
 526
 527                         none
 528
 529                 Known Bugs
 530
 531                         none
 532
 533         resize
 534
 535                 Description
 536
 537                         Image scaling and padding
 538
 539                 Constructor Argument
 540
 541                         scale - "affine" to use affine transform scaling, otherwise
 542                                  center and pad.
 543
 544                 Initialisation Properties
 545
 546                         int in - in point
 547                         int out - out point
 548
 549                 Read Only Properties
 550
 551                         none
 552
 553                 Dependencies
 554
 555                         none
 556
 557                 Known Bugs
 558
 559                         none
 560
 561         volume
 562
 563                 Description
 564
 565                         Adjust an audio stream's volume level
 566
 567                 Constructor Argument
 568
 569                         gain - a string containing one of:
 570                                  - a floating point value of the gain adjustment
 571                                  - a numeric value with the suffix "dB" to adjust in terms of decibels
 572                                  - "normalise" to normalise the volume to the target amplitude -12dBFS
 573
 574                 Initialisation Properties
 575
 576                         int in - in point
 577                         int out - out point
 578                         int window - the number of video frames over which to smooth normalisation.
 579                                      defaults to 75.
 580
 581                 Mutable Properties
 582
 583                         string gain - same as constructor argument above
 584
 585                         string normalise - normalise the volume to the amplitude:
 586                                 - a numeric value with the suffix "dB" to set amplitude in decibels
 587                                 - a floating point value of the relative volume
 588                                 - an unspecified value uses the default -12dBFS
 589
 590                         string limiter - limit all samples above:
 591                                 - a numeric value with the suffix "dB"
 592                                 - a floating point value ( dB = 20 * log10(x) )
 593                                 - an unspecified value uses the default -6dBFS
 594
 595                         double max_gain - a floating point or decibel value of the maximum gain that
 596                                 can be applied during normalisation.
 597                                 - an unspecified value uses the default 20dB
 598
 599                         string end - a gain value just like the gain property above.
 600                                      This causes the gain to be interpolated from 'gain' to 'end'
 601                                      over the duration.
 602
 603                         int window - the size of the normalising smoothing buffer in video frame units.
 604                                    - the smoothing buffer prevents erratic gain changes.
 605                                    - the default value is 75 video frames.
 606
 607                         gain can be applied as a factor to the normalise amplitude!
 608
 609                 Dependencies
 610
 611                         none
 612
 613                 Known Bugs
 614
 615                         none
 616
 617         resample
 618
 619                 Description
 620
 621                         Adjust an audio stream's sampling rate
 622
 623                 Constructor Argument
 624
 625                         frequency - a numeric value for the new sample rate
 626
 627                 Initialisation Properties
 628
 629                         int in - in point
 630                         int out - out point
 631
 632                 Mutable Properties
 633
 634                         int frequency - the target sample rate
 635
 636                 Dependencies
 637
 638                         libresample
 639
 640                 Known Bugs
 641
 642                         none
 643
 644         rescale
 645
 646                 Description
 647
 648                         Scale the producer video frame size to match the consumer.
 649
 650                 Constructor Argument
 651
 652                         interpolation - the rescaling method, one of:
 653                                 nearest (lowest quality, fastest),
 654                                 tiles,
 655                                 bilinear (good quality, moderate speed),
 656                                 hyper (best quality, slowest)
 657
 658                 Initialisation Properties
 659
 660                         int in - in point
 661                         int out - out point
 662
 663                 Mutable Properties
 664
 665                         string interpolation - see constructor argument above
 666
 667                         If a property "consumer_aspect_ratio" exists on the frame, then
 668                         rescaler normalises the producer's aspect ratio and maximises the
 669                         size of the frame, but may not produce the consumer's requested
 670                         dimension. Therefore, this option works best in conjunction with the
 671                         resize filter. This behavior can be disabled by another service by
 672                         either removing the property, setting it to zero, or setting
 673                         frame property "distort" to 1.
 674
 675                 Dependencies
 676
 677                         libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
 678
 679                 Known Bugs
 680
 681                         none
 682
 683 Transitions
 684 -----------
 685
 686         composite
 687
 688                 Description
 689
 690                         An alpha-channel based compositor for two frames.
 691
 692                 Constructor Argument
 693
 694                         string start - X,Y:WxH[:mix]
 695
 696                 Initialisation Properties
 697
 698                         string end - X,Y:WxH[:mix]
 699                         int in - in point
 700                         int out - out point
 701
 702                 Read Only Properties
 703
 704                         none
 705
 706                 Dependencies
 707
 708                         none
 709
 710                 Known Bugs
 711
 712                         Need to add field-based rendering.
 713
 714         luma
 715
 716                 Description
 717
 718                         A generic dissolve and wipe transition processor. It gets its name
 719                         from how it uses a grayscale "map" file. As the luma value varies
 720                         over time, a threshold filter is applied to the map to determine
 721                         what parts of frame A vs. frame B to show. It only reads PGM
 722                         files, but it does handle 16 bit PGM. This performs field-based
 723                         rendering.
 724
 725                 Constructor Argument
 726
 727                         string resource - the luma map file name. If not supplied, a dissolve.
 728
 729                 Initialisation Properties
 730
 731                         int in - in point
 732                         int out - out point
 733
 734                 Mutable Properties
 735
 736                         string resource - same as above
 737                         double softness - only when using a luma map, how soft to make the
 738                                           edges between A and B. 0.0 = no softness. 1.0 =
 739                                           too soft.
 740
 741                 Read Only Properties
 742
 743                         none
 744
 745                 Dependencies
 746
 747                         none
 748
 749                 Known Bugs
 750
 751                         The luma map must be the same size as the B frame.
 752                         The PGM parser does not handle comments.
 753
 754         mix
 755
 756                 Description
 757
 758                         An two stream audio mixer.
 759
 760                 Constructor Argument
 761
 762                         start - see below
 763
 764                 Initalisation Properties
 765
 766                         int in - in point
 767                         int out - out point
 768
 769                 Mutable Properties
 770
 771                         double start - the mix level to apply to the second frame.
 772                                      - any negative value causes an automatic crossfade from 0 to 1.
 773                         double end - the ending value of the mix level. mix level will be interpolated
 774                                      from start to end over the in-out range.
 775                         int reverse - set to 1 to reverse the direction of the mix.
 776
 777                 Read Only Properties
 778
 779                         none
 780
 781                 Dependencies
 782
 783                         none
 784
 785                 Known Bugs
 786
 787                         Samples from the longer of the two frames are discarded.
 788
 789 Consumers
 790 ---------
 791
 792         bluefish
 793
 794                 Description
 795
 796                         BlueFish444 audio and video output module.
 797
 798                 Constructor Argument
 799
 800                         string video_standard - "PAL" (default) or "NTSC"
 801
 802                 Initialisation Properties
 803
 804                         int video_standard - 0 = PAL, 1 = NTSC
 805
 806                 Read Only Properties
 807
 808                         none
 809
 810                 Dependencies
 811
 812                         BlueVelvet SDK installed parallel to mlt in "bluefish."
 813
 814                 Known Bugs
 815
 816                         Does not work with any service that uses pipes!
 817
 818                         If mlt crashes, you must reload the BlueDriver kernel module
 819                         due to unreleased DMA buffers.
 820
 821                         Needs an argument or property for multi-card address.
 822
 823         ffmpeg
 824
 825                 Description
 826                 Constructor Argument
 827                 Initialisation Properties
 828                 Read Only Properties
 829                 Dependencies
 830                 Known Bugs
 831
 832         libdv
 833
 834                 Description
 835
 836                         libdv dv producer.
 837
 838                 Constructor Argument
 839
 840                         string video_standard - "PAL" (default) or "NTSC"
 841
 842                 Initialisation Properties
 843                 Read Only Properties
 844                 Dependencies
 845                 Known Bugs
 846
 847         sdl
 848
 849                 Description
 850
 851                         Simple DirectMedia Layer audio and video output module.
 852
 853                 Constructor Argument
 854
 855                         string video_standard - "PAL" (default), "NTSC", or "WxH"
 856
 857                 Mutable Properties
 858
 859                         double volume - audio level factor
 860                         int video_off - if 1, disable video output
 861                         int audio_off - if 1, disable audio output
 862                         int scale_overlay - if 1, resample video from source pixel aspect
 863                                             ratio to square pixels.
 864
 865                 Read Only Properties
 866
 867                         none
 868
 869                 Dependencies
 870
 871                         libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
 872
 873                 Known Bugs
 874
 875                         NTSC handling needs tightening up - sdl:NTSC is the only valid
 876                         constructor for NTSC playback at the moment.
 877
 878         westley
 879
 880                 Description
 881
 882                         Serialise the service network to XML.
 883
 884                 Constructor Argument
 885
 886                         resource - the name of a file in which to store the XML.
 887                                 stdout is used if not supplied.
 888
 889                 Initialisation Properties
 890
 891                         string resource - same as above.
 892
 893                 Dependencies
 894
 895                         libxml2
 896
 897                 Known Bugs
 898
 899                         Untested arbitrary nesting of multitracks and playlists.
 900                         Property "id" is generated as service type followed by number if
 901                         no property named "id" exists, but it fails to guarantee uniqueness.
 902