--- /dev/null
+Miracle Control Protocol (DVCP) Reference Documentation
+
+Copyright (C) 2004 Ushodaya Enterprised Limited
+Author: Dan Dennedy <dan@dennedy.org>
+Last Revision: 2004-03-20
+
+
+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
+ 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
+ must be surrounded by double quotation marks. The new line must contain
+ a line feed optionally preceeded by a carriage return. There are no
+ request header lines or body.
+
+
+Response Codes
+--------------
+ Responses consist of a numeric result code followed by a space folowed
+ by a brief textual description of the result. No quoting is applied to
+ descriptions regardless if it contains spaces. The result codes are
+ grouped by the hundreds into general categories of responses. Anything
+ in the 200-299 range is considered a success and anything 300 and above
+ is an error or exception. Most responses do not contain a body except
+ some of the success results that report information and sometimes the
+ 500 Server Error returns specific information.
+
+ A 200 result code contains no body.
+ A 201 result code contains one or more lines in the body, and an empty
+ line terminates the response.
+ A 202 result code contains only a single response line in the body.
+
+ Errors in the 400 range indicate a normally handled error where the
+ command could not perform its action due to protocol syntax errors or
+ problems with validation of one or more of the arguments. This usually
+ indicates that the client is responsible for performing an illegal
+ request.
+
+ Errors in the 500 range indicate a server error or exception.
+
+ The following is a list of response codes and their descriptions:
+ 200 OK
+ 201 OK
+ 202 OK
+ 400 Unknown command
+ 401 Operation timed out
+ 402 Argument missing
+ 403 Unit not found
+ 404 Failed to locate or open clip
+ 405 Argument value out of range
+ 500 Server Error
+
+
+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
+ is 5250. Connections can be broken at will or use the BYE command to
+ request the server to terminate the connection.
+
+
+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 ?
+ is the unit number, for example, U0. As units are added to the server,
+ the unit number increases; the first unit is U0.
+
+ The command HELP lists all commands known to the server with a brief
+ description of their purpose and arguments. Most commands take zero or
+ one argument outside of the unit name. Sometimes an argument is
+ optional, and an optional argument always follows required arguments.
+ All units command required a unit name argument.
+
+ {} = required argument
+ [] = optional argument
+ () = one of a set of pre-defined values
+
+
+Global Commands
+---------------
+
+HELP
+ List the commands and their brief description.
+
+BYE
+ Close the connection.
+
+SHUTDOWN
+ Shutdown the server and all client connections.
+
+SET {key=value}
+ Set a global server configuration property.
+ Currently, the only planned key is "root" to set the base directory
+ path for the CLS and LOAD commands. The default root value is /.
+
+GET {key}
+ Get the current value of a configuration property.
+ The value is returned by itself in the body of the response.
+
+CLS {path}
+ List the clips and subdirectories at {path} on the server.
+ Only subdirectories, non-hidden regular files, symbolic links, and NFS
+ shares are supported.
+ The response body contains one line per item.
+ The name of the subdirectory/file is always surrounded by double
+ quotation marks in case it contains spaces.
+ Subdirectories are listed before files and have a trailing / in their
+ name.
+ File entries have a size value in bytes in the second column position.
+
+RUN {file}
+ Process the commands in a file located on the server.
+ Commands are executed one after the other with no delay until the end
+ of file is reached or a command returns a response code not in the 200
+ range.
+ The response body contains each command sent along with its arguments,
+ followed by each command's response status code and response body.
+
+
+STATUS
+ Responds with the output of USTA for each unit and accepts no further
+ input. Each time the state of the unit changes, a new row is returned by
+ the server containing the state of the unit.
+
+Unit Management
+
+ The following global commands manage the DV 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 *
+
+
+UADD mlt-consumer[:argument]
+ Add a unit based upon the mlt-consumer id and optional constructor
+ argument.
+ If the consumer is not found, then it still added but in an
+ offline manner. Later, by adding the device to the bus, the unit will
+ automatically become online.
+ The response body contains the name of the new unit: U0, U1, U2, or U3.
+ Channel is an optional setting.
+
+ULS
+ List the units.
+ The response body contains a space-delimited row for each unit in the
+ 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)
+ - online flag (1 = online, 0 = offline)
+
+SHUTDOWN
+ Shutdown the server.
+
+
+Unit Commands
+-------------
+
+ The first argument of any unit command is the unit name (U0 - U3). A
+ unit must be loaded with a file before it can play anything. A "clip"
+ refers to the presence of a file loaded into the unit. A clip can
+ contain an in and out point to set the playback region. The default in
+ point is 0, and the default out point is the number of frames in the
+ file minus one. Therefore, all frame positions are zero-based.
+
+USET {unit} {key=value}
+ Set a unit's configuration property.
+ Key is one of the following: eof, points.
+
+ Property "eof" determines what the playback engine does when it reaches
+ the end of a clip. The eof property takes one of the following values:
+ stop, loop, continue or pause. The default is pause.
+
+ Property "points" determines whether the playback engine restricts the
+ playback region to the in and out points. It takes one of the following
+ values: use, ignore.
+
+UGET {unit} {key}
+ Get a unit's configuration property.
+ Key is one of the following: eof, points.
+ The response body contains only the key's value. See USET for information
+ about each property.
+
+LIST {unit}
+ List the clips associated to the unit.
+ The response body consists of two sections - the first section is a single row
+ containing the generation number of the playlist associated to the unit (an
+ integer starting from 0 which is incremented on each action which changes the
+ playlist). The second sections contais a space-delimited row for each clip in the
+ units playlistcontaining the following columns:
+ - clip index (starts from 0)
+ - file name
+ - in point
+ - out point
+ - real length of the files
+ - calculated length of file
+ When USET points=use is specified (default), the calculated size is (out-in)+1.
+ When points are ignored, the real length of the file is returned.
+
+LOAD {unit} {filename} [in out]
+ Load a clip into the unit.
+ Optionally set the in and out points to the specified absolute frame numbers.
+ 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
+ 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).
+
+APND {unit} {filename} [in out]
+ Append a clip onto the unit's playlist.
+ Optionally set the in and out points to the specified absolute frame numbers.
+
+INSERT {unit} {filename} [ [+|-]clip [ in out ] ]
+ Insert a clip into the units playlist at the specified clip index or relative
+ to the currently playing clip index.
+
+REMOVE {unit} [ [+|-]clip ]
+ Removes a clip from the specified clip index or position relative to the
+ currently playing clip index.
+
+CLEAN {unit}
+ Removes all by the playing clip.
+
+WIPE {unit}
+ Removes all clips before the playing clip.
+
+MOVE {unit} [+|-]clip [ [+|-]clip ]
+ Move a clip in the playlist to position specified or position relative to the
+ currently playing clip.
+
+PLAY {unit} [speed]
+ Commence unit playback from the current position.
+ The default speed is 100% if not specified.
+ Speed is represented as a percentage value multiplied by 10. Therefore
+ the default playback speed is 1000 (1X or 100%), 2X is 2000.
+ Negative speed values play in reverse.
+
+STOP {unit}
+ Terminate the unit playback resulting in no video being sent.
+
+PAUSE {unit}
+ Pause the unit playback causing the current frame position to he held
+ indefinitely.
+
+REW {unit}
+ Rewind the unit.
+ If the unit it playing, then REW sets the playback speed to -2000
+ (200%).
+ If the unit is stopped, then the frame position is reset to the first
+ frame. First frame depends upon the "points" unit configuration property
+ and whether an in point has been established for the clip using the SIN
+ command.
+ Set the currently loaded clip's in point.
+ Frame is zero-based and absolute. It is not dependent upon the clip's
+ current in point.
+ A frame-number of -1, resets the in point to 0.
+
+FF {unit}
+ Fast forward the unit.
+ If the unit it playing, then FF sets the playback speed to 2000 (200%
+ in reverse).
+ If the unit is stopped, then the frame position is reset to the first
+ frame. First frame depends upon the "points" unit configuration property
+ and whether an in point has been established for the clip using the SIN
+ command.
+
+STEP {unit} {number-of-frames}
+ Adjust the current frame position by the number of frames specified.
+ Number-of-frames can accept positive or negative values.
+
+GOTO {unit} {frame-number} [ [+|-]clip ]
+ Set the current frame position to frame-number.
+ Frame-number is zero-based and absolute within the clip, which means it is
+ relative to the file beginning and not the clip in point.
+ It does not alter the playback status of the unit.
+
+SIN {unit} {frame-number} [ [+|-]clip ]
+ Set the currently loaded clip's in point.
+ The in point is the logical starting frame of the clip.
+ Frame is zero-based and absolute. It is not dependent upon the clip's
+ current in point.
+ A frame-number of -1, resets the in point to 0.
+
+SOUT {unit} {frame-number} [ [+|-]clip ]
+ Set the currently loaded clip's out point.
+ The out point is the logical last frame of the clip.
+ Frame is zero-based and absolute. It is not dependent upon the clip's
+ current out point.
+ A frame-number of -1, resets the out point to the number of frames in
+ the file minus 1.
+
+USTA {unit}
+ Get the unit status report.
+ The response body contains the following fields delimited by spaces:
+ - unit number: U0, U1, U2, or U3 without the "U" prefix
+ - mode: (offline|not_loaded|playing|stopped|paused|disconnected|unknown)
+ "unknown" means the unit has not been added
+ "disconnected" means the server has closed the connection to the client.
+ - current clip name: filename
+ - current position: in absolute frame number units
+ - speed: playback rate in (percent * 10)
+ - fps: frames-per-second of loaded clip
+ - current in-point: starting frame number
+ - current out-point: ending frame number
+ - length of the clip
+ - buffer tail clip name: filename
+ - buffer tail position: in absolute frame number units
+ - buffer tail in-point: starting frame number
+ - buffer tail out-point: ending frame number
+ - buffer tail length: length of clip in buffer tail
+ - seekable flag: indicates if the current clip is seekable (relates to head)
+ - playlist generation number
+ - current clip index (relates to head)
+
+ The status contains information based not only on the current frame being
+ output (current above) but also based upon the most recent frame read by
+ the disk reader thread and added to the tail of the input buffer queue
+ (buffer tail above).
+
+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."
+
+
+
+
projects / melted / blobdiff