From: Brian Matherly Date: Mon, 3 Oct 2011 03:16:18 +0000 (-0500) Subject: Remove docs/TODO, docs/policies.txt, docs/services/txt. All that X-Git-Url: https://git.sesse.net/?a=commitdiff_plain;h=05850adcdb704377ad50ca6b039a175f41dbaff9;p=mlt Remove docs/TODO, docs/policies.txt, docs/services/txt. All that information is now available on the web site. --- diff --git a/README b/README index b753f645..beec33aa 100644 --- a/README +++ b/README @@ -10,8 +10,14 @@ MLT FRAMEWORK README effects. This document provides a quick reference for the minimal configuration, - build and installation of MLT. See the docs directory for usage and - development details. + build and installation of MLT. + + See the docs directory for usage details. + + See the website for development details: + http://www.mltframework.org/twiki/bin/view/MLT/Documentation + http://www.mltframework.org/twiki/bin/view/MLT/Contributing + http://www.mltframework.org/twiki/bin/view/MLT/ToDo Configuration diff --git a/docs/TODO b/docs/TODO deleted file mode 100644 index ec188f59..00000000 --- a/docs/TODO +++ /dev/null @@ -1 +0,0 @@ -See http://www.mltframework.org/twiki/bin/view/MLT/ToDo diff --git a/docs/policies.txt b/docs/policies.txt deleted file mode 100644 index 60ba1db5..00000000 --- a/docs/policies.txt +++ /dev/null @@ -1,64 +0,0 @@ -Open Source Development Policies and Procedures for MLT -by Dan Dennedy - -Policies --------- - -Any contribution to the "core" module must assign copyright to Ushodaya -Enterprises Limited because they need license control over that module. - -The framework and libmvsp client libraries are covered under LGPL. melted, -melt, melted-console, and melted-client applications are covered under GPL. Modules -should strive to be LGPL to make them available through the framework as LGPL. - -Comments in the framework and libmvsp header files must be C-style, not C++. - -Coding Style: -There are not a lot of rules, but we prefer brackets on their own line, -indents using tabs, liberal usage of spaces in statements and expressions, and -no hard line length. The code in src/framework serves as a good example. - -Commit messages must be prefaced with the name of the changed files. This makes -the Subversion log more useful as a ChangeLog. For example, - docs/policies.txt: added policy about commit message - -Increment the version number in ./configure, mlt.h, and melt.1 on the first -commit after a release as well as just prior to a new release. This way we can -track if someone is using an unreleased version from the source code repository. - -Do not write messages to stdout. stdout is reserved for writing streams that -can be redirected: e.g. raw DV in consumer_libdv. I recommended to use the -mlt_log API. For something quick and dirty, use stderr. - - -Procedures ----------- - -Update services.txt when you add or update a service. - -Setting Copyright on Appropriated Code: -You do not want to be accused of copying someone's code and changing copyright -or license without permission. The license is straightforward: you must retain -the original author's license unless you receive explicit permission. There are -a few ways to approach the copyright declaration depending upon the -intermingling and changes. If you heavily comingle original and new code or -lightly modifiy the original code, you can retain the original's copyright -including the years, and then add your copyright for the current year. If you -can separate the MLT integration from the core subroutines, then you can put -the core subroutines into a separate file with the original copyright and just -copyright the MLT integration code as your own. However, if you have heavily -modified the original code beyond nearly all recognition, you can copyright it -as your own and attribute the original author as inspiration. - -A producer should validate its input and return NULL on failure. - -A filter or transition should express the image format it wants before calling -mlt_frame_get_image(). It should expect to receive what it requested as long -as it is yuv422, rgb24, or rgb24a and you are using the imageconvert filter -(typically via the loader producer and its loader.ini file). - -Bug Reporting: -First preference is to use the SourceForge tracker: -http://sourceforge.net/tracker/?group_id=96039&atid=613414 -Second preference is in the mailing list: -mlt-devel@lists.sourceforge.net diff --git a/docs/services.txt b/docs/services.txt deleted file mode 100644 index 89ef0744..00000000 --- a/docs/services.txt +++ /dev/null @@ -1,1409 +0,0 @@ -Service Documentation - -Authors: Charles Yates - Dan Dennedy -Last Revision: 2009-05-08 - - -SERVICES --------- - - Services marked as "(Proprietary)" are not distributed with the LGPL - version of mlt. - -Producers ---------- - - avformat - - Description - - ffmpeg libavformat based producer for video and audio. - - Constructor Argument - - 'file' - a filename specification or URL in the form: - [{protocol}|{format}]:{resource}[?{format-parameter}[&{format-parameter}...]] - For example, video4linux:/dev/video1?width:320&height:240 - Note: on the bash command line, & must be escaped as '\&'. - Also, note the use of ':' instead of '=' for parameters. - Use 'ffmpeg -formats' to see a list of supported protocols - and formats. - - Details - - Format parameters only appear to be useful with 'video4linux' or - 'audio_device' formats. For 'video4linux' the parameters are - width, height, frame_rate, frame_rate_base, and standard (ntsc|pal). - For 'audio_device' the parameters are channels and sample_rate. - - 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 - - string resource - file location - 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 - - Known Bugs - - Audio sync discrepancy with some content. - Not all libavformat supported formats are seekable. - Fails to play beyond first frame of video of sources with PTS not - starting at 0 (video4linux). - - loader - - Description - - A friendly giant that likes to rhyme and throw rocks - - Constructor Argument - - 'file' - a filename specification: - [{mlt-service}:]{resource} | {mlt-service} - - can also be the name of a producer service that can - accept the resource specified post construction. - - 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 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. - - - colour - - Description - - A simple colour generator. - - Constructor Argument - - colour - A colour value is a hexadecimal representation of RGB plus - alpha channel as 0xrrggbbaa. - - Also colours can be the words: white, black, red, green, - or blue. - - The default colour is black. - - Initialisation Properties - - none - - Read Only Properties - - none - - Dependencies - - none - - Known Bugs - - none - - - libdv - - Description - - libdv based 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 - int length - duration of resource (in frames) - - Mutable Properties - - string quality - one of "best," "fast" or anything else chooses - medium. - - Dependencies - - libdv. - - Known Bugs - - DVCPRO is incorrectly identified as 16:9 aspect ratio. You must use - libdv from CVS or a post 0.101 release. - - noise - - Description - - White noise producer - - Constructor Argument - - none - - 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 - sample aspect ratio of video - int length - duration of resource (in frames) - - Dependencies - - none - - 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 from: - <, >, & -to- <, >, & - - Details - - Supplying a filename with extension ".txt" causes the loader - producer to load with pango. If the filename begins with "+" the - pango producer interprets the filename as pango text. This is a - shortcut to embed titles in melt commands. For MLT XML, it is - recommended that you embed the title text in the property value. - - Pango has builtin scaling. It will rescale the originally rendered - title to whatever the consumer requests. Therefore, it will lose - its aspect ratio if so requested, and it is up to the consumer to - request a proper width and height that maintains the image aspect. - - Initialisation Properties - - int in - in point - int out - out point - - Mutable Properties - - 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 from: - <, >, & -to- <, >, & - string fgcolour - an RGBA colour specification of the text - (i.e. 0xrrggbbaa) - string bgcolour - an RGBA colour of the background rectangle - string align - paragraph alignment: left, centre, right - - also, numbers 0, 1 and 2 can be used respectively. - 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 string in UTF-8 encoding (can contain - markup chars un-encoded) - string font - the default typeface to use when not using markup. - 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 - - string resource - the text/markup file or "pango" if no file. - int real_width - the original, unscaled width of the rendered title. - int real_height - the original, unscaled height of the title. - int width - the last requested scaled image width. - int height - the last requested scaled image height. - - Dependencies - - libpango-1.0, libpangoft2-1.0, libfreetype, libgdk_pixbuf-2.0, - libglib-2.0, libgobject-2.0, libgmodule-2.0, libfontconfig. - - Known Bugs - - The foreground and background Pango markup span attributes are not - supported. - Word wrapping is not supported. - - pixbuf - - Description - - A still graphics to video 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. - - If filename contains the string "2 channels. - - rescale - - Description - - Scale the producer video frame size to match the consumer. - This filter is designed for use as a normaliser for the loader producer. - - Constructor Argument - - None. - - Initialisation Properties - - int in - in point - int out - out point - - Mutable Properties - - 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 - - none - - Known Bugs - - none but... it only implements a nearest neighbour scaling - it is - used as the base class for the gtkrescale and mcrescale filters. - - resize - - Description - - Image scaling and padding and field order adjustment. - - Details - - Normally resize is used to pad the producer's - output to what the consumer has requested after an upstream rescale - filter first scales the image to maximise usage of the image area. - This filter also adjusts the field order to lower field first - if the frame property "top_field_first" has been set to 1. - Therefore, when done, it sets the top_field_first to 0. - This filter is automatically invoked by the loader as part of image - sample aspect ratio normalisation. - - 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 - - Assumes lower field first output. - - volume - - Description - - Adjust an audio stream's volume level - - based on the 'normalize' utility - - 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 (default: 'loader') - string composite.geometry - composite geometry - string composite.distort - control scaling - int in - in point - int out - out point - - Mutable Properties - - none - - Dependencies - - mlt core modules and optionally, loader - - Known Bugs - - none - -Transitions ------------ - - composite - - Description - - A key-framable alpha-channel compositor for two frames. - - Details - - Performs dissolves and luma wipes in addition to alpha compositing. - - By default, the aspect ratio of the B frame is respected and the - size portion of the geometry specification simply defines a - bounding rectangle. - - This performs field-based rendering unless the A frame property - "progressive" or "consumer_progressive" or the transition property - "progressive" is set to 1. - - Constructor Argument - - none[*] - - 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 'loader'. - - Read Only Properties - - 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. - string halign - when not distorting, set the horizontal alignment - of B within the geometry rectangle. - - one of: left (0), centre (1), or right (2). - - the default is left. - string valign - when not distorting, set the vertical alignment of - B within the geometry rectangle. - - one of: top (0), middle (1), or bottom (2). - - the default is top. - string luma - the luma map file name. If not supplied, a dissolve. - 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. - 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 - - Known Bugs - - Assumes lower field first during field rendering. - - luma - - Description - - A generic dissolve and wipe transition processor. - - Details - - luma 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 reads PGM files - up to 16 bits! Alternatively, it can use the first frame from any - producer that outputs yuv, but it will be limited to the luma - gamut of 220 values. - This performs field-based rendering unless the A frame property - "progressive" or "consumer_progressive" or the transition property - "progressive" is set to 1. - - Constructor Argument - - string resource - the luma map file name - either PGM or any other - producable video. - - If not supplied, a dissolve. - - 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 'loader'. - - 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 - - none - - Known Bugs - - Assumes lower field first output. - - 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. - - - region - - Description - - Apply zero or more filters to B frame as it is composited onto - a region of the A frame. The "shape" of the region can be defined - by the alpha channel of a third producer. - - Constructor Argument - - resource - a shape producer - - Initialisation Properties - - string resource - nothing is rectangle, "circle" is a pixbuf- - generated SVG circle, anything else is loaded by the factory. - string factory - the service that creates the shape producer. - - the default is 'loader'. - string filter[N] - one or more filters to apply. All filter - properties are passed using the same filter "key" - Any property starting with "composite." is passed to the - encapsulated composite transition. - - Read Only Properties - - none - - Dependencies - - transition_composite - - Known Bugs - - none - - -Consumers ---------- - - avformat - - Description - - Multiformat transcoding consumer. - - Constructor Argument - - string target - the filename to write to, e.g. test.mpeg. - - Initialisation Properties - - int buffer - the number of frames to buffer, minimum 1, default 25. - string rescale - a rescale method, see the Filters/rescale. - int progressive - indicates whether to use progressive or field- - based rendering, default 0 (off). - - Read Only Properties - - none - - Dependencies - - libavformat - - Known Bugs - - Plenty. - - libdv - - Description - - libdv dv producer. - - Constructor Argument - - string target - the filename to write to, e.g. /dev/dv1394. - - Initialisation Properties - - int buffer - the number of frames to buffer, minimum 1, default 25. - string rescale - a rescale method, see the Filters/rescale. - - Mutable Properties - - int progressive - indicates whether to use progressive or field- - based rendering, default 0 (off). - - Read Only Properties - - none - - Dependencies - - libdv - - Known Bugs - - none - - sdl - - Description - - Simple DirectMedia Layer audio and video output module. - - Constructor Argument - - string video_standard - "PAL" (default), "NTSC", or "WxH" - - Initialisation Properties - - int buffer - the number of frames to buffer, minimum 1, default 25. - string rescale - a rescale method, see the Filters/rescale. - - Hint: "none" works very good with SDL output. - - Mutable Properties - - double volume - audio level factor - int video_off - if 1, disable video output - int audio_off - if 1, disable audio output - 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 - - none - - Dependencies - - libSDL-1.2, libasound, libaudio, libXt, libX11, libXext, libSM, libICE - - Known Bugs - - none - - xml - - Description - - Serialise the service network to XML. - See docs/mlt-xml.txt for more information. - - Constructor Argument - - resource - the name of a file in which to store the XML. - - stdout is default. - - 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.