X-Git-Url: http://research.m1stereo.tv/gitweb?a=blobdiff_plain;f=mlt%2B%2B%2FHOWTO;fp=mlt%2B%2B%2FHOWTO;h=830ab29b143b749650c82080d53d660a7f561427;hb=0caa0a91b0971439dfe00d0ed9bc05992b7dd609;hp=0000000000000000000000000000000000000000;hpb=e9506a0f7005ad5cc8821879ba78b8c42f3ec4bb;p=melted diff --git a/mlt++/HOWTO b/mlt++/HOWTO new file mode 100644 index 0000000..830ab29 --- /dev/null +++ b/mlt++/HOWTO @@ -0,0 +1,287 @@ +INTRODUCTION +------------ + + This document provides a brief tutorial on the use of the mlt++ wrapper + and bindings. + + +Hello World +----------- + + The mlt++ wrapper is a c++ wrapper for the mlt C library. As such, it + provides clean C++ access to the underlying library. + + An example of use is as follows: + + #include + #include + using namespace Mlt; + + int main( void ) + { + Factory::init( ); + Producer p( "pango:" ); + p.set( "text", "Hello World" ); + Consumer c( "sdl" ); + c.connect( p ); + c.start( ); + struct timespec tm = { 1, 0 }; + while ( !c.is_stopped( ) ) + nanosleep( &tm, NULL ); + return 0; + } + + This is a fairly typical example of use of mlt++ - create a 'producer' (an + object which produces 'frames'), create a 'consumer' (an object which consumes + frames), connect them together, start the consumer and wait until done (here + we just wait for the user to close the window). + + In this case, we construct a window as a consumer using the 'sdl' consumer + (SDL is a standard portable library which provides platform independent + access to accelerated video display and audio) and use the 'pango' + producer to generate frames with the words 'Hello World' (pango is a + library from the gtk toolkit). + + The main point of this example is to show that mlt uses existing libraries + to provide its functionality - this keeps the framework itself very small. + + Note that mlt is designed to be housed in GUI or server type applications - + typically, applications don't wait around for the consumer to be stopped in + the manner shown. + + TODO: Replace wait loop with an event. + + So far, we've introduced the Producer and Consumer mlt classes. We'll cover + each of these in more detail later in the tutorial, but for now, we'll + briefly cover the remaining classes. + + +Playlists +--------- + + Another simple class is the Playlist - this is direct extension of Producer + and it allows you to maintain a list of producer objects. + + As a simple example of the Playlist in action, we'll convert the example + above into an application which plays multiple video or audio files. + + #include + #include + using namespace Mlt; + + int main( int argc, char **argv ) + { + Factory::init( ); + Playlist list; + for ( int i = 1; i < argc; i ++ ) + { + Producer p( argv[i] ); + if ( p.is_valid( ) ) + list.append( p ); + } + Consumer c( "sdl" ); + c.connect( list ); + c.start( ); + struct timespec tm = { 1, 0 }; + while ( !c.is_stopped( ) ) + nanosleep( &tm, NULL ); + return 0; + } + + Now you can run the program as: + + ./player *.avi *.mp3 *.jpg etc + + In this case, we construct a playlist by simply appending producers to it. + Notice that although the scope of the Producer is limited to the inner + for loop, we can safely add it to the playlist - this is due to the fact + that all mlt objects maintain reference counts and no object is really + destroyed until all the references are gone. In this case, when the list + object goes out of scope, all the producers we created will automatically + be destroyed. + + +Filters +------- + + So far, we've shown how you can load and play media. We've given a brief + intro to the Playlist container, now it's time to start manipulating + things... + + For the next example, I'll add a 'watermark' to the video - a watermark + is used by broadcasters to brand the channel and normally consists of a + logo of some sort. We'll just use some black text on a partially + transparent red background. + + #include + #include + using namespace Mlt; + + int main( int argc, char **argv ) + { + Factory::init( ); + Playlist list; + for ( int i = 1; i < argc; i ++ ) + { + Producer p( argv[i] ); + if ( p.is_valid( ) ) + list.append( p ); + } + Filter f( "watermark", "pango:" ); + f.set( "producer.text", "MLT++" ); + f.set( "producer.fgcolour", "0x000000ff" ); + f.set( "producer.bgcolour", "0xff000080" ); + list.attach( f ); + Consumer c( "sdl" ); + c.connect( list ); + c.start( ); + struct timespec tm = { 1, 0 }; + while ( !c.is_stopped( ) ) + nanosleep( &tm, NULL ); + return 0; + } + + Notice that the watermark filter reuses the 'pango' producer we showed in the + first example. In fact, you could use any producer here - if you wanted to + use a graphic or a video, you would just construct the filter with a full path + to that as the second argument. + + We manipulate the filter using the set method - this method was also shown + in the first example. + + Finally, we attach the filter to the playlist. This ensure that all frames + that are obtained from the playlist are watermarked. + + +Tractor +------- + + A tractor is an object that allows the manipulation of multiple video and audio + tracks. + + Stepping away from the player example we've been tinkering with for a minute, + let's assume we want to do something like dubbing a video with some audio. This + a very trivial thing to do: + + Tractor *dub( char *video_file, char *audio_file ) + { + Tractor *tractor = new Tractor( ); + Producer video( video_file ); + Producer audio( audio_file ); + tractor->set_track( video, 0 ); + tractor->set_track( audio, 1 ); + return tractor; + } + + That's all that needs to be done - you can now connect the returned object to a + consumer, or add it to a playlist, or even apply it as a track to another tractor. + + +Transition +---------- + + Let's now assume we want to mix the audio between two tracks - to do this, we + need to introduce the concept of a transition. A transition in mlt is a service + which combines frames from two producers to produce a new frame. + + Tractor *mix( char *video_file, char *audio_file ) + { + Tractor *tractor = new Tractor( ); + Transition mix( "mix" ); + Producer video( video_file ); + Producer audio( audio_file ); + tractor.set_track( video, 0 ); + tractor.set_track( audio, 1 ); + tractor.field.plant_transition( mix, 0, 1 ); + return tractor; + } + + The tractor returned will now mix the audio from the original video and the audio. + + +That's All Folks... +------------------- + + And that, believe it or not, is a fairly complete summary of the classes you'll + typically be interfacing with in mlt++. Obviously, there's a little more to it + than this - a couple of intrisinc classes have been glossed over (notably, the + Properties and Service base classes). The next section will cover all of the + above, but in much more detail... + + +DIGGING DEEPER +-------------- + + The previous section was designed to give you a whistle stop tour through the major + framework classes. This section will take you through the scenic route. + + +Introducing Base Classes +------------------------ + + Services in mlt are the collective noun for Producers, Filters, Transitions and + Consumer. A Service is also the base class from which all of these classes + extend. It provides the basic connectivity which has been shown throughout the + examples in the previous section. + + Properties are the main way in which we communicate with the Services - + essentially, it provides get/set methods for named values. All services extend + Properties. + + +Properties +---------- + + Properties provide the general mechanism for communicating with Services - + through the Properties interface, we are able to manipulate and serialise + a services state. + + For example, to dump all the properties to stdout, you can use something + like: + + void dump( Properties &properties ) + { + for ( int i = 0; i < properties.count( ); i ++ ) + cout << Properties.get_name( i ) << " = " << Properties.get( i ) << endl; + } + + Note that the properties object handles type conversion, so the following + is acceptable: + + properties.set( "hello", "10.5" ); + int hello_int = properties.get_int( "hello" ); + double hello_double = properties.get_double( "hello" ); + + A couple of convenience methods are provide to examine or serialise property + objects. + + For example: + + properties.debug( ); + + will report all serialisable properties on stderr, in the form: + + Object: [ ref=1, in=0, out=0, track=0, u=75, v=150, _unique_id=15, + mlt_type=filter, mlt_service=sepia ] + + +Services +-------- + + Typically, all the services are constructed via the specific classes + constructor. Often, you will receive Service objects rather than their + specific type. In order to access the extended classes interface, + you will need to create a reference. + + For example, given an arbitrary Service object, you can determine its + type by using the type method - this will return a 'service_type' which + has values of producer_type, filter_type etc. Alternatively, you can + create a wrapping object and check on its validity. + + bool do_we_have_a_producer( Service &service ) + { + Producer producer( service ); + return producer.is_valid( ); + } + +