X-Git-Url: http://research.m1stereo.tv/gitweb?a=blobdiff_plain;f=docs%2Fservices.txt;h=27864d3d79c4ed879af01daf5724e5f359c8163b;hb=42bd0aedb6d3d65bedb98479adcdbaeb326dfee9;hp=358861080508282e3037dc3e7aca2ae5efbdc6dd;hpb=0cf7dff156fe3c541eb5d668e317cc73b008c7b0;p=melted

diff --git a/docs/services.txt b/docs/services.txt
index 3588610..27864d3 100644
--- a/docs/services.txt
+++ b/docs/services.txt
@@ -1,13 +1,58 @@
 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.
+
+		Oddities
+
+			There seems to be a discrepancy between audio and video pts (time
+			stamps) which causes audio seeking to be unreliable in some cases.
+			If audio playback is broken, try adding discrepancy=3 as a
+			property.
+
+			Not sure of the exact reasons, but am investigating. 
+
+		Known Bugs
+
+			Fixed frame rate.
+			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.
+
 	ffmpeg
 
-		Description:
+		Description
 
 			Test case pipe based producer for video and audio.
 
-		Constructor argument:
+		Constructor Argument
 
 			'file'	- produce a/v from file
 			v4l		- produce a/v from video4linux and dsp device
@@ -24,13 +69,15 @@ 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
 
 		Read Only Properties
 
-			end_of_clip - holds 1 when input is exhausted
+			string resource - file or "v4l"
+			int end_of_clip - holds 1 when input is exhausted
 
 		Dependencies
 
@@ -38,29 +85,31 @@ Producers
 
 		Known Bugs
 
-			in/out point setting is broken.
+			in point setting is broken.
 
 			Implementation does not allow fast random access.
 
 	libdv
 
-		Description:
+		Description
 
 			libdv based decoder for video and audio.
 
-		Constructor argument:
+		Constructor Argument
 
 			'file'	- produce a/v from file
 
 		Initialisation Properties
 
-			string file - file location
-			timecode in - in point
-			timecode out - out point
+			int in - in point
+			int out - out point
 
 		Read Only Properties
 
-			double fps - output frames per second 
+			string resource - file location
+			double fps - output frames per second
+			double aspect_ratio - aspect ratio of video]
+			int length - duration of resource (in frames)
 
 		Dependencies
 
@@ -68,32 +117,747 @@ Producers
 
 		Known Bugs
 
-			'file' is not populated on properties?
+			None.
 
 	mcdv
+
+		Description
+
+			Mainconcept based dv decoder for video and audio.
+
+		Constructor Argument
+
+			'file'	- produce a/v from file
+
+		Initialisation Properties
+
+			int in - in point
+			int out - out point
+
+		Read Only Properties
+
+			string resource - file location
+			double fps - output frames per second
+			double aspect_ratio - aspect ratio of video
+			int length - duration of resource (in frames)
+
+		Dependencies
+
+			mainconcept dv sdk and libdv.
+			"dv_sdk" installed parallel to mlt.
+
+		Known Bugs
+
+			Can be problematic with source NTSC DV files? really? yes - try
+			playing pond.dv...
+
 	mcmpeg
+
+		Description
+
+			Mainconcept based mpeg decoder for video and audio.
+
+		Constructor Argument
+
+			'file'	- produce a/v from file
+
+		Initialisation Properties
+
+			int in - in point
+			int out - out point
+
+		Read Only Properties
+
+			string resource - file location
+			double fps - output frames per second
+			double aspect_ratio - aspect ratio of video
+
+		Dependencies
+
+			mainconcept mpeg sdk.
+			"mpeg_sdk_demo" installed parallel to mlt.
+
+		Known Bugs
+
+			None.
+
 	pango
