test not only if header frei0r.h exists, also use an item

[mlt-frei0r-support.git] / mlt++ / CUSTOMISING

Server Customisation

Copyright (C) 2005 Ushodaya Enterprises Limited
Authors: Charles Yates <charles.yates@pandora.be>
Last Revision: 2005-03-16


INTRODUCTION

        This document describes how miracle can be customised. The emphasis is on
        showing simple examples of various aspects of the servers capabilities 
        rather than on focussing on the MLT++ API.


THE BASIC CUSTOM SERVER

        The most basic custom server exposes the entire DVCP protocol and is roughly 
        equivalent to the miracle server iteself, but in this case, it lacks the 
        initialisation from /etc/miracle.conf and the port is hardcoded to 5290:

        #include <iostream.h>
        using namespace std;

        #include <MltMiracle.h>
        using namespace Mlt;
        
        int main( int argc, char **argv )
        {
                Miracle server( "miracle++", 5290 );
                if ( server.start( ) )
                {
                        server.execute( "uadd sdl" );
                        server.execute( "play u0" );
                        server.wait_for_shutdown( );
                }
                else
                {
                        cerr << "Failed to start server" << endl;
                }
                return 0;
        }

        Note that after the server is started, this example submits the hard coded
        commands specified - further units and property settings can of course be
        specified via the DVCP protocol.

        To specify initial DVCP commands from /etc/miracle.conf, it is sufficient to
        specify an additional argument in the server constructor.

        The wait_for_shutdown call is not required if the server is integrated in
        a user interface application.


CUSTOMISATION

        This document focusses on the following areas of customisation:

        * the Miracle server class
        * extending the command set
        * accessing the units
        * the Response object
        * handling pushed westley documents
        * accessiving events


THE MIRACLE SERVER CLASS

        The full public interface of the server is as follows:

        class Miracle : public Properties
        {
                public:
                        Miracle( char *name, int port = 5290, char *config = NULL );
                        virtual ~Miracle( );
                        mlt_properties get_properties( );
                        bool start( );
                        bool is_running( );
                        virtual Response *execute( char *command );
                        virtual Response *received( char *command, char *doc );
                        virtual Response *push( char *command, Service *service );
                        void wait_for_shutdown( );
                        static void log_level( int );
                        Properties *unit( int );
        };

        The focus of this document is on the 3 virtual methods (execute, received and
        push). Some further information is provided about the unit properties method
        and the types of functionality that it provides.


EXTENDING THE COMMAND SET

        The simplest customisation is carried out by overriding the the 'execute' 
        method - the following shows a simple example:

        #include <iostream.h>
        #include <string>
        #include <sstring>
        using namespace std;

        #include <MltMiracle.h>
        #include <MltResponse.h>
        using namespace Mlt;

        class Custom : 
                public Miracle
        {
                public:
                        Custom( char *name = "Custom", int port = 5290, char *config = NULL ) :
                                Miracle( name, port, config )
                        {
                        }

                        Response *execute( char *command )
                        {
                                cerr << "command = " << command << endl;
                                return Miracle::execute( command );
                        }
        };
        
        int main( int argc, char **argv )
        {
                Custom server( "miracle++", 5290 );
                if ( server.start( ) )
                {
                        server.execute( "uadd sdl" );
                        server.execute( "play u0" );
                        server.wait_for_shutdown( );
                }
                else
                {
                        cerr << "Failed to start server" << endl;
                }
                return 0;
        }

        All this does is output each command and pass control over to the original
        implementation. 

        When you execute this, you will see the following output:

        (5) Starting server on 5290.
        command = uadd sdl
        (5) miracle++ version 0.0.1 listening on port 5290
        command = play u0
        (7) Received signal 2 - shutting down.

        Note that all commands except the PUSH are passed through this method before 
        they are executed and this includes those coming from the main function itself. 


ACCESSING UNIT PROPERTIES

        A unit consists of two objects - a playlist and a consumer. Your custom 
        server can access these by obtaining the Properties object associated to a unit
        via the 'unit' method. 
        
        As a simple example we can replace our execute method above with the following:

                Response *execute( char *command )
                {
                        if ( !strcmp( command, "debug" ) )
                        {
                                int i = 0;
                                while( unit( i ) != NULL )
                                        unit( i ++ )->debug( );
                                return new Response( 200, "Diagnostics output" );
                        }
                        return Miracle::execute( command );
                }

        When this runs and you send a 'debug' command via DVCP, the server will output
        some information on stderr, like:

        (5) Starting server on 5290.
        (5) Server version 0.0.1 listening on port 5290
        (5) Connection established with localhost (7)
        Object: [ ref=3, unit=0, generation=0, constructor=sdl, id=sdl, arg=(nil), 
        consumer=0x80716a0, playlist=0x807f8a8, root=/, notifier=0x8087c28 ]
        (6) localhost "debug" 100

        You can extract the objects using:

                Playlist playlist( ( mlt_playlist )( unit( i )->get_data( "playlist" ) ) );
                Consumer consumer( ( mlt_consumer )( unit( i )->get_data( "consumer" ) ) );
        
        and use the standard MLT++ wrapping methods to interact with them or you can 
        bypass these and using the C API directly.

        Obviously, this opens a lot of possibilities for the types of editing operations
        than can be carried out over the DVCP protocol - for example, you can attach filters
        apply mixes/transitions between neighbouring cuts or carry out specific operations
        on cuts.


