+Framework Documentation
+
+Copyright (C) 2004 Ushodaya Enterprises Limited
+Author: Charles Yates <charles.yates@pandora.be>
+Last Revision: 2004-03-20
+
+
MLT FRAMEWORK
-------------
it provides a pluggable architecture for the inclusion of new audio/video
sources, filters, transitions and playback devices.
- The MLT framework provides the structure and utility functionality on which
+ The framework provides the structure and utility functionality on which
all of the MLT applications and services are defined.
On its own, the framework provides little more than 'abstract classes' and
A typical consumer requests MLT Frame objects from the producer, does
something with them and when finished with a frame, closes it.
- /\ A common confusion with the producer/consumer terminoligy used here is
+ /\ A common confusion with the producer/consumer terminology used here is
/!!\ that a consumer may 'produce' something. For example, the libdv consumer
\!!/ produces DV and the libdv producer seems to consume DV. However, the
\/ naming conventions refer only to producers and consumers of MLT Frames.
+------------------+------------------------------------+------------------+
|MLT_CONSUMER |The default consumer |"sdl" or other |
+------------------+------------------------------------+------------------+
+ |MLT_TEST_CARD |The default test card producer |any producer |
+ +------------------+------------------------------------+------------------+
These values are initialised from the environment variables of the same
name.
Let's assume that we're adapting the Hello World example, and wish to queue
a number of files for playout, ie:
- hello *.avi
+ hello *.avi
Instead of invoking mlt_factory_producer directly, we'll create a new
function called create_playlist. This function is responsible for creating
the playlist, creating each producer, appending to the playlist and ensuring
that all the producers are cleaned up when the playlist is destroyed. The
- last point is important - a close on the playlist won't explicitly these
+ last point is important - a close on the playlist won't explicitly close these
producers. In this example, we use unique "data" properties with destructors
to ensure closing.
int i = 0;
for ( i = 1; i < argc; i ++ )
{
- // Definie the unique key
+ // Define the unique key
char key[ 256 ];
// Create the producer
properties can be set as needed.
The additional argument in the filter connection is an important one as it
- dicates the 'track' on which the filter operates. For basic producers and
+ dictates the 'track' on which the filter operates. For basic producers and
playlists, there's only one track (0), and as you will see in the next
section, even multiple tracks have a single track output.
Multiple Tracks and Transitions:
- MLT's approach to mutliple tracks is governed by two requirements:
+ MLT's approach to multiple tracks is governed by two requirements:
1) The need for a consumer and producer to communicate with one another via
a single frame;
+------------------------------+
The overlapping areas of track 0 and 1 would (presumably) have some kind of
- transition - without a transition, the frames from a1 and a2 would be shown
- during the areas of overlap.
+ transition - without a transition, the frames from b1 and b2 would be shown
+ during the areas of overlap (ie: by default, the higher numbered track takes
+ precedence over the lower numbered track).
MLT has a multitrack object, but it is not a producer in the sense that it
can be connected directly to a consumer and everything will work correctly.
evenly, the correct frame is output and that we have 'producer like'
behaviour.
- Thus, a mulitrack is conceptually 'pulled' by a tractor as shown here:
+ Thus, a multitrack is conceptually 'pulled' by a tractor as shown here:
+----------+
|multitrack|
+----------+
With a combination of the two, we can now connect multitracks to consumers.
- The first non-test card will be retrieved and passed on.
+ The last non-test card will be retrieved and passed on.
The tracks can be producers, playlists, or even other tractors.
- Now we wish to insert filters and transitions between the mulitrack and the
+ Now we wish to insert filters and transitions between the multitrack and the
tractor. We can do this directly by inserting filters directly between the
tractor and the multitrack, but this involves a lot of connecting and
reconnecting left and right producers and consumers, and it seemed only fair
that we should be able to automate that process.
-
+
So in keeping with our agricultural theme, the concept of the 'field' was
born. We 'plant' filters and transitions in the field and the tractor pulls
the multitrack (think of a combine harvester :-)) over the field and
mlt_properties_set_position( properties, "in", 0 );
mlt_properties_set_position( properties, "out", length - 1 );
mlt_properties_set_position( properties, "length", length );
-
+ mlt_properties_set_int( properties, "a_track", 0 );
+ mlt_properties_set_int( properties, "b_track", 1 );
+
// Now set the properties on the transition
properties = mlt_transition_properties( transition );
mlt_properties_set_position( properties, "in", 0 );
SECTION 3 - STRUCTURE AND DESIGN
--------------------------------
-Class Heirachy:
+Class Hierarchy:
- The mlt framework consists of an OO class heirachy which consists of the
+ The mlt framework consists of an OO class hierarchy which consists of the
following public classes and abstractions:
mlt_properties
too.
Steps 6 and 7 demonstrate that the properties object handles deserialisation
- from strings. The string value of "50" is set, the integer value of 50 is
+ from strings. The string value of "0" is set, the integer value of 0 is
retrieved.
Steps 8 and 9 demonstrate that the properties object handles serialisation
+------------------+------------------------------------+------------------+
|samples |The samples of the audio | |
+------------------+------------------------------------+------------------+
- |aspect_ratio |The aspect ratio of the image |double |
+ |aspect_ratio |The sample aspect ratio of the image|double |
+------------------+------------------------------------+------------------+
|test_image |Used to indicate no image available |0 or 1 |
+------------------+------------------------------------+------------------+
|rescale.interp |Use this scale method for test image|"string" |
+------------------+------------------------------------+------------------+
- While most of these are mainly self explainatory, the normalised_width and
- normalised_height values require a little explaination. These are required
+ While most of these are mainly self explanatory, the normalised_width and
+ normalised_height values require a little explanation. These are required
to ensure that effects are consistently handled as PAL or NTSC, regardless
of the consumers or producers width/height image request.
void mlt_service_close( mlt_service this );
Typically, only direct descendents of services need invoke these methods and
- developers are encouraged to use those extensions when definining new
- services.
+ developers are encouraged to use those extensions when defining new services.
mlt_producer:
void mlt_playlist_close( mlt_playlist this );
mlt_tractor:
-
-
projects / mlt / blobdiff