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