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