-Servers and Westley Docs
-------------------------
+Server Customisation
- One of the key features of MLT is its server capabilities. This feature
- allows you to pass westley documents seamlessly from one process to
- another and even to different computers on your network.
+Copyright (C) 2005-2009 Ushodaya Enterprises Limited
+Authors: Charles Yates <charles.yates@pandora.be>
+Last Revision: 2009-05-14
- The miracle playout server is one such example of an application which
- uses this functionality - you can build your own servers into your own
- processes with ease.
+
+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
+ * pushing documents
+ * handling pushed 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).
+
+
+PUSHING DOCUMENTS
+
+ This feature allows you to pass MLT XML documents seamlessly from one
+ process to another and even to different computers on your network.
A server process would be running as follows:
}
Typically, when you have an MLT object such as a producer or a playlist,
- you can send a westley representation of this to a running server with:
+ you can send a XML representation of this to a running server with:
- Conumser valerie( "valerie", "localhost:5250" );
- valerie.connect( producer );
- valerie.start( );
+ Consumer mvsp( "mvsp", "localhost:5250" );
+ mvsp.connect( producer );
+ mvsp.start( );
The effect of the push will be to append the producer on to the first
unit (u0).
- You can completely customise the miracle server - an example of this
- is shown below.
+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.
+++ /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 / commitdiff