mltpp/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.