+
+		Description
+
+			A title generator that uses the Pango international text layout
+			and Freetype2 font renderer.
+
+		Constructor Argument
+
+			string file - a text file containing Pango markup, see:
+			           http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
+			           - requires xml-like encoding special chars: <, >, & to &lt;, &gt;, &amp;
+
+		Initialisation Properties
+
+			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
+
+			string markup - a string containing Pango markup see:
+			                http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html
+			              - requires xml-like encoding special chars: <, >, & to &lt;, &gt;, &amp;
+
+			int fgcolor - an rgba color specification of the text (i.e. 0xrrggbbaa)
+			int bgcolor - an rgba color 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
+			string markup - see constructor argument
+			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
+
+			string resource - the text/markup file or "pango" if no file
+
+		Dependencies
+
+			libpango-1.0, libpangoft2-1.0, libfreetype, libgdk_pixbuf-2.0, libglib-2.0,
+			libgobject-2.0, libgmodule-2.0, libfontconfig
+
+		Known Bugs
+
+			no frame-alignment functionality
+
 	pixbuf
+
+		Description
+
+			A graphics overlay generator using gdk-pixbuf
+
+		Constructor Argument
+
+			'file' - The name of a graphics file loadable by
+			         a gdk-pixbuf loader. see /usr/lib/gdk-pixbuf/loaders
+			         definitely png, jpeg, tiff, pnm, and xpm
+			       - If "%" in filename, the filename is used with sprintf
+			         generate a filename from a counter for multi-file/flipbook animation.
+			         The file sequence ends when numeric discontinuity >100.
+			       - If filename contains "/.all.", suffix with an extension to load
+			         all pictures with matching extension from a directory
+
+		Initialisation Properties
+
+			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
+			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
+
+			string resource - file location
+
+		Dependencies
+
+			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
 -------
 
 	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
+		
+			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 color 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
+
+	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
+			
+		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
+
+		Dependencies
+
+			libgdk_pixbuf-2.0, libglib-2.0, libgobject-2.0, libgmodule-2.0
+
+		Known Bugs
+
+			none
 
 Transitions
 -----------
 
 	composite
+	
+		Description
+
+			An alpha-channel based compositor for two frames.
+			
+		Constructor Argument
+
+			mix - see below
+
+		Initialisation Properties
+			
+			int in - in point
+			int out - out point
+
+		Mutable Properties
+
+			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).
+			           - any negative value causes an automatic dissolve
+		
+		Read Only Properties
+
+			none
+		
+		Dependencies
+
+			none
+		
+		Known Bugs
+
+			Need to add field-based rendering.
+
+	luma
+	
+		Description
+
+			A generic dissolve and wipe transition processor. It gets its name
+			from how it uses a grayscale "map" file. As the luma value varies
+			over time, a threshold filter is applied to the map to determine
+			what parts of frame A vs. frame B to show. It only reads PGM
+			files, but it does handle 16 bit PGM. This performs field-based
+			rendering.
+		
+		Constructor Argument
+
+			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 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.
+			
+		Read Only Properties
+
+			none
+			
+		Dependencies
+
+			none
+			
+		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
+
+			mix - see below
+
+		Initalisation Properties
+
+			int in - in point
+			int out - out point
+
+		Mutable Properties
+
+			double mix - the mix level to apply to the second frame.
+			           - any negative value causes an automatic crossfade.
+
+		Read Only Properties
+
+			none
+
+		Dependencies
+
+			none
+
+		Known Bugs
+
+			Samples from the longer of the two frames are discarded.
 
 Consumers
 ---------
 
 	bluefish
+	
+		Description
+
+			BlueFish444 audio and video output module.
+		
+		Constructor Argument
+
+			string video_standard - "PAL" (default) or "NTSC"
+			
+		Initialisation Properties
+
+			int video_standard - 0 = PAL, 1 = NTSC
+			
+		Read Only Properties
+
+			none
+		
+		Dependencies
+
+			BlueVelvet SDK installed parallel to mlt in "bluefish."
+		
+		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
+	
+		Description
+		Constructor Argument
+		Initialisation Properties
+		Read Only Properties
+		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.
+			
+		Constructor Argument
+
+			string video_standard - "PAL" (default), "NTSC", or "WxH"
+			
+		Mutable Properties
+
+			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.
+			
+		Read Only Properties
+
+			none
+			
+		Dependencies
+
+			libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE
+		
+		Known Bugs
+
+			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.
+