X-Git-Url: http://research.m1stereo.tv/gitweb?a=blobdiff_plain;f=docs%2Fservices.txt;h=6500f5ff831ca600b64f7a965812408c46a6986d;hb=10e377d51ca937d99a68723dd53026953a6a5c6d;hp=16c42cc58fba45381f5df7640a2beca8fc6b7885;hpb=160b37d9aa19e895958c4f87a19e6f3c57765337;p=melted diff --git a/docs/services.txt b/docs/services.txt index 16c42cc..6500f5f 100644 --- a/docs/services.txt +++ b/docs/services.txt @@ -1,6 +1,83 @@ Producers --------- + avformat + + Description + + ffmpeg libavformat based producer for video and audio. + + Constructor Argument + + 'file' - producer a/v from file + + Initialisation Properties + + int video_index - index of video stream to use (-1 is off) + int audio_index - index of audio stream to use (-1 is off) + int in - in point + int out - out point + + Read Only Properties + + double fps - this is fixed at 25 for PAL currently + double aspect_ratio - this is determined on the first frame read + + Dependencies + + ffmpeg must be configured as --enable-shared and installed prior + to compilation of mlt. + + Known Bugs + + Audio sync discrepancy with some content. + Not all libavformat supported formats are seekable. + ogg is currently broken. + mpeg seeking is inaccurate - doesn't seek to i-frames so you may + get junk for a few frames. + + fezzik + + Description + + A friendly giant that likes to rhyme and throw rocks + + Constructor Argument + + 'file' - produce a/v from file + + Initialisation Properties + + int in - in point + int out - out point + + all producer initialising properties + + Read Only Properties + + string resource - file location + + all producer read only properties + + Details + + This producer is has two roles: + + 1. it handles the mappings of all file names to the other + producers; + 2. it attaches normalising filters (rescale, resize and resample) + to the producers (when necessary). + + This producer simplifies many aspects of use. Essentially, it + ensures that a consumer will receive images and audio precisely as + they request them. + + Dependencies + + all. + + Known Bugs + + None. + ffmpeg Description @@ -24,8 +101,8 @@ Producers 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) - timecode in - in point - timecode out - out point + int in - in point + int out - out point double fps - output frames per second (default: 25) double aspect_ratio - aspect ratio of video @@ -56,15 +133,15 @@ Producers Initialisation Properties - timecode in - in point - timecode out - out point + int in - in point + int out - out point Read Only Properties string resource - file location - double fps - output frames per second + double fps - output frames per second double aspect_ratio - aspect ratio of video] - timecode length - duration of resource (in seconds) + int length - duration of resource (in frames) Dependencies @@ -86,15 +163,15 @@ Producers Initialisation Properties - timecode in - in point - timecode out - out point + int in - in point + int out - out point Read Only Properties string resource - file location - double fps - output frames per second + double fps - output frames per second double aspect_ratio - aspect ratio of video - timecode length - duration of resource (in seconds) + int length - duration of resource (in frames) Dependencies @@ -103,8 +180,7 @@ Producers Known Bugs - Can be problematic with source NTSC DV files? really? yes - try - playing pond.dv... + Can be problematic with some NTSC DV files? mcmpeg @@ -118,13 +194,13 @@ Producers Initialisation Properties - timecode in - in point - timecode out - out point + int in - in point + int out - out point Read Only Properties string resource - file location - double fps - output frames per second + double fps - output frames per second double aspect_ratio - aspect ratio of video Dependencies @@ -137,7 +213,7 @@ Producers None. pango - + Description A title generator that uses the Pango international text layout @@ -151,11 +227,11 @@ Producers Initialisation Properties - timecode in - in point - timecode out - out point + int in - in point + int out - out point Mutable Properties - + int video_standard - enum mlt_video_standard from mlt_frame.h PAL = 0, NTSC = 1 this determines proper pixel aspect ratio @@ -164,8 +240,8 @@ Producers http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html - requires xml-like encoding special chars: <, >, & to <, >, & - int fgcolor - an rgba color specification of the text (i.e. 0xrrggbbaa) - int bgcolor - an rgba color of the background rectangle + string fgcolour - an rgba colour specification of the text (i.e. 0xrrggbbaa) + string bgcolour - an rgba colour of the background rectangle int align - paragraph alignment: 0 = left, 1 = center, 2 = right int pad - the number of pixels to pad the background rectangle beyond edges of text default 0 @@ -173,12 +249,6 @@ Producers string text - non-markup text (can contain markup chars un-encoded) string font - the default typeface to use when not using markup default "Sans 48" - int x - the horizontal position of the title on the frame - default 0 - int y - the vertical position of the title on the frame - default 0 - double mix - the overall opacity control of the generated title - default 1.0 Read Only Properties @@ -212,8 +282,8 @@ Producers Initialisation Properties - timecode in - in point - timecode out - out point + int in - in point + int out - out point Mutable Properties @@ -221,11 +291,6 @@ Producers PAL = 0, NTSC = 1 this determines proper pixel aspect ratio double ttl - how long (seconds) to repeat each picture in file sequences - int x - the horizontal offset from the left edge of the frame - int y - the vertical offset from the top edge of the frame - double mix - the opacity factor to apply to the second frame - (used in addition to alpha channel). - Read Only Properties @@ -233,20 +298,89 @@ Producers Dependencies - libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0 + libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0 Known Bugs in/out settings are incorrectly handled. ppm + Description + + Reads a stream of contiguous PPM images. + Constructor Argument + + command - a shell command to run something that produces ppm + streams on stdout. + Initialisation Properties + + none + Read Only Properties + + string resource - the command + Dependencies + + none + Known Bugs + Since it uses pipes, it is not compatible with bluefish. + + westley + + Description + + Construct a service network from an XML description. + + Constructor Argument + + file - an XML text file containing westley XML (schema pending) + + Read Only Properties + + string resource - file location + + Dependencies + + libxml2 + + Known Bugs + + Non-referenced producers and playlists are not destroyed. + A referenced producer or playlist must appear before the reference. + + vorbis + + Description + + OGG Vorbis file reader. + + Constructor Argument + + 'file' - file to use (only .ogg supported at the moment) + + Initialisation Properties + + int in - in point + int out - out point + + Read Only Properties + + double fps - this is fixed at 25 for PAL currently + + Dependencies + + libvorbisfile + + Known Bugs + + Fixed frame size (PAL audio chunks). + Doesn't cover ogg files with multiple, differing sections. Filters ------- @@ -254,48 +388,324 @@ Filters deinterlace Description + + Deinterlace a frame consisting of two fields by linearly blending. + Constructor Argument + + none + Initialisation Properties + + int in - in point + int out - out point + Read Only Properties + + none + Dependencies + + none + Known Bugs + + Not a bug, but it only provides fair quality at a fair performance; + i.e., it excels at neither. 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 + + Adjust image luma using a non-linear power-law curve + Constructor Argument + + gamma - a floating point value + Initialisation Properties - Read Only Properties + + int in - in point + int out - out point + + Mutable Properties + + double gamma - the exponential factor of the power-law curve + Dependencies + + none + Known Bugs + + none greyscale Description + + Convert colour image to greyscale + Constructor Argument + + none + Initialisation Properties + + int in - in point + int out - out point + Read Only Properties + + none + Dependencies + + none + Known Bugs + + none + obscure + + Description + + Obscuring filter. + + Constructor Argument + + none + + Initialisation Properties + + string start - in the format X,Y:WxH[:PWxPY] + string end - in the format X,Y:WxH[:PWxPY] + int in - in point + int out - out point + + Read Only Properties + + none + + Dependencies + + none + + Known Bugs + + none + resize Description + + Image scaling and padding + Constructor Argument + + scale - "affine" to use affine transform scaling, otherwise + center and pad. + Initialisation Properties + + int in - in point + int out - out point + Read Only Properties + + none + + Dependencies + + none + + Known Bugs + + none + + resample + + Description + + Adjust an audio stream's sampling rate + + Constructor Argument + + frequency - a numeric value for the new sample rate + + Initialisation Properties + + int in - in point + int out - out point + + Mutable Properties + + int frequency - the target sample rate + Dependencies + + libresample + Known Bugs + none + + rescale + + Description + + Scale the producer video frame size to match the consumer. + + Constructor Argument + + interpolation - the rescaling method, one of: + nearest (lowest quality, fastest), + tiles, + bilinear (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 + + volume + + Description + + Adjust an audio stream's volume level + + Constructor Argument + + gain - a string containing one of: + - a floating point value of the gain adjustment + - a numeric value with the suffix "dB" to adjust in terms of decibels + - "normalise" to normalise the volume to the target amplitude -12dBFS + + Initialisation Properties + + int in - in point + int out - out point + int window - the number of video frames over which to smooth normalisation. + defaults to 75. + + Mutable Properties + + string gain - same as constructor argument above + + string normalise - normalise the volume to the amplitude: + - a numeric value with the suffix "dB" to set amplitude in decibels + - a floating point value of the relative volume + - an unspecified value uses the default -12dBFS + + string limiter - limit all samples above: + - a numeric value with the suffix "dB" + - a floating point value ( dB = 20 * log10(x) ) + - an unspecified value uses the default -6dBFS + + double max_gain - a floating point or decibel value of the maximum gain that + can be applied during normalisation. + - an unspecified value uses the default 20dB + + string end - a gain value just like the gain property above. + This causes the gain to be interpolated from 'gain' to 'end' + over the duration. + + int window - the size of the normalising smoothing buffer in video frame units. + - the smoothing buffer prevents erratic gain changes. + - the default value is 75 video frames. + + gain can be applied as a factor to the normalise amplitude! + + Dependencies + + none + + Known Bugs + + none + + watermark + + Description + + Add a watermark to the frames. + + Constructor Argument + + resource - the producer to use (ie: a .png) + + Initialisation Properties + + string resource - the producer to use + string factory - producer required for the resource ('fezzik') + string geometry - composite geometry + string distort - control scaling + int in - in point + int out - out point + + Mutable Properties + + none + + Dependencies + + mlt core modules and optionally, fezzik + + Known Bugs + + none + Transitions ----------- @@ -307,15 +717,14 @@ Transitions Constructor Argument - none - - Mutable Properties + string start - X,Y:WxH[:mix] - int x - the horizontal offset from the left edge of the frame - int y - the vertical offset from the top edge of the frame - double mix - the opacity factor to apply to the second frame - (used in addition to alpha channel). - + Initialisation Properties + + string end - X,Y:WxH[:mix] + int in - in point + int out - out point + Read Only Properties none @@ -341,11 +750,16 @@ Transitions Constructor Argument - string file - the luma map file name. If not supplied, a dissolve. + string resource - the luma map file name. If not supplied, a dissolve. + + Initialisation Properties + int in - in point + int out - out point + Mutable Properties - string filename - same as above + 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. @@ -361,6 +775,42 @@ Transitions Known Bugs The luma map must be the same size as the B frame. + The PGM parser does not handle comments. + + mix + + Description + + An two stream audio mixer. + + Constructor Argument + + start - see below + + Initalisation Properties + + int in - in point + int out - out point + + Mutable Properties + + double start - the mix level to apply to the second frame. + - any negative value causes an automatic crossfade from 0 to 1. + double end - the ending value of the mix level. mix level will be interpolated + from start to end over the in-out range. + int reverse - set to 1 to reverse the direction of the mix. + + Read Only Properties + + none + + Dependencies + + none + + Known Bugs + + Samples from the longer of the two frames are discarded. Consumers --------- @@ -389,8 +839,11 @@ Consumers Known Bugs + Does not work with any service that uses pipes! + If mlt crashes, you must reload the BlueDriver kernel module due to unreleased DMA buffers. + Needs an argument or property for multi-card address. ffmpeg @@ -402,7 +855,23 @@ Consumers Dependencies Known Bugs + libdv + + Description + + libdv dv producer. + + Constructor Argument + + string video_standard - "PAL" (default) or "NTSC" + + Initialisation Properties + Read Only Properties + Dependencies + Known Bugs + sdl + Description Simple DirectMedia Layer audio and video output module. @@ -432,3 +901,28 @@ Consumers NTSC handling needs tightening up - sdl:NTSC is the only valid constructor for NTSC playback at the moment. + westley + + Description + + Serialise the service network to XML. + + Constructor Argument + + resource - the name of a file in which to store the XML. + stdout is used if not supplied. + + Initialisation Properties + + string resource - same as above. + + Dependencies + + libxml2 + + Known Bugs + + Untested arbitrary nesting of multitracks and playlists. + Property "id" is generated as service type followed by number if + no property named "id" exists, but it fails to guarantee uniqueness. +