Nevar pievienot vairāk kā 25 tēmas
Tēmai ir jāsākas ar burtu vai ciparu, tā var saturēt domu zīmes ('-') un var būt līdz 35 simboliem gara.
340 rindas
13 KiB
340 rindas
13 KiB
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."
|
|
|
|
|
|
|
|
|