From: Dan Dennedy Date: Sat, 16 May 2009 06:00:56 +0000 (-0700) Subject: Fix documents since the renaming. X-Git-Url: http://research.m1stereo.tv/gitweb?a=commitdiff_plain;h=093f38066a0b1b2df494492ddb2de20cac2de689;p=melted Fix documents since the renaming. Signed-off-by: Dan Dennedy --- diff --git a/NEWS b/NEWS index f96d4ad..b1c4348 100644 --- a/NEWS +++ b/NEWS @@ -1,171 +1,13 @@ -MLT Release Notes ------------------ +MLT Melted Release Notes +------------------------ -Version 0.3.8 +Version 0.4.0 -The recommended version of FFmpeg for use with this release is SVN r17923. - -This almost entirely a bugfix release to coincide with the Kdenlive 0.7.3 -release. See the ChangeLog (SVN log) for details. - -framework: -* added mlt_cache API -* improved doxygen documentation comments -* added some 15 fps profiles -* improved color property handling (support web-style '#' color value) -* add const qualifier to many string parameters - -modules: -* core: improved brightness filter -* core: added image crop filter -* frei0r: added support for producer/source plugins -* frei0r: added support for color parameters -* sdl: added window_background color property - - -Version 0.3.6 - -The recommended version of FFmpeg for use with this release is SVN r16849. - -This almost entirely a bugfix release to coincide with the Kdenlive 0.7.2 -release. See the ChangeLog (SVN log) for details. - -framework: -* added mlt_log logging API -* improved doxygen documentation comments - -avformat module: -* consumer: report list of muxers when f=list and codecs when acodec=list or - vcodec=list -* consumer: added support for an=1 or acodec=none and vn=1 or vcodec=none -* producer: list available demuxers and decoders when constructor arg is like - f-list[[,]acodec-list][[,]vcodec-list] - - -Version 0.3.4 - -The recommended version of FFmpeg for use with this release is SVN r16313. - -This almost entirely a bugfix release. See the ChangeLog (SVN log) for details. -There are a few notes: - -framework: -* improved doxygen documentation comments (work in progress) - published docs are at http://mltframework.org/doxygen/ - -avformat module: -* added support for AVOption parsing to producer -* added filter_swscale as alternative rescaler -* added recommended FFmpeg revision to configure option --help -* use recommended FFmpeg revision with --avformat-svn on release versions -* added configure option --avformat-no-codecs -* added configure option --avformat-no-filters - -misc: -* new profile atsc_1080i_50 -* added --disable-sse option to configure script -* improved build for OS X and x86-64 and improved handling of mmx/sse - - -Version 0.3.2 - -In addition to bug fixes detailed in the ChangeLog, here is a list of -enhancements. - -framework: -* deprecated mlt-config; use pkg-config instead -* added more HD profiles - -modules: -* sdl: added fullscreen property -* sox: sox v14.1.0 compatibility -* gtk: added force_reload property to producer_pixbuf -* frei0r: added support for YAML Tiny metadata -* frei0r: added keyframe support on double and boolean parameters -* oldfilm: added keyframe support for filter_vignette -* kdenlive: added filter_freeze - -inigo: -* added -version, -silent, and -progress options -* improved output of usage information -* removed realtime process scheduling - - -Version 0.3.0 - -framework: -* fix bugs with introduction of mlt_profile in v0.2.4 -* added versioning to libs -* remove module registry and add dynamic module loading: - added mlt_repository_register, mlt_repository_consumers, - mlt_repository_filters, mlt_repository_producers, mlt_repository_transitions -* new module metadata system based on YAML Tiny: - added mlt_repository_register_metadata, mlt_repository_metadata, - mlt_repository_languages, mlt_properties_is_sequence, - mlt_properties_parse_yaml, mlt_properties_serialise_yaml, and - added metaschema.yaml Kwalify schema file -* mlt_consumer: added threaded, non-lossy processing when real_time=-1 -* added autoclose property to mlt_playlist for sequential processing - of very large playlists (prevents resource exhaustion) -* mlt_factory_init now returns the global mlt_repository -* change mlt_repository_fetch to mlt_repository_create -* change mlt_factory_prefix to mlt_factory_directory -* added mlt_field_disconnect_service - -modules: -* move all modules from $datadir to $libdir -* new oldfilm module by Marco Gittler -* new frei0r module by Marco Gittler -* new dgraft module by Dan Dennedy for inverse telecine (not ready yet) -* avformat: added support for multi-threaded encoding and decoding -* consumer_avformat: added support for AVOption to support all ffmpeg options - using ffmpeg-style property names -* consumer_avformat: added support for dual pass encoding -* qimage: added support for Qt4 -* sox: added support for sox v14.0.0 -* transition_composite: added animatable geometry-type "pan" property to crop - and pan instead of automatic down-scale - -inigo: -* added -query option to lookup module metadata -* added -profile option and support for progress=1 for kdenlive - - -Version 0.2.4 - -* framework: new extensible profiles system to replace MLT_NORMALISATION -* module avformat: interlaced coding support for ffmpeg/libavcodec -* module avformat: build improvements for --avformat-svn -* new effectv module with BurningTV video filter -* module qimage: added support for psd, xcf and exr images -* numerous bugfixes - - -Version 0.2.3 - -* Addition of kdenlive module -* Support for ffmpeg from subversion -* Support for ffmpeg libswscale -* Copyright and license cleanup - - -Version 0.2.2 - -* Prepared specifically for the kdenlive 0.3 release. -* Contains some patches to support rgb24a output for the gdk-pixbuf and qimage - producers as well as some minor bugfixes. - - -Version 0.2.1 - -* Many improvements since initial releases due to development of Shotcut and - Jahshaka editing interfaces. - - -Version 0.1.1 - -* Minor modifications and bug fixes from the previous release. Better - ffmpeg/avformat integration and more reliable playback. +Separated from the main MLT framework project. +Renamed Miracle as melted. +Renamed Valerie as libmvcp. +Renamed Humperdink as mvcp-client. +Renamed Albino as mvcp-console. Version 0.1.0 diff --git a/README b/README index aaac6e2..f860e1b 100644 --- a/README +++ b/README @@ -1,12 +1,12 @@ -MLT/Miracle README ------------------- +MLT Melted README +----------------- Sponsored by Ushodaya Enterprises Limited Written by Charles Yates and Dan Dennedy MLT is a LGPL multimedia framework designed for television broadcasting, - and Miracle is a GPL multi-unit video playout server with realtime + and Melted is a GPL multi-unit video playout server with realtime effects. This document provides a quick reference for the minimal configuration, @@ -39,18 +39,6 @@ Compilation to compile the system. -Testing -------- - - To execute the mlt tools without installation, or to test a new version - on a system with an already installed mlt version, you should run: - - . setenv - - NB: This applies to your current shell only and it assumes a bash or - regular bourne shell is in use. - - Installation ------------ diff --git a/docs/TODO b/docs/TODO index ec188f5..d6d3a5e 100644 --- a/docs/TODO +++ b/docs/TODO @@ -1 +1 @@ -See http://www.mltframework.org/twiki/bin/view/MLT/ToDo +Testing since the refactoring for the 0.4.0 release. diff --git a/docs/install.txt b/docs/install.txt index b888322..85314e3 100644 --- a/docs/install.txt +++ b/docs/install.txt @@ -1,15 +1,15 @@ Installation Documentation -Copyright (C) 2004 Ushodaya Enterprises Limited +Copyright (C) 2004-2009 Ushodaya Enterprises Limited Author: Charles Yates -Last Revision: 2004-04-13 +Last Revision: 2009-05-15 INSTALL ------- - This document provides a description of the MLT project installation and - organisation. + This document provides a description of the MLT Melted project installation + and organisation. Directories @@ -17,83 +17,32 @@ Directories The directory heirarchy is defined as follows: - + demo - A selection of samples to show off capabilities. + docs - Location of all documentation + src - All project source is provided here - + framework - The mlt media framework + + melted - The server implementation (*) + + mvcp - Client API to access the server + + mvcp-console - A simple console (protocol level) example (*) + + mvcp-client - A terminal-based example client (*) + modules - All services are defined here - + avformat - libavformat dependent services - + bluefish - Bluefish dependent services (*) - + core - Independent MLT services - + dv - libdv dependent services - + fezzik - A giant (meta) service to load and normalise media - + gtk2 - pango and pixbuf dependent services - + mainconcept - mainconcept dependent services (*) - + normalize - audio normalisation functions (**) - + plus - throwaway silliness - + resample - libresample dependent services (**) - + sdl - SDL dependent services - + vorbis - vorbis dependenent services - + westley - Nice and clever XML services - + xine - Xine-derived sources (**) - + albino - A simple console (protocol level) example (**) - + inigo - A media playing test application (**) - + humperdink - A terminal-based example client (**) - + miracle - The server implementation (**) - + tests - Reserved for regression and unit tests - + valerie - Client API to access the server + + mvcp - MVCP consumer + + melted++ - C++ classes for melted and mvcp Additional subdirectories may be nested below those shown and should be documented in their parent. - (*) Not posted to CVS due to licensing issues. - (**) Contains GPL dependencies or code. + (*) Contains GPL dependencies or code. Dependencies ------------ - The MLT core is dependent on: + Melted is dependent on: + * The MLT framework library * a C99 compliant C compiler * posix threading * standard posix libraries - The MLT applications and libraries provided are all dependent on the core. - - The modules have the following dependencies: - - ----------- ---------------------------------------------------------- - MODULE DESCRIPTION - ----------- ---------------------------------------------------------- - avformat Provided from ffmpeg CVS and compiled as a shared library. - URL: http://ffmpeg.sf.net - ----------- ---------------------------------------------------------- - bluefish Bluefish hardware and software development kit - URL: http://www.bluefish444.com - ----------- ---------------------------------------------------------- - dv libdv 0.102 or later. - URL: http://libdv.sf.net - ----------- ---------------------------------------------------------- - gtk2 GTK2 and associated dependencies. - URL: http://www.gtk.org - ----------- ---------------------------------------------------------- - mainconcept Mainconcept MPEG and DVCPRO Release SDKs. - URL: http://www.mainconcept.com - ----------- ---------------------------------------------------------- - resample libsamplerate 0.15 or later - URL: http://www.mega-nerd.com/SRC/ (GPL) - ----------- ---------------------------------------------------------- - sdl SDL 1.2 or later. - URL: http://www.libsdl.org - ----------- ---------------------------------------------------------- - vorbis libvorbis 1.0.1 or later. - URL: http://www.vorbis.com/ - ----------- ---------------------------------------------------------- - westley libxml2 2.5 or later. - URL: http://www.xmlsoft.org/ - ----------- ---------------------------------------------------------- - Configuration ------------- @@ -123,65 +72,27 @@ Compilation a per directory template which must be provided by the developer. -Testing -------- - - To execute the mlt tools without installation, or to test a new version - on a system with an already installed mlt version, you should run: - - . setenv - - NB: This applies to your current shell only and it assumes sh or bash. - - Installation ------------ The install is triggered by running make install from the top level directory. - The framework produces a single shared object which is installed in - $prefix/lib/ and public header files which are installed in - $prefix/include/mlt/framework. - - Valerie produces a single shared object which is installed in + Mvcp produces a single shared object which is installed in $prefix/lib/ and public header which are installed in - $prefix/include/mlt/valerie. + $prefix/include/mlt/mvcp. - Miracle produces a single exectuable which is installed in + Melted produces a single exectuable which is installed in $prefix/bin/, a library in $prefix/lib and associated header files in - $prefix/include. + $prefix/include/mlt/melted. - The modules produce a shared object per module and update text files - containing a list of modules provided by this build. These are installed - in $prefix/share/mlt/modules. It is at the discretion of the module to - install additional support files. + The modules produce a shared object per module. These are installed + in $prefix/lib/mlt/modules. It is at the discretion of the module to + install additional support files in $prefix/share/mlt. - To allow the development of external components, mlt-config and scripts - are generated and installed in $prefix/bin. + To allow the development of external components, pkg-config config files + are generated and installed in $prefix/lib/pkgconfig. After install, only those modules listed are usable by the server. No module is loaded unless explicitly requested via server configuration or usage. - - External modules are also placed in this $prefix/share/mlt/modules, and the - installation of those must modify the text file accordingly before they - will be considered at runtime. - - -Development ------------ - - All compilation in the project has {top-level-dir}/src on the include path. - All headers are included as: - - #include - - All external modules have {prefix}/include/mlt on the include path. All - headers should also be included as: - - #include - - This allows migration of source between external and internal modules. - The configuration and Makefile template requirements will require - attention though. diff --git a/docs/libmvcp.txt b/docs/libmvcp.txt index 9a90c86..b7bd6a9 100644 --- a/docs/libmvcp.txt +++ b/docs/libmvcp.txt @@ -1,8 +1,8 @@ -Valerie API Documentation +MLT libmvcp API Documentation -Copyright (C) 2004 Ushodaya Enterprised Limited +Copyright (C) 2004-2009 Ushodaya Enterprised Limited Author: Charles Yates -Last Revision: 2004-03-20 +Last Revision: 2009-05-15 TABLE OF CONTENTS @@ -18,7 +18,7 @@ TABLE OF CONTENTS 1.4. Closing the Parser 2. The High Level Parser Wrapper 2.1. Connecting - 2.2. valerie_error_code + 2.2. mvcp_error_code 2.3. Using the High Level Wrapper 2.4. Obtaining Directory Contents 2.5. Obtaining the Node List @@ -30,7 +30,7 @@ TABLE OF CONTENTS 2.11. Examples 3. The Low Level Parser API 3.1. Executing a Command - 3.2. Interpreting valerie_response + 3.2. Interpreting mvcp_response 3.3. Accessing Unit Status APPENDIX A - COMPILATION AND LINKING APPENDIX B - COMPLETE HIGH LEVEL PARSER WRAPPER API LISTING @@ -41,14 +41,14 @@ TABLE OF CONTENTS 0. Overview ----------- - This document details how applications interface to DVCP functionality. + This document details how applications interface to MVCP functionality. 0.1. Intended Audience ---------------------- - This document draws heavily upon the DVCP design (1) and assumes a basic - knowledge of the functionality provided by the DVCP core. + This document draws heavily upon the MVCP design (1) and assumes a basic + knowledge of the functionality provided by the MVCP core. It is aimed at developers who wish to use or maintain the API. @@ -57,21 +57,21 @@ TABLE OF CONTENTS ---------------- The API is designed to allow client applications the ability to communicate - to a standalone miracle server or entirely embed the DVCP core in an + to a standalone melted server or entirely embed the MVCP core in an instance of a client application. The distinction between the two is defined by the construction of the 'parser'. - This 'parser' can be used to issue DVCP commands and receive responses and + This 'parser' can be used to issue MVCP commands and receive responses and a 'high level parser wrapper' is provided to simplify the usage and - decouple the application from the DVCP command set. + decouple the application from the MVCP command set. 1. Definition of a Parser ------------------------- - The parser provides a low level API which allows text DVCP commands to be + The parser provides a low level API which allows text MVCP commands to be executed with responses being returned to the caller. Commands and responses are ASCII formatted text. @@ -81,7 +81,7 @@ TABLE OF CONTENTS executes them. The remote parser is a network abstraction that forwards commands to a - miracle instance that hosts a local parser. + melted instance that hosts a local parser. 1.1. Construction of a Local Parser @@ -89,11 +89,11 @@ TABLE OF CONTENTS To construct a local parser you must have: - #include + #include and code to initialise the parser is as follows: - valerie_parser parser = miracle_parser_init_local( ); + mvcp_parser parser = melted_parser_init_local( ); See Appendix A for compilation and linking details. @@ -103,11 +103,11 @@ TABLE OF CONTENTS To construct a remote parser you must have: - #include + #include and code to initialise the parser is as follows: - valerie_parser parser = valerie_parser_init_remote( "server", port ); + mvcp_parser parser = mvcp_parser_init_remote( "server", port ); See Appendix A for compilation and linking details. @@ -136,20 +136,20 @@ TABLE OF CONTENTS Regardless of use, it is the constructors responsibility to close the parser before it goes out of scope. This is done via: - valerie_parser_close( parser ); + mvcp_parser_close( parser ); 2. The High Level Parser Wrapper -------------------------------- - The recommended way to access the parser, is via the valerie API. To use + The recommended way to access the parser, is via the mvcp API. To use this API, you must have: - #include + #include and code to construct the wrapper is: - valerie dv = valerie_init( parser ); + mvcp client = mvcp_init( parser ); Note that either remote or local parsers can be used here and there is no difference in usage, though some error returns will not be applicable to @@ -158,14 +158,14 @@ TABLE OF CONTENTS It is recommended that applications honour and deal with the error returns of both as this allows applications to interchange parsers. - Also note that valerie is not threadsafe, so you should not use the same + Also note that mvcp is not threadsafe, so you should not use the same structure in multiple threads. The correct solution to this is to create a - valerie per thread - you may safely use the same parser for each thread ie: + mvcp per thread - you may safely use the same parser for each thread ie: - /* valerie for the application */ - valerie dv = valerie_init( parser ); - /* valerie for the status handling thread. */ - valerie dv_status = valerie_init( parser ); + /* mvcp for the application */ + mvcp client = mvcp_init( parser ); + /* mvcp for the status handling thread. */ + mvcp client_status = mvcp_init( parser ); For the purposes of simplification, the remainder of this section assumes that a remote parser is in use. @@ -176,65 +176,65 @@ TABLE OF CONTENTS Once constructed, the next thing to do is 'connect': - valerie_error_code error = valerie_connect( dv ); + mvcp_error_code error = mvcp_connect( client ); This function call initialises the parser (ie: if it's remote, it establishes a connection to the server, or if it's local, it initialises the state of the units and supporting objects). - Note that if you have multiple valerie instances on the same parser you + Note that if you have multiple mvcp instances on the same parser you should only connect one of the instances. -2.2. valerie_error_code +2.2. mvcp_error_code ---------------------- - All but a couple of the functions that make up the valerie API return a - valerie_error_code. + All but a couple of the functions that make up the mvcp API return a + mvcp_error_code. These are defined as follows: - valerie_ok = 0, - valerie_malloc_failed, - valerie_unknown_error, - valerie_no_response, - valerie_invalid_command, - valerie_server_timeout, - valerie_missing_argument, - valerie_server_unavailable, - valerie_unit_creation_failed, - valerie_unit_unavailable, - valerie_invalid_file, - valerie_invalid_position - - In most cases, it is sufficient to check on a return of valerie_ok. + mvcp_ok = 0, + mvcp_malloc_failed, + mvcp_unknown_error, + mvcp_no_response, + mvcp_invalid_command, + mvcp_server_timeout, + mvcp_missing_argument, + mvcp_server_unavailable, + mvcp_unit_creation_failed, + mvcp_unit_unavailable, + mvcp_invalid_file, + mvcp_invalid_position + + In most cases, it is sufficient to check on a return of mvcp_ok. To obtain a textual description of a particular error, you can use: - char *valerie_error_description( valerie_error_code ); + char *mvcp_error_description( mvcp_error_code ); 2.3. Using the High Level Wrapper --------------------------------- - The following code snippet assumes that dv is an initialised and connected - valerie structure: + The following code snippet assumes that client is an initialised and connected + mvcp structure: - valerie_error_code error = valerie_unit_play( dv, 0 ); - if ( error == valerie_ok ) + mvcp_error_code error = mvcp_unit_play( client, 0 ); + if ( error == mvcp_ok ) fprintf( stderr, "Unit 0 is now playing\n" ); else fprintf( stderr, "Play on unit 0 failed: %s\n", - valerie_error_description( error ) ); + mvcp_error_description( error ) ); - The complete interface to valerie is listed in Appendix B of this document. + The complete interface to mvcp is listed in Appendix B of this document. 2.4. Obtaining Directory Contents -------------------------------- To obtain a list of files and subdirectories in a given directory relative - to the ROOT property of the server, DVCP provides the CLS command. + to the ROOT property of the server, MVCP provides the CLS command. A valid execution of CLS would be something like: @@ -253,23 +253,23 @@ TABLE OF CONTENTS of a subdirectory and the 3rd and 4th line lists two files that happen to exist in the directory. - valerie provides a high level view on this which automatically parses the - response from the server correctly via the valerie_dir structures and + mvcp provides a high level view on this which automatically parses the + response from the server correctly via the mvcp_dir structures and related functions. An example of use is as follows: - valerie_dir dir = valerie_dir_init( dv, "/Stuff" ); - valerie_error_code error = valerie_dir_get_error_code( dir ); - if ( error == valerie_ok ) + mvcp_dir dir = mvcp_dir_init( client, "/Stuff" ); + mvcp_error_code error = mvcp_dir_get_error_code( dir ); + if ( error == mvcp_ok ) { - if ( valerie_dir_count( dir ) > 0 ) + if ( mvcp_dir_count( dir ) > 0 ) { - valerie_dir_entry_t entry; + mvcp_dir_entry_t entry; int index = 0; - for ( index = 0; index < valerie_dir_count( dir ); index ++ ) + for ( index = 0; index < mvcp_dir_count( dir ); index ++ ) { - valerie_dir_get( dir, index, &entry ); + mvcp_dir_get( dir, index, &entry ); if ( entry.dir ) printf( "<%s>\n", entry.name ); else @@ -284,15 +284,15 @@ TABLE OF CONTENTS else { fprintf( stderr, "Directory listing failed: %s\n", - valerie_error_description( error ) ); + mvcp_error_description( error ) ); } - valerie_dir_close( dir ); + mvcp_dir_close( dir ); Note that entry.name provides the name of the file or directory without the directory prefix. As a convenience, entry.full provides the prefixed name, so you could subsequently use: - error = valerie_unit_load( dv, 0, entry.full ); + error = mvcp_unit_load( client, 0, entry.full ); to load unit 0 with an entry. @@ -300,12 +300,12 @@ TABLE OF CONTENTS 2.5. Obtaining the Node List ---------------------------- - Currently not defined by miracle. + Currently not defined by melted. 2.6. Obtaining the Unit List ---------------------------- - To obtain a list of defined units, DVCP provides the ULS command. + To obtain a list of defined units, MVCP provides the ULS command. A valid execution of ULS would be: @@ -321,23 +321,23 @@ TABLE OF CONTENTS The fields of each record in the response dictate unit, node, mlt consumer and online status respectively. - valerie provides a high level view on this which automatically parses the - response from the server correctly via the valerie_units structures and + mvcp provides a high level view on this which automatically parses the + response from the server correctly via the mvcp_units structures and related functions. An example of use is as follows: - valerie_units units = valerie_units_init( dv ); - valerie_error_code error = valerie_units_get_error_code( units ); - if ( error == valerie_ok ) + mvcp_units units = mvcp_units_init( client ); + mvcp_error_code error = mvcp_units_get_error_code( units ); + if ( error == mvcp_ok ) { - if ( valerie_units_count( units ) > 0 ) + if ( mvcp_units_count( units ) > 0 ) { - valerie_unit_entry_t entry; + mvcp_unit_entry_t entry; int index = 0; - for ( index = 0; index < valerie_units_count( units ); index ++ ) + for ( index = 0; index < mvcp_units_count( units ); index ++ ) { - valerie_units_get( units, index, &entry ); + mvcp_units_get( units, index, &entry ); printf( "U%d %02d %s %s\n", entry.unit, entry.node, @@ -353,9 +353,9 @@ TABLE OF CONTENTS else { fprintf( stderr, "Unit listing failed: %s\n", - valerie_error_description( error ) ); + mvcp_error_description( error ) ); } - valerie_units_close( units ); + mvcp_units_close( units ); 2.7. Unit Status Information @@ -363,7 +363,7 @@ TABLE OF CONTENTS There are two methods for a client to obtain unit status information. - The first is via the DVCP USTA command, which would normally be accessed + The first is via the MVCP USTA command, which would normally be accessed via: USTA U0 @@ -396,12 +396,12 @@ TABLE OF CONTENTS * Playlist generation * Clip index - Again, valerie provides a high level means for obtaining this via the - valerie_unit_status function and valerie_status structures: + Again, mvcp provides a high level means for obtaining this via the + mvcp_unit_status function and mvcp_status structures: - valerie_status_t status; - valerie_error_code error = valerie_unit_status( dv, 0, &status ); - if ( error == valerie_ok ) + mvcp_status_t status; + mvcp_error_code error = mvcp_unit_status( client, 0, &status ); + if ( error == mvcp_ok ) { switch( status.status ) { @@ -433,32 +433,32 @@ TABLE OF CONTENTS else { fprintf( stderr, "Unit status failed: %s\n", - valerie_error_description( error ) ); + mvcp_error_description( error ) ); } The second approach for obtaining a units status is via automatic notification. - This is done via the valerie_notifier API. To obtain the notifier from the + This is done via the mvcp_notifier API. To obtain the notifier from the high level API, you can use: - valerie_notifier notifier = valerie_get_notifier( dv ); + mvcp_notifier notifier = mvcp_get_notifier( client ); To obtain the last status associated to a unit, you can use: int unit = 1; - valerie_status_t status; - valerie_notifier_get( notifier, &status, unit ); + mvcp_status_t status; + mvcp_notifier_get( notifier, &status, unit ); To wait for the next status from any unit, you can use: - valerie_notifier_wait( notifier, &status ); + mvcp_notifier_wait( notifier, &status ); If you wish to trigger the action associated to your applications wait handling of a particular unit, you can use: - valerie_notifier_get( notifier, &status, unit ); - valerie_notifier_put( notifier, &status ); + mvcp_notifier_get( notifier, &status, unit ); + mvcp_notifier_put( notifier, &status ); See Examples below for details on this. @@ -523,20 +523,20 @@ TABLE OF CONTENTS * set in/out points allows you to modify clip in and out points Backward compatability has been maintained by the addition of a clip-aware - family of APIs which have the naming convention of valerie_unit_clip_*. + family of APIs which have the naming convention of mvcp_unit_clip_*. These are listed in Appendix B. The following shows an example of obtaining the clips queued on unit 0: - valerie_list list = valerie_list_init( dv, 0 ); - valerie_list_entry_t entry; + mvcp_list list = mvcp_list_init( client, 0 ); + mvcp_list_entry_t entry; int index; printf( "Generation = %d\n", list->generation ); - for ( index = 0; index < valerie_list_count( list ); index ++ ) + for ( index = 0; index < mvcp_list_count( list ); index ++ ) { - valerie_list_get( list, index, &entry ); + mvcp_list_get( list, index, &entry ); printf( "%d %s %d %d %d %d\n", entry.clip, entry.full, @@ -545,24 +545,24 @@ TABLE OF CONTENTS entry.max, entry.size ); } - valerie_list_close( list ); + mvcp_list_close( list ); To load a clip on unit 0: - valerie_unit_load( dv, 0, "/path/clip.dv" ); + mvcp_unit_load( client, 0, "/path/clip.dv" ); To append a clip on unit 0: - valerie_unit_append( dv, 0, "/path/clip.dv", -1, -1 ); + mvcp_unit_append( client, 0, "/path/clip.dv", -1, -1 ); Note that the last two arguments specify the in and out points of the clip with -1 denoting dfaults of the entirety of the file. To insert a clip at position 0 on unit 0, we can use the following: - valerie_unit_clip_insert( dv, 0, clip_absolute, 0, "/path/clip.dv", -1, -1 ); + mvcp_unit_clip_insert( client, 0, clip_absolute, 0, "/path/clip.dv", -1, -1 ); - The 3rd and 4th arguments here are common to all the valerie_unit_clip functions. + The 3rd and 4th arguments here are common to all the mvcp_unit_clip functions. They take the form of either [clip_absolute, n] to indicate an absolute clip index, or [clip_relative, n] to indicate a clip index relative to the currently playing clip. @@ -570,35 +570,35 @@ TABLE OF CONTENTS So, to insert a clip immediately before the currently playing clip, we can use: - valerie_unit_clip_insert( dv, 0, clip_relative, -1, "/path/clip.dv", -1, -1 ); + mvcp_unit_clip_insert( client, 0, clip_relative, -1, "/path/clip.dv", -1, -1 ); To move the current clip to the next position in the list: - valerie_unit_clip_move( dv, 0, clip_relative, 0, clip_relative, 1 ); + mvcp_unit_clip_move( client, 0, clip_relative, 0, clip_relative, 1 ); To remove a specific clip: - valerie_unit_clip_remove( dv, 0, clip_absolute, index ); + mvcp_unit_clip_remove( client, 0, clip_absolute, index ); To remove all but the currently playing clip: - valerie_unit_clean( dv, 0 ); + mvcp_unit_clean( client, 0 ); To goto the first frame in the first clip, you can use: - valerie_unit_clip_goto( dv, 0, clip_absolute, 0, 0 ); + mvcp_unit_clip_goto( client, 0, clip_absolute, 0, 0 ); To set the in and out points on the current clip: - valerie_unit_clip_set_in( dv, 0, clip_relative, 0, 0 ); - valerie_unit_clip_set_out( dv, 0, clip_relative, 0, 1000 ); + mvcp_unit_clip_set_in( client, 0, clip_relative, 0, 0 ); + mvcp_unit_clip_set_out( client, 0, clip_relative, 0, 1000 ); A more complete example of use of the server side can queuing can be found at: http://users.pandora.be/acp/rugen - The demo client provided with valerie is used for retaining backward + The demo client provided with mvcp is used for retaining backward compatability with the client side queuing API. @@ -610,33 +610,34 @@ TABLE OF CONTENTS The methods are provided via a pair of high level methods: - valerie_error_code error = valerie_execute( dv, 1024, "USTA U%d", unit ); - valerie_response response = valerie_get_last_response( dv ); + mvcp_error_code error = mvcp_execute( client, 1024, "USTA U%d", unit ); + mvcp_response response = mvcp_get_last_response( client ); int index = 0; - for ( index = 0; index < valerie_response_count( response ); index ++ ) - printf( "%d: %s\n", index, valerie_response_get_line( response,index ) ); + for ( index = 0; index < mvcp_response_count( response ); index ++ ) + printf( "%d: %s\n", index, mvcp_response_get_line( response,index ) ); - More details on the valerie_response structure can be found in section 3 of this + More details on the mvcp_response structure can be found in section 3 of this document. 2.10. Cleaning up ----------------- - Before the valerie and parser go out of scope, you need to run: + Before the mvcp and parser go out of scope, you need to run: - valerie_close( dv ); - valerie_parser_close( parser ); + mvcp_close( client ); + mvcp_parser_close( parser ); - Note that you should close all valerie instances before closing the parser. + Note that you should close all mvcp instances before closing the parser. 2.11. Examples -------------- - Please refer to albino and humperdink source for examples provided with - the project. Additional examples can be found via google with gdv1394 and - poldo. + Please refer to mvcp-console and mvcp-client source for examples provided with + the project. Rugen is another example: + + http://users.pandora.be/acp/rugen 3. The Low Level Parser API @@ -653,49 +654,49 @@ TABLE OF CONTENTS ------------------------ All commands can be executed via the single variable argument function - valerie_parser_executef and this function returns a valerie_response, ie: + mvcp_parser_executef and this function returns a mvcp_response, ie: - valerie_response response = valerie_parser_executef( parser, "CLS \"%s\"", dir ); + mvcp_response response = mvcp_parser_executef( parser, "CLS \"%s\"", dir ); Note that no carriage return/line feed is required (adding this is erroneous). It is the receiver of the response who is responsible for closing it. - valerie_response_close( response ); + mvcp_response_close( response ); -3.2. Interpreting valerie_response +3.2. Interpreting mvcp_response ----------------------------- The response received can be NULL, but it is safe to call: - int error = valerie_response_get_error_code( response ); + int error = mvcp_response_get_error_code( response ); which will return: * -1 if response is NULL, * -2 if there is no content to the response, - * 0 if the responses first line does not correspond to a valid DVCP response - * or the DVCP protocol error code returned on the first line of the response + * 0 if the responses first line does not correspond to a valid MVCP response + * or the MVCP protocol error code returned on the first line of the response - A simple use of a valerie_response structure is as follows: + A simple use of a mvcp_response structure is as follows: - valerie_response response = valerie_parser_executef( parser, "CLS \"%s\"", dir ); - int error = valerie_response_get_error_code( response ); + mvcp_response response = mvcp_parser_executef( parser, "CLS \"%s\"", dir ); + int error = mvcp_response_get_error_code( response ); if ( error >= 0 ) { int index = 0; - for ( index = 0; index < valerie_response_count( response ); index ++ ) - printf( "%3d: %s\n", index, valerie_response_get_line( response, index ) ); + for ( index = 0; index < mvcp_response_count( response ); index ++ ) + printf( "%3d: %s\n", index, mvcp_response_get_line( response, index ) ); } else { /* interpret error */ } - valerie_response_close( response ); + mvcp_response_close( response ); - Note that it is safe to call valerie_response_close regardless of the error + Note that it is safe to call mvcp_response_close regardless of the error condition indicated. @@ -703,8 +704,8 @@ TABLE OF CONTENTS -------------------------- As with the high level parser, there are two alternatives to obtain unit - status information - either via the USTA DVCP command or via the - valerie1394_notifier. + status information - either via the USTA MVCP command or via the + mvcp_notifier. The latter is the recommended way for any applications which wish to extract meaningful information from the status while avoiding the requirement to @@ -712,19 +713,19 @@ TABLE OF CONTENTS The notifier can be obtained by: - valerie_notifier notifier = valerie_parser_get_notifier( parser ); + mvcp_notifier notifier = mvcp_parser_get_notifier( parser ); The use of the notifier with the low level parser is identical to that dictated in Section 2 - to obtain the last status associated to a unit, you can use: int unit = 1; - valerie_status_t status; - valerie_notifier_get( notifier, &status, unit ); + mvcp_status_t status; + mvcp_notifier_get( notifier, &status, unit ); To wait for the next status from any unit, you can use: - valerie_notifier_wait( notifier, &status ); + mvcp_notifier_wait( notifier, &status ); APPENDIX A - COMPILATION AND LINKING @@ -738,11 +739,11 @@ APPENDIX A - COMPILATION AND LINKING Linking flags for a client are: - -L /lib/ -lvalerie + -L /lib/ -lmvcp Or for a local parser: - -L /lib/ -lmiracle + -L /lib/ -lmelted Note that you never need both libs. @@ -750,112 +751,112 @@ APPENDIX A - COMPILATION AND LINKING APPENDIX B - COMPLETE HIGH LEVEL PARSER WRAPPER API LISTING ----------------------------------------------------------- - valerie valerie_init( valerie_parser ); - - valerie_error_code valerie_connect( valerie ); - - valerie_error_code valerie_set( valerie, char *, char * ); - valerie_error_code valerie_get( valerie, char *, char *, int ); - - valerie_error_code valerie_unit_add( valerie, char * ); - valerie_error_code valerie_unit_load( valerie, int, char * ); - valerie_error_code valerie_unit_load_clipped( valerie,int,char *,long,long ); - valerie_error_code valerie_unit_load_back( valerie, int, char * ); - valerie_error_code valerie_unit_load_back_clipped(valerie,int,char *,long,long) - valerie_error_code valerie_unit_play( valerie, int ); - valerie_error_code valerie_unit_play_at_speed( valerie, int, int ); - valerie_error_code valerie_unit_stop( valerie, int ); - valerie_error_code valerie_unit_pause( valerie, int ); - valerie_error_code valerie_unit_rewind( valerie, int ); - valerie_error_code valerie_unit_fast_forward( valerie, int ); - valerie_error_code valerie_unit_step( valerie, int, int ); - valerie_error_code valerie_unit_goto( valerie, int, int ); - valerie_error_code valerie_unit_set_in( valerie, int, int ); - valerie_error_code valerie_unit_set_out( valerie, int, int ); - valerie_error_code valerie_unit_clear_in( valerie, int ); - valerie_error_code valerie_unit_clear_out( valerie, int ); - valerie_error_code valerie_unit_clear_in_out( valerie, int ); - valerie_error_code valerie_unit_set( valerie, int, char *, char * ); - valerie_error_code valerie_unit_get( valerie, int, char * ); - - valerie_error_code valerie_unit_status( valerie, int, valerie_status ); - valerie_notifier valerie_get_notifier( valerie ); - - valerie_dir valerie_dir_init( valerie, char * ); - valerie_error_code valerie_dir_get( valerie_dir, int, valerie_dir_entry ); - int valerie_dir_count( valerie_dir ); - void valerie_dir_close( valerie_dir ); - - valerie_nodes valerie_nodes_init( valerie ); - valerie_error_code valerie_nodes_get(valerie_nodes,int,valerie_node_entry); - int valerie_nodes_count( valerie_nodes ); - void valerie_nodes_close( valerie_nodes ); - - valerie_units valerie_units_init( valerie ); - valerie_error_code valerie_units_get(valerie_units,int,valerie_unit_entry); - int valerie_units_count( valerie_units ); - void valerie_units_close( valerie_units ); - - valerie_response valerie_get_last_response( valerie ); - - valerie_error_code valerie_execute( valerie, size_t, char *, ... ); - - void valerie_close( valerie ); + mvcp mvcp_init( mvcp_parser ); + + mvcp_error_code mvcp_connect( mvcp ); + + mvcp_error_code mvcp_set( mvcp, char *, char * ); + mvcp_error_code mvcp_get( mvcp, char *, char *, int ); + + mvcp_error_code mvcp_unit_add( mvcp, char * ); + mvcp_error_code mvcp_unit_load( mvcp, int, char * ); + mvcp_error_code mvcp_unit_load_clipped( mvcp,int,char *,long,long ); + mvcp_error_code mvcp_unit_load_back( mvcp, int, char * ); + mvcp_error_code mvcp_unit_load_back_clipped(mvcp,int,char *,long,long) + mvcp_error_code mvcp_unit_play( mvcp, int ); + mvcp_error_code mvcp_unit_play_at_speed( mvcp, int, int ); + mvcp_error_code mvcp_unit_stop( mvcp, int ); + mvcp_error_code mvcp_unit_pause( mvcp, int ); + mvcp_error_code mvcp_unit_rewind( mvcp, int ); + mvcp_error_code mvcp_unit_fast_forward( mvcp, int ); + mvcp_error_code mvcp_unit_step( mvcp, int, int ); + mvcp_error_code mvcp_unit_goto( mvcp, int, int ); + mvcp_error_code mvcp_unit_set_in( mvcp, int, int ); + mvcp_error_code mvcp_unit_set_out( mvcp, int, int ); + mvcp_error_code mvcp_unit_clear_in( mvcp, int ); + mvcp_error_code mvcp_unit_clear_out( mvcp, int ); + mvcp_error_code mvcp_unit_clear_in_out( mvcp, int ); + mvcp_error_code mvcp_unit_set( mvcp, int, char *, char * ); + mvcp_error_code mvcp_unit_get( mvcp, int, char * ); + + mvcp_error_code mvcp_unit_status( mvcp, int, mvcp_status ); + mvcp_notifier mvcp_get_notifier( mvcp ); + + mvcp_dir mvcp_dir_init( mvcp, char * ); + mvcp_error_code mvcp_dir_get( mvcp_dir, int, mvcp_dir_entry ); + int mvcp_dir_count( mvcp_dir ); + void mvcp_dir_close( mvcp_dir ); + + mvcp_nodes mvcp_nodes_init( mvcp ); + mvcp_error_code mvcp_nodes_get(mvcp_nodes,int,mvcp_node_entry); + int mvcp_nodes_count( mvcp_nodes ); + void mvcp_nodes_close( mvcp_nodes ); + + mvcp_units mvcp_units_init( mvcp ); + mvcp_error_code mvcp_units_get(mvcp_units,int,mvcp_unit_entry); + int mvcp_units_count( mvcp_units ); + void mvcp_units_close( mvcp_units ); + + mvcp_response mvcp_get_last_response( mvcp ); + + mvcp_error_code mvcp_execute( mvcp, size_t, char *, ... ); + + void mvcp_close( mvcp ); Notifier Functions ------------------ - void valerie_notifier_get( valerie_notifier, valerie_status, int ); - void valerie_notifier_put( valerie_notifier, valerie_status ); - int valerie_notifier_wait( valerie_notifier, valerie_status ); - void valerie_notifier_close( valerie_notifier ); + void mvcp_notifier_get( mvcp_notifier, mvcp_status, int ); + void mvcp_notifier_put( mvcp_notifier, mvcp_status ); + int mvcp_notifier_wait( mvcp_notifier, mvcp_status ); + void mvcp_notifier_close( mvcp_notifier ); Server Side Queuing ------------------- - valerie_list valerie_list_init( valerie, int ) - valerie_error_code valerie_list_get_error_code( valerie_list ) - valerie_error_code valerie_list_get( valerie_list, int, valerie_list_entry ) - int valerie_list_count( valerie_list ) - void valerie_list_close( valerie_list ) + mvcp_list mvcp_list_init( mvcp, int ) + mvcp_error_code mvcp_list_get_error_code( mvcp_list ) + mvcp_error_code mvcp_list_get( mvcp_list, int, mvcp_list_entry ) + int mvcp_list_count( mvcp_list ) + void mvcp_list_close( mvcp_list ) - valerie_error_code valerie_unit_clean( valerie dv, int unit ) - valerie_error_code valerie_unit_append( valerie dv, int unit, char *file, int in, int out ) - valerie_error_code valerie_unit_remove_current_clip( valerie dv, int unit ) + mvcp_error_code mvcp_unit_clean( mvcp client, int unit ) + mvcp_error_code mvcp_unit_append( mvcp client, int unit, char *file, int in, int out ) + mvcp_error_code mvcp_unit_remove_current_clip( mvcp client, int unit ) - valerie_error_code valerie_unit_clip_goto( valerie dv, int unit, valerie_clip_offset offset, int clip, int position ) - valerie_error_code valerie_unit_clip_set_in( valerie dv, int unit, valerie_clip_offset offset, int clip, int in ) - valerie_error_code valerie_unit_clip_set_out( valerie dv, int unit, valerie_clip_offset offset, int clip, int in ) - valerie_error_code valerie_unit_clip_move( valerie dv, int unit, valerie_clip_offset offset, int src, valerie_clip_offset offset, int dest ) - valerie_error_code valerie_unit_clip_remove( valerie dv, int unit, valerie_clip_offset offset, int clip ) - valerie_error_code valerie_unit_clip_insert( valerie dv, int unit, valerie_clip_offset offset, int clip, char *file, int in, int out ) + mvcp_error_code mvcp_unit_clip_goto( mvcp client, int unit, mvcp_clip_offset offset, int clip, int position ) + mvcp_error_code mvcp_unit_clip_set_in( mvcp client, int unit, mvcp_clip_offset offset, int clip, int in ) + mvcp_error_code mvcp_unit_clip_set_out( mvcp client, int unit, mvcp_clip_offset offset, int clip, int in ) + mvcp_error_code mvcp_unit_clip_move( mvcp client, int unit, mvcp_clip_offset offset, int src, mvcp_clip_offset offset, int dest ) + mvcp_error_code mvcp_unit_clip_remove( mvcp client, int unit, mvcp_clip_offset offset, int clip ) + mvcp_error_code mvcp_unit_clip_insert( mvcp client, int unit, mvcp_clip_offset offset, int clip, char *file, int in, int out ) APPENDIX C - COMPLETE LOW LEVEL PARSER API LISTING -------------------------------------------------- - valerie_response valerie_parser_connect( valerie_parser ); - valerie_response valerie_parser_execute( valerie_parser, char * ); - valerie_response valerie_parser_executef( valerie_parser, char *, ... ); - valerie_response valerie_parser_run( valerie_parser, char * ); - valerie_notifier valerie_parser_get_notifier( valerie_parser ); - void valerie_parser_close( valerie_parser ); - - valerie_response valerie_response_init( ); - valerie_response valerie_response_clone( valerie_response ); - int valerie_response_get_error_code( valerie_response ); - char *valerie_response_get_error_string( valerie_response ); - char *valerie_response_get_line( valerie_response, int ); - int valerie_response_count( valerie_response ); - void valerie_response_set_error( valerie_response, int, char * ); - int valerie_response_printf( valerie_response, size_t, char *, ... ); - int valerie_response_write( valerie_response, char *, int ); - void valerie_response_close( valerie_response ); + mvcp_response mvcp_parser_connect( mvcp_parser ); + mvcp_response mvcp_parser_execute( mvcp_parser, char * ); + mvcp_response mvcp_parser_executef( mvcp_parser, char *, ... ); + mvcp_response mvcp_parser_run( mvcp_parser, char * ); + mvcp_notifier mvcp_parser_get_notifier( mvcp_parser ); + void mvcp_parser_close( mvcp_parser ); + + mvcp_response mvcp_response_init( ); + mvcp_response mvcp_response_clone( mvcp_response ); + int mvcp_response_get_error_code( mvcp_response ); + char *mvcp_response_get_error_string( mvcp_response ); + char *mvcp_response_get_line( mvcp_response, int ); + int mvcp_response_count( mvcp_response ); + void mvcp_response_set_error( mvcp_response, int, char * ); + int mvcp_response_printf( mvcp_response, size_t, char *, ... ); + int mvcp_response_write( mvcp_response, char *, int ); + void mvcp_response_close( mvcp_response ); APPENDIX D - REFERENCES ----------------------- - (1) doc/dvcp.txt - DVCP protocol + (1) doc/mvcp.txt - MVCP protocol (2) doc/testing.txt - Test procedures diff --git a/docs/melted++.txt b/docs/melted++.txt index 711d901..2c784f3 100644 --- a/docs/melted++.txt +++ b/docs/melted++.txt @@ -7,26 +7,26 @@ Last Revision: 2009-05-14 INTRODUCTION - This document describes how miracle can be customised. The emphasis is on + This document describes how melted 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. + 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: + The most basic custom server exposes the entire MVCP protocol and is roughly + equivalent to the melted server iteself, but in this case, it lacks the + initialisation from /etc/melted.conf and the port is hardcoded to 5290: #include using namespace std; - #include + #include using namespace Mlt; int main( int argc, char **argv ) { - Miracle server( "miracle++", 5290 ); + Melted server( "melted++", 5290 ); if ( server.start( ) ) { server.execute( "uadd sdl" ); @@ -42,9 +42,9 @@ THE BASIC CUSTOM SERVER 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. + specified via the MVCP protocol. - To specify initial DVCP commands from /etc/miracle.conf, it is sufficient to + To specify initial MVCP commands from /etc/melted.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 @@ -55,7 +55,7 @@ CUSTOMISATION This document focusses on the following areas of customisation: - * the Miracle server class + * the Melted server class * extending the command set * accessing the units * the Response object @@ -64,15 +64,15 @@ CUSTOMISATION * accessiving events -THE MIRACLE SERVER CLASS +THE MELTED SERVER CLASS The full public interface of the server is as follows: - class Miracle : public Properties + class Melted : public Properties { public: - Miracle( char *name, int port = 5290, char *config = NULL ); - virtual ~Miracle( ); + Melted( char *name, int port = 5290, char *config = NULL ); + virtual ~Melted( ); mlt_properties get_properties( ); bool start( ); bool is_running( ); @@ -99,29 +99,29 @@ EXTENDING THE COMMAND SET #include using namespace std; - #include + #include #include using namespace Mlt; class Custom : - public Miracle + public Melted { public: Custom( char *name = "Custom", int port = 5290, char *config = NULL ) : - Miracle( name, port, config ) + Melted( name, port, config ) { } Response *execute( char *command ) { cerr << "command = " << command << endl; - return Miracle::execute( command ); + return Melted::execute( command ); } }; int main( int argc, char **argv ) { - Custom server( "miracle++", 5290 ); + Custom server( "melted++", 5290 ); if ( server.start( ) ) { server.execute( "uadd sdl" ); @@ -142,7 +142,7 @@ EXTENDING THE COMMAND SET (5) Starting server on 5290. command = uadd sdl - (5) miracle++ version 0.0.1 listening on port 5290 + (5) melted++ version 0.0.1 listening on port 5290 command = play u0 (7) Received signal 2 - shutting down. @@ -167,10 +167,10 @@ ACCESSING UNIT PROPERTIES unit( i ++ )->debug( ); return new Response( 200, "Diagnostics output" ); } - return Miracle::execute( command ); + return Melted::execute( command ); } - When this runs and you send a 'debug' command via DVCP, the server will output + When this runs and you send a 'debug' command via MVCP, the server will output some information on stderr, like: (5) Starting server on 5290. @@ -185,11 +185,11 @@ ACCESSING UNIT PROPERTIES 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 + 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 + than can be carried out over the MVCP protocol - for example, you can attach filters apply mixes/transitions between neighbouring cuts or carry out specific operations on cuts. @@ -218,7 +218,7 @@ THE RESPONSE OBJECT response->write( output.str( ).c_str( ) ); } } - return response == NULL ? Miracle::execute( command ) : response; + return response == NULL ? Melted::execute( command ) : response; } Now when you connect to the server via a telnet session, you can access the @@ -255,32 +255,32 @@ PUSHING DOCUMENTS A server process would be running as follows: - #include + #include using namespace Mlt; int main( void ) { - Miracle miracle( "miracle", 5250 ); - miracle.start( ); - miracle.execute( "uadd sdl" ); - miracle.execute( "play u0" ); - miracle.wait_for_shutdown( ); + Melted melted( "melted++", 5250 ); + melted.start( ); + melted.execute( "uadd sdl" ); + melted.execute( "play u0" ); + melted.wait_for_shutdown( ); return 0; } Typically, when you have an MLT object such as a producer or a playlist, you can send a XML representation of this to a running server with: - Consumer mvsp( "mvsp", "localhost:5250" ); - mvsp.connect( producer ); - mvsp.start( ); + Consumer mvcp( "mvcp", "localhost:5250" ); + mvcp.connect( producer ); + mvcp.start( ); The effect of the push will be to append the producer on to the first unit (u0). HANDLING PUSHED DOCUMENTS - The custom class receives PUSH'd westley either via the received or push + The custom class receives PUSH'd MLT XML either via the received or push method. The default handling is to simply append a pushed document on to the end of @@ -289,7 +289,7 @@ HANDLING PUSHED DOCUMENTS You can test this in the server defined above from the command line, for example: - $ inigo noise: -consumer valerie:localhost:5290 + $ melt noise: -consumer mvcp: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 @@ -329,11 +329,11 @@ HANDLING PUSHED DOCUMENTS Response *received( char *command, char *document ) { cerr << document; - Producer producer( "westley-xml", document ); + Producer producer( "xml-string", document ); return push( command, &producer ); } - When you push your videos in to the server via the inigo command above (or + When you push your videos in to the server via the melt 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 @@ -347,7 +347,7 @@ OTHER MANIPULATIONS 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 + Typically, shotcut and melt 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: @@ -387,12 +387,12 @@ EVENT HANDLING on 'consumer-frame-render' - this event is fired immediately before a frame is rendered. - See example in test/server.cpp + See example in src/examples/server.cpp -DISABLING DVCP +DISABLING MVCP - In some cases, it is desirable to fully disable the entire DVCP command set + In some cases, it is desirable to fully disable the entire MVCP 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 diff --git a/docs/mvcp.txt b/docs/mvcp.txt index 18da20f..2fe0e17 100644 --- a/docs/mvcp.txt +++ b/docs/mvcp.txt @@ -1,14 +1,14 @@ -Miracle Control Protocol (DVCP) Reference Documentation +MLT Video Control Protocol (MVCP) Reference Documentation -Copyright (C) 2004 Ushodaya Enterprised Limited +Copyright (C) 2004-2009 Ushodaya Enterprised Limited Author: Dan Dennedy -Last Revision: 2004-03-20 +Last Revision: 2009-05-15 General Format -------------- - DVCP is an ASCII-based request/response TCP protocol much like FTP and - inspired by the SGI MVCP (Multiport Video Computer Protocol). Each + MVCP is an ASCII-based request/response TCP protocol much like FTP and + inspired by the SGI MVCP [1] (Multiport Video Computer Protocol). Each command is three to eight characters long followed by zero or more arguments. Every item (command or argument) in the request is delimited by a space and terminated with a new line. Arguments that contain spaces @@ -16,6 +16,8 @@ General Format a line feed optionally preceeded by a carriage return. There are no request header lines or body. + [1] http://techpubs.sgi.com/library/tpl/cgi-bin/getdoc.cgi?coll=0650&db=bks&fname=/SGI_EndUser/MSB3xx_UG/ch09.html + Response Codes -------------- @@ -56,8 +58,8 @@ Response Codes Establishing a Connection ------------------------- - One can connect to the miracle server using telnet or a custom client, - preferrably one developed using the valerie client API. The default port + One can connect to the melted server using telnet or a custom client, + preferrably one developed using the libmvcp client API. The default port is 5250. Connections can be broken at will or use the BYE command to request the server to terminate the connection. @@ -68,7 +70,7 @@ General Command Information All commands are case insensitive. Arguments may or may not be case sensitive. There are two categories of commands: global and unit. Global commands operate at the server level. Unit commands address a specific - unit. miracle is a multi-unit system. Units are named as U? where ? + unit. melted is a multi-unit system. Units are named as U? where ? is the unit number, for example, U0. As units are added to the server, the unit number increases; the first unit is U0. @@ -131,14 +133,14 @@ STATUS Unit Management - The following global commands manage the DV units within the server. + The following global commands manage the playout units within the server. Currently there is a maximum of four units, and units can not be removed. Each unit may be in an online or offline state. Offline units can not be used, and any unit commands issued against an offline unit results in a 403 response. NLS - * NOT IMPLEMENTED IN MIRACLE YET * + * NOT IMPLEMENTED IN MELTED YET * UADD mlt-consumer[:argument] @@ -156,7 +158,7 @@ ULS server containing the following columns: - unit name (one of U0, U1, U2, or U3) - mlt-consumer[:argument] from uadd - - 1394 node GUID (defunt - always 0 with miracle for now) + - 1394 node GUID (defunt - always 0 with melted for now) - online flag (1 = online, 0 = offline) SHUTDOWN @@ -213,7 +215,7 @@ LOAD {unit} {filename} [in out] Sets the current position to the first frame in the clip. Preface the filename with '!' to tell the disk reader thread to remove only duplicate frames from the tail of its buffer queue (from a previously loaded - and playing clip). Otherwise, miracle flushes all of its buffers upon LOAD + and playing clip). Otherwise, melted flushes all of its buffers upon LOAD to make the effect of LOAD instantaneous. The LOAD !, USET eof=pause, and extended USTA information can be used for client-side playlists (see the demo programs). @@ -333,7 +335,3 @@ XFER {unit} {target-unit} Transfer the unit's clip to the target unit. The clip inherently includes the in- and out-point information. The target unit's "points" configuration property is set to "use." - - - - diff --git a/docs/testing.txt b/docs/testing.txt index 2886989..8a7fb9a 100644 --- a/docs/testing.txt +++ b/docs/testing.txt @@ -1,11 +1,11 @@ -Miracle Test Procedure +Melted Test Procedure -Copyright (C) 2003 Ushodaya Enterprised Limited +Copyright (C) 2003-2009 Ushodaya Enterprised Limited Author: Dan Dennedy -Last Revision: 2004-03-20 +Last Revision: 2009-05-15 -NOTE: THIS DOCUMENT REQUIRES REVISION TO NEW, EXPECTED BEHAVIOR FROM MIRACLE. +NOTE: THIS DOCUMENT REQUIRES REVISION TO NEW, EXPECTED BEHAVIOR FROM MELTED. Tests are divided into 9 sections: @@ -51,7 +51,7 @@ resume the tests from that point onward - it is better to repeat from the beginning (but you can of course employ common sense in this situation). Before starting the final tests, please delete/backup your current -/etc/dv139d.conf file. This (more or less) ensures that tests are carried out +/etc/melted.conf file. This (more or less) ensures that tests are carried out for a virgin install. @@ -60,23 +60,23 @@ for a virgin install. Run these from the top level project directory -1.1.0 Start miracle in interactive mode: src/miracle/miracle -test ---> miracle starts interactively and reports: +1.1.0 Start melted in interactive mode: src/melted/melted -test +--> melted starts interactively and reports: (5) Starting server on 5250. -(5) miracle version 0.0.1 listening on port 5250 +(5) melted version 0.0.1 listening on port 5250 1.1.1 Stop the server by pressing Ctrl-C ---> miracle returns the following and returns control to the console: -(5) miracle version 0.0.1 server terminated. +--> melted returns the following and returns control to the console: +(5) melted version 0.0.1 server terminated. -1.2.2 Start miracle as a daemon: src/miracle/miracle +1.2.2 Start melted as a daemon: src/melted/melted --> control returns to the console -1.2.3 Verify miracle is running: ps ax ---> several miracle processes are running +1.2.3 Verify melted is running: ps ax +--> several melted processes are running -1.2.4 Verify successful miracle startup using syslog: sudo tail /var/log/syslog ---> miracle: miracle version 0.0.1 listening on port 5250 +1.2.4 Verify successful melted startup using syslog: sudo tail /var/log/syslog +--> melted: melted version 0.0.1 listening on port 5250 1.2.5 Verify connectivity on port 5250: telnet localhost 5250 --> 100 VTR Ready @@ -84,16 +84,16 @@ Run these from the top level project directory 1.2.6 Test clean disconnect: BYE --> Connection closed by foreign host. -1.2.7 Stop the daemon: killall miracle +1.2.7 Stop the daemon: killall melted --> no errors 1.2.8 Verify a clean server shutdown: sudo tail /var/log/syslog ---> miracle: shutdown complete. +--> melted: shutdown complete. -1.3.0 Start miracle on a different port: src/miracle/miracle -port 5260 +1.3.0 Start melted on a different port: src/melted/melted -port 5260 -1.3.1 Verify successful miracle startup using syslog: sudo tail /var/log/syslog ---> miracle: miracle version 0.0.1 listening on port 5260 +1.3.1 Verify successful melted startup using syslog: sudo tail /var/log/syslog +--> melted: melted version 0.0.1 listening on port 5260 1.3.2 Verify connectivity on port 5260: telnet localhost 5260 --> 100 VTR Ready @@ -101,21 +101,21 @@ Run these from the top level project directory 1.3.3 Test clean disconnect: BYE --> Connection closed by foreign host. -1.3.4 Stop the daemon: killall miracle +1.3.4 Stop the daemon: killall melted --> no errors 2. Unit Management ------------------ -Start the miracle server and connect to it with telnet or a protocol- -level client (albino). +Start the melted server and connect to it with telnet or a protocol- +level client (mvcp-client). -2.1 List the AV/C devices on the bus: NLS +2.1 List the playout devices on the host: NLS --> 201 OK ---> one or more lines listing devices with GUID in second column +--> one or more lines listing devices with an ID in second column -2.2 Add a device as a miracle unit: UADD {sdl, bluefish} +2.2 Add a device as a melted unit: UADD {sdl, bluefish} --> 201 OK --> U0 @@ -149,7 +149,7 @@ level client (albino). 3. Server Configuration ----------------------- -Start miracle if not already started from a previous test. +Start melted if not already started from a previous test. 3.1 Get the hard-coded default root property value: GET root --> 202 OK @@ -194,7 +194,7 @@ XXX --> 400 Unknown command 4. Simple Playback ------------------- -Start miracle or restart if already started. +Start melted or restart if already started. Add an online unit. Set the server root property if desired. @@ -252,7 +252,7 @@ Set the server root property if desired. 5. Multi-unit Playback ----------------------- -Start miracle or restart if already started. +Start melted or restart if already started. Add *2* online units. Set the server root property if desired. @@ -280,7 +280,7 @@ Set the server root property if desired. 6. Advanced Playback -------------------- -Start miracle or restart if already started. +Start melted or restart if already started. Add *2* online units. Set the server root property if desired. @@ -430,7 +430,7 @@ Transfer: 7. Unit Configuration --------------------- -Start miracle or restart if already started. +Start melted or restart if already started. Add an online unit. Set the server root property if desired. @@ -474,10 +474,10 @@ users are encouraged to test with multiple units online. It is assumed that a number of dv files are available for use in the servers ROOT directory - this document assumes that they are named test001.dv and up. -9.1.0 Start miracle in interactive mode and add a unit (all tests will assume U0) +9.1.0 Start melted in interactive mode and add a unit (all tests will assume U0) --> server started with unit 0 available -9.1.1 Obtain a miracle shell (via telnet or albino). +9.1.1 Obtain a melted shell (via telnet or mvcp-client). --> 100 VTR (if reported by the client) 9.1.2 Load a clip with LOAD U0 test001.dv and PAUSE U0