+++ /dev/null
-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.
-
-
-
projects / melted / blobdiff