THE RESPONSE OBJECT

        The example above doesn't do anything particularly useful - in order to extend 
        things in more interesting ways, we should be able to carry information back to 
        the client. In the code above, we introduced the Response object to carry an 
        error code and a description - it can also be used to carry arbitrary large
        blocks of data.

                Response *execute( char *command )
                {
                        Response *response = NULL;
                        if ( !strcmp( command, "debug" ) )
                        {
                                response = new Response( 200, "Diagnostics output" );
                                for( int i = 0; unit( i ) != NULL; i ++ )
                                {
                                        Properties *properties = unit( i );
                                        stringstream output;
                                        output << string( "Unit " ) << i << endl;
                                        for ( int j = 0; j < properties->count( ); j ++ )
                                                output << properties->get_name( j ) << " = " << properties->get( j ) << endl;
                                        response->write( output.str( ).c_str( ) );
                                }
                        }
                        return response == NULL ? Miracle::execute( command ) : response;
                }

        Now when you connect to the server via a telnet session, you can access the 
        'debug' command as follows:

                $ telnet localhost 5290
                Trying 127.0.0.1...
                Connected to localhost (127.0.0.1).
                Escape character is '^]'.
                100 VTR Ready
                debug
                201 OK
                Unit 0
                unit = 0
                generation = 0
                constructor = sdl
                id = sdl
                arg =

        Note that the '200' return code specified is automatically promoted to a 201
        because of the multiple lines.

        Alternatively, you can invoke response->write as many times as you like - each
        string submitted is simply appended to the object in a similar way to writing
        to a file or socket. Note that the client doesn't receive anything until the
        response is returned from this method (ie: there's currently no support to 
        stream results back to the client).
        

HANDLING PUSHED DOCUMENTS

        The custom class receives PUSH'd westley either via the received or push 
        method. 

        The default handling is to simply append a pushed document on to the end of
        first unit 0.

        You can test this in the server defined above from the command line, for
        example:

        $ inigo noise: -consumer valerie:localhost:5290

        By default, the 'push' method is used - this means that the xml document 
        received is automatically deserialised by the server itself and then offered
        to the push method for handling - an example of this would be:

                Response *push( char *command, Service *service )
                {
                        Playlist playlist( ( mlt_playlist )( unit( 0 )->get_data( "playlist" ) ) );
                        Producer producer( *service );
                        if ( producer.is_valid( ) && playlist.is_valid( ) )
                        {
                                playlist.lock( );
                                playlist.clear( );
                                playlist.append( producer );
                                playlist.unlock( );
                                return new Response( 200, "OK" );
                        }
                        return new Response( 400, "Invalid" );
                }

        With this method, each service pushed into the server will automatically
        replace whatever is currently playing.

        Note that the 'received' method is not invoked by default - if you wish to
        receive the XML document and carry out any additional processing prior to
        processing, you should set the 'push-parser-off' property on the server to 1.
        This can be done by placing the following line in your classes constructor:

                set( "push-parser-off", 1 );

        When this property is set, the received method is used instead of the push - 
        in this scenario, your implementation is responsible for all handling
        of the document.

        To simulate this, you can try the following method:

                Response *received( char *command, char *document )
                {
                        cerr << document;
                        Producer producer( "westley-xml", document );
                        return push( command, &producer );
                }

        When you push your videos in to the server via the inigo command above (or 
        from other tools, such as those in the shotcut suite), you will see the xml 
        in the servers stderr output. If you need to carry out some operations on the 
        xml document (such as replacing low quality videos used in the editing process 
        with their original) the received mechanism is the one that you would want to 
        use.


OTHER MANIPULATIONS

        What you do with the received MLT Service is largely up to you. As shown above,
        you have flexibility in how the item is scheduled and you can carry out 
        manipulations on either the xml document and/or the deserialised producer.

        Typically, shotcut and inigo produce 'tractor' objects - these can be easily
        manipulated in the push method - for example, to remove a track from the 
        output, we could do something like:

                Response *push( char *command, Service *service )
                {
                        Playlist playlist( ( mlt_playlist )( unit( 0 )->get_data( "playlist" ) ) );
                        Tractor *tractor( *service );
                        if ( tractor.is_valid( ) && playlist.is_valid( ) )
                        {
                                // Remove track 2 (NB: tracks are indexed from 0 like everything else)
                                Producer *producer = tractor.track( 2 );
                                Playlist track( producer );

                                // If we have a valid track then hide video and audio
                                // This is a bit pattern - 1 is video, 2 is audio
                                if ( track.is_valid( ) )
                                        track.set( "hide", 3 );

                                // You need to delete the reference to the playlist producer here
                                delete producer;

                                // Play it
                                playlist.lock( );
                                playlist.clear( );
                                playlist.append( producer );
                                playlist.unlock( );
                                return new Response( 200, "OK" );
                        }
                        return new Response( 400, "Invalid" );
                }


EVENT HANDLING

        The MLT framework generates events which your custom server can use to do
        various runtime manipulations. For the purpose of this document, I'll focus
        on 'consumer-frame-render' - this event is fired immediately before a frame
        is rendered.

        See example in test/server.cpp


DISABLING DVCP

        In some cases, it is desirable to fully disable the entire DVCP command set
        and handle the PUSH in an application specific way (for example, the shotcut 
        applications all do this). The simplest way of doing this is to generate a
        response that signifies the rejection of the command. In this example, the 
        'shutdown' command is also handled:

                Response *execute( char *command )
                {
                        if ( !strcmp( command, "shutdown" ) )
                                exit( 0 );
                        return new Response( 400, "Invalid Command" );
                }
                
        If you use this method in the code above, your server does nothing - no units 
        are defined, so even a PUSH will be rejected.