Service Documentation
-Copyright (C) 2004 Ushodaya Enterprises Limited
Authors: Charles Yates <charles.yates@pandora.be>
- Dan Dennedy <dan@dennedy.org>
-Last Revision: 2004-03-20
+ Dan Dennedy <dan@dennedy.org>
+Last Revision: $Date$
SERVICES
--------
- Services marked as "(Proprietary)" are not distributed with the GPL version
- of mlt.
+ Services marked as "(Proprietary)" are not distributed with the LGPL
+ version of mlt.
Producers
---------
Read Only Properties
string resource - file location
- double fps - this is fixed at 25 for PAL currently
double source_fps - the framerate of the resource
double aspect_ratio - sample aspect ratio of the resource
- this is determined on every frame read
Dependencies
- ffmpeg must be configured as --enable-shared and installed prior
- to compilation of mlt.
+ ffmpeg
Known Bugs
Audio sync discrepancy with some content.
Not all libavformat supported formats are seekable.
- Ogg Vorbis is currently broken.
- MPEG seeking is inaccurate - doesn't seek to i-frames so you may
- get junk for a few frames.
- RAW DV seeking not supported.
Fails to play beyond first frame of video of sources with PTS not
starting at 0 (video4linux).
Details
- This producer is has two roles:
+ This producer has two roles:
1. it handles the mappings of all file names to the other
producers;
none
- ffmpeg (DEPRECATED)
-
- Description
-
- Test case pipe based producer for video and audio.
-
- Constructor Argument
-
- 'file' - produce a/v from file
- v4l - produce a/v from video4linux and dsp device
-
- Initialisation Properties
-
- string video_type - "file" or "v4l"
- string video_file - file or v4l device
- string video_size - WxH of video to produce (default: "")
- int video_loop - loop video until audio exhausted (default: 0)
- string audio_type - "file" or "dsp"
- string audio_file - file or dsp device
- int audio_rate - audio frequency (default: 48000)
- int audio_channels - audio channels (default: 2)
- int audio_track - audio track to use (default: 0)
- int audio_loop - loop audio until video exhausted (default: 0)
- int in - in point
- int out - out point
- double fps - output frames per second (default: 25)
- double aspect_ratio - aspect ratio of video
-
- Read Only Properties
-
- string resource - file or "v4l"
- int end_of_clip - holds 1 when input is exhausted
-
- Dependencies
-
- ffmpeg executable.
-
- Known Bugs
-
- in point setting is broken.
-
- Implementation does not allow fast random access.
-
libdv
Description
default "Sans 48". FreeType2 renders at 72 dpi.
string encoding - the text encoding type of the input if not UTF-8.
- see 'iconv --list' for a list of possible inputs.
+ int weight - the weight of the font (default is 400)
Read Only Properties
int in - in point
int out - out point
+ int begin - when using an image sequence, this sets the starting
+ number.
Mutable Properties
Not a bug, but it only provides fair quality.
- ffmpeg_dub
-
- Description
-
- Use ffmpeg executable to substitute audio stream.
-
- Constructor Argument
-
- file - filename of a WAV, Ogg Vorbis (--enable-vorbis),
- MP3 (--enable-mp3lame), or AC-3 (--enable-a52) audio file.
-
- Initialisation Properties
-
- int in - in point
- int out - out point
-
- Read Only Properties
-
- string resource - file
-
- Dependencies
-
- ffmpeg plus for ffmpeg:
- libogg and libvorbis for Ogg Vorbis, libmp3lame for MP3, liba52 for AC-3.
-
- Known Bugs
-
- Uses pipes and is therefore not compatible with bluefish.
-
-
gamma
Description
none
+ gtkrescale
+
+ Description
+
+ Scale the producer video frame size to match the consumer.
+ This filter is designed for use as a Fezzik normaliser.
+
+ Constructor Argument
+
+ interpolation - the rescaling method, one of:
+ nearest (lowest quality, fastest),
+ tiles,
+ bilinear (default; good quality, moderate speed),
+ hyper (best quality, slowest).
+
+ Initialisation Properties
+
+ int in - in point
+ int out - out point
+
+ Mutable Properties
+
+ string interpolation - see constructor argument above
+
+ If a property "consumer_aspect_ratio" exists on the frame, then
+ rescaler normalises the producer's aspect ratio and maximises the
+ size of the frame, but may not produce the consumer's requested
+ dimension. Therefore, this option works best in conjunction with the
+ resize filter. This behavior can be disabled by another service by
+ either removing the property, setting it to zero, or setting
+ frame property "distort" to 1.
+
+ Dependencies
+
+ libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
+
+ Known Bugs
+
+ none
+
+ jackrack
+
+ Description
+
+ Creates Jack ports and runs a JackRack project to process audio
+ through a stack of LADSPA filters.
+
+ Constructor Argument
+
+ src - a JackRack file
+
+ Details
+
+ If you are using a consumer that uses ALSA, then you should start
+ jackd with the dummy driver: jackd -d dummy.
+ I also recommend using a period size of 2048: -p 2048.
+
+ jackd -ddummy -r48000 -p2048
+
+ Initialisation Properties
+
+ int in - in point
+ int out - out point
+
+ The following can be used without a rack file in order to connect
+ filter_jackrack to a running instance of JackRack:
+ string out_1 - Jack port to connect MLT's output port (JackRack's input)
+ string out_2 - Jack port to connect MLT's output port (JackRack's input)
+ string in_1 - Jack port to connect MLT's input port (JackRack's output)
+ string in_2 - Jack port to connect MLT's input port (JackRack's output)
+
+ Read Only Properties
+
+ none
+
+ Mutable Properties
+
+ none
+
+ Dependencies
+
+ Jack, LADSPA, glib-2.0, libxml2
+
+ Known Bugs
+
+ Currently, due to timing and synchronisation issues, the audio
+ is distorted with repeated samples and latency clicks.
+ no encapsulated resampling and jack runs at a fixed frequency
+
+ ladspa
+
+ Description
+
+ Runs a JackRack project to process audio through a stack of
+ LADSPA filters without using Jack.
+
+ Constructor Argument
+
+ src - a JackRack file
+
+ Details
+
+ Due to audio integrity issues with the jackrack filter, this
+ filter is better for runtime, while jackrack is more suitable
+ for prototyping a rack file using the Jack Rack GUI.
+
+ Initialisation Properties
+
+ int in - in point
+ int out - out point
+
+ Read Only Properties
+
+ none
+
+ Mutable Properties
+
+ none
+
+ Dependencies
+
+ Jack, LADSPA, glib-2.0, libxml2
+ Jack is still required because this coexists with the jackrack
+ filter.
+
+ Known Bugs
+
+ no encapsulated resampling and jack runs at a fixed frequency
+
luma
Description
none
+ mcrescale
+
+ Description
+
+ Scale the producer video frame size to match the consumer.
+ This filter is designed for use as a Fezzik normaliser.
+
+ Constructor Argument
+
+ interpolation - the rescaling method, one of:
+ nearest (lowest quality, fastest),
+ bilinear (default; good quality, moderate speed),
+ hyper (best quality, slowest).
+
+ Initialisation Properties
+
+ int in - in point
+ int out - out point
+
+ Mutable Properties
+
+ string interpolation - see constructor argument above
+
+ If a property "consumer_aspect_ratio" exists on the frame, then
+ rescaler normalises the producer's aspect ratio and maximises the
+ size of the frame, but may not produce the consumer's requested
+ dimension. Therefore, this option works best in conjunction with the
+ resize filter. This behavior can be disabled by another service by
+ either removing the property, setting it to zero, or setting
+ frame property "distort" to 1.
+
+ Dependencies
+
+ the mainconcept rescaling sdk.
+
+ Known Bugs
+
+ none
mirror
none
+ mono
+
+ Description
+
+ Mix all channels of audio into a mono signal and output it as
+ N channels.
+
+ Constructor Argument
+
+ channels - the number of output channels (default 2)
+
+ Initialisation Properties
+
+ none
+
+ Read Only Properties
+
+ none
+
+ Mutable Properties
+
+ none
+
+ Dependencies
+
+ none
+
+ Known Bugs
+
+ none
+
+
obscure
Description
Description
- Apply one or filters to a region of the video image. The region
+ Apply one or more filters to a region of the video image. The region
can be shaped as well using the alpha channel of another producer.
Constructor Argument
- file - A file whose alpha channel will "shape" the region.
+ resource - A file whose alpha channel will "shape" the region.
- The string "circle" is a shortcut but it requires pixbuf with
the librsvg loader. The circle is automatically stretched
to the region to create an ellipse.
Description
Scale the producer video frame size to match the consumer.
- This filter is automatically invoked by Fezzik in order to normalise
- sample aspect ratio.
+ This filter is designed for use as a Fezzik normaliser.
Constructor Argument
- interpolation - the rescaling method, one of:
- nearest (lowest quality, fastest),
- tiles,
- bilinear (default; good quality, moderate speed),
- hyper (best quality, slowest).
+ None.
Initialisation Properties
Mutable Properties
- string interpolation - see constructor argument above
-
If a property "consumer_aspect_ratio" exists on the frame, then
rescaler normalises the producer's aspect ratio and maximises the
size of the frame, but may not produce the consumer's requested
Dependencies
- libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
+ none
Known Bugs
- none
+ none but... it only implements a nearest neighbour scaling - it is
+ used as the base class for the gtkrescale and mcrescale filters.
resize
Description
- Adjust an audio stream's volume level
+ Adjust an audio stream's volume level
+ - based on the 'normalize' utility
Constructor Argument
Constructor Argument
- string start - a geometry specification as X,Y:WxH[!][:mix]
- - X, Y, W, H are assumed to pixel units unless they
- have the suffix '%'
- - '!' is a shortcut to specify distort, see below.
- - mix is always a 2 digit percentage, defaults to 100.
- - default is "85%,5%:10%x10%"
+ none[*]
Initialisation Properties
- string end - the ending size and position.
- string key[F] - X,Y:WxH[:mix] - set a key frame for geometry between
- the in and out. F is a frame number and can be
- negative to make it relative to the out point.
int in - in point
int out - out point
string factory - The name of a factory service used as a non-PGM
none
Mutable Properties
-
+
+
+ string geometry - key frame specification
+ - this is a ; delimited form of the deprecated start,
+ key[n], end properties
int progressive - set to 1 to disable field-based rendering.
string distort - when set, causes the B frame image to fill the WxH
completely with no regard to B's aspect ratio.
Any property starting with "luma." is passed to the non-PGM luma
producer.
+ Deprecated Properties
+
+ string start - a geometry specification as X,Y:WxH[!][:mix]
+ - X, Y, W, H are assumed to pixel units unless they
+ have the suffix '%'
+ - '!' is a shortcut to specify distort, see below.
+ - mix is always a 2 digit percentage, defaults to 100.
+ - default is "85%,5%:10%x10%"
+ string end - the ending size and position.
+ string key[F] - X,Y:WxH[:mix] - set a key frame for geometry between
+ the in and out. F is a frame number and can be
+ negative to make it relative to the out point.
+
Dependencies
none
A generic dissolve and wipe transition processor.
- Initialisation Properties
-
- int in - in point
- int out - out point
- string factory - The name of a factory service used as a non-PGM
- producer loader. The default is Fezzik.
-
- Mutable Properties
-
- string resource - same as above
- double softness - only when using a luma map, how soft to make the
- edges between A and B. 0.0 = no softness. 1.0 =
- too soft.
- int reverse - reverse the direction of the transition.
- Any property starting with "producer." is passed to the non-PGM luma
- producer.
-
- Read Only Properties
-
- none
-
- Dependencies
+ Details
luma gets its name
from how it uses a grayscale "map" file. As the luma value varies
double softness - only when using a luma map, how soft to make the
edges between A and B. 0.0 = no softness. 1.0 =
too soft.
+ int reverse - reverse the direction of the transition.
Any property starting with "producer." is passed to the non-PGM luma
producer.
none
+ mcmpeg
+
+ Description
+
+ Mainconcept MPEG encoder.
+
+ Constructor Argument
+
+ string target - the filename to write to.
+
+ Initialisation Properties
+
+ int buffer - the number of frames to buffer, minimum 1, default 25.
+ string rescale - a rescale method, see the Filters/rescale.
+ string format - vcd [default], svcd or dvd provide base settings
+ int motion_search_type - 0 to 16 - reduces quality/cpu usage
+ int gop - group of picture size (default: format dependent)
+
+ Mutable Properties
+
+ int progressive - indicates whether to use progressive or field-
+ based rendering, default 0 (off).
+
+ Read Only Properties
+
+ none
+
+ Dependencies
+
+ Mainconcept MPEG SDK
+
+ Known Bugs
+
+ none
+
sdl
Description
double volume - audio level factor
int video_off - if 1, disable video output
int audio_off - if 1, disable audio output
- int scale_overlay - if 1, resample video from source pixel aspect
- ratio to square pixels.
+ int resize - TODO
int progressive - indicates whether to use progressive or field-
based rendering, default 0 (off).
+ int audio_buffer - size of the sdl audio buffer (default: 1024)
Read Only Properties