1 Miracle Control Protocol (DVCP) Reference Documentation
3 Copyright (C) 2004 Ushodaya Enterprised Limited
4 Author: Dan Dennedy <dan@dennedy.org>
5 Last Revision: 2004-03-20
10 DVCP is an ASCII-based request/response TCP protocol much like FTP and
11 inspired by the SGI MVCP (Multiport Video Computer Protocol). Each
12 command is three to eight characters long followed by zero or more
13 arguments. Every item (command or argument) in the request is delimited
14 by a space and terminated with a new line. Arguments that contain spaces
15 must be surrounded by double quotation marks. The new line must contain
16 a line feed optionally preceeded by a carriage return. There are no
17 request header lines or body.
22 Responses consist of a numeric result code followed by a space folowed
23 by a brief textual description of the result. No quoting is applied to
24 descriptions regardless if it contains spaces. The result codes are
25 grouped by the hundreds into general categories of responses. Anything
26 in the 200-299 range is considered a success and anything 300 and above
27 is an error or exception. Most responses do not contain a body except
28 some of the success results that report information and sometimes the
29 500 Server Error returns specific information.
31 A 200 result code contains no body.
32 A 201 result code contains one or more lines in the body, and an empty
33 line terminates the response.
34 A 202 result code contains only a single response line in the body.
36 Errors in the 400 range indicate a normally handled error where the
37 command could not perform its action due to protocol syntax errors or
38 problems with validation of one or more of the arguments. This usually
39 indicates that the client is responsible for performing an illegal
42 Errors in the 500 range indicate a server error or exception.
44 The following is a list of response codes and their descriptions:
49 401 Operation timed out
52 404 Failed to locate or open clip
53 405 Argument value out of range
57 Establishing a Connection
58 -------------------------
59 One can connect to the miracle server using telnet or a custom client,
60 preferrably one developed using the valerie client API. The default port
61 is 5250. Connections can be broken at will or use the BYE command to
62 request the server to terminate the connection.
65 General Command Information
66 ---------------------------
68 All commands are case insensitive. Arguments may or may not be case
69 sensitive. There are two categories of commands: global and unit. Global
70 commands operate at the server level. Unit commands address a specific
71 unit. miracle is a multi-unit system. Units are named as U? where ?
72 is the unit number, for example, U0. As units are added to the server,
73 the unit number increases; the first unit is U0.
75 The command HELP lists all commands known to the server with a brief
76 description of their purpose and arguments. Most commands take zero or
77 one argument outside of the unit name. Sometimes an argument is
78 optional, and an optional argument always follows required arguments.
79 All units command required a unit name argument.
81 {} = required argument
82 [] = optional argument
83 () = one of a set of pre-defined values
90 List the commands and their brief description.
96 Shutdown the server and all client connections.
99 Set a global server configuration property.
100 Currently, the only planned key is "root" to set the base directory
101 path for the CLS and LOAD commands. The default root value is /.
104 Get the current value of a configuration property.
105 The value is returned by itself in the body of the response.
108 List the clips and subdirectories at {path} on the server.
109 Only subdirectories, non-hidden regular files, symbolic links, and NFS
110 shares are supported.
111 The response body contains one line per item.
112 The name of the subdirectory/file is always surrounded by double
113 quotation marks in case it contains spaces.
114 Subdirectories are listed before files and have a trailing / in their
116 File entries have a size value in bytes in the second column position.
119 Process the commands in a file located on the server.
120 Commands are executed one after the other with no delay until the end
121 of file is reached or a command returns a response code not in the 200
123 The response body contains each command sent along with its arguments,
124 followed by each command's response status code and response body.
128 Responds with the output of USTA for each unit and accepts no further
129 input. Each time the state of the unit changes, a new row is returned by
130 the server containing the state of the unit.
134 The following global commands manage the DV units within the server.
135 Currently there is a maximum of four units, and units can not be
136 removed. Each unit may be in an online or offline state. Offline units
137 can not be used, and any unit commands issued against an offline unit
138 results in a 403 response.
141 * NOT IMPLEMENTED IN MIRACLE YET *
144 UADD mlt-consumer[:argument]
145 Add a unit based upon the mlt-consumer id and optional constructor
147 If the consumer is not found, then it still added but in an
148 offline manner. Later, by adding the device to the bus, the unit will
149 automatically become online.
150 The response body contains the name of the new unit: U0, U1, U2, or U3.
151 Channel is an optional setting.
155 The response body contains a space-delimited row for each unit in the
156 server containing the following columns:
157 - unit name (one of U0, U1, U2, or U3)
158 - mlt-consumer[:argument] from uadd
159 - 1394 node GUID (defunt - always 0 with miracle for now)
160 - online flag (1 = online, 0 = offline)
169 The first argument of any unit command is the unit name (U0 - U3). A
170 unit must be loaded with a file before it can play anything. A "clip"
171 refers to the presence of a file loaded into the unit. A clip can
172 contain an in and out point to set the playback region. The default in
173 point is 0, and the default out point is the number of frames in the
174 file minus one. Therefore, all frame positions are zero-based.
176 USET {unit} {key=value}
177 Set a unit's configuration property.
178 Key is one of the following: eof, points.
180 Property "eof" determines what the playback engine does when it reaches
181 the end of a clip. The eof property takes one of the following values:
182 stop, loop, continue or pause. The default is pause.
184 Property "points" determines whether the playback engine restricts the
185 playback region to the in and out points. It takes one of the following
189 Get a unit's configuration property.
190 Key is one of the following: eof, points.
191 The response body contains only the key's value. See USET for information
195 List the clips associated to the unit.
196 The response body consists of two sections - the first section is a single row
197 containing the generation number of the playlist associated to the unit (an
198 integer starting from 0 which is incremented on each action which changes the
199 playlist). The second sections contais a space-delimited row for each clip in the
200 units playlistcontaining the following columns:
201 - clip index (starts from 0)
205 - real length of the files
206 - calculated length of file
207 When USET points=use is specified (default), the calculated size is (out-in)+1.
208 When points are ignored, the real length of the file is returned.
210 LOAD {unit} {filename} [in out]
211 Load a clip into the unit.
212 Optionally set the in and out points to the specified absolute frame numbers.
213 Sets the current position to the first frame in the clip.
214 Preface the filename with '!' to tell the disk reader thread to remove only
215 duplicate frames from the tail of its buffer queue (from a previously loaded
216 and playing clip). Otherwise, miracle flushes all of its buffers upon LOAD
217 to make the effect of LOAD instantaneous. The LOAD !, USET eof=pause, and
218 extended USTA information can be used for client-side playlists (see the
221 APND {unit} {filename} [in out]
222 Append a clip onto the unit's playlist.
223 Optionally set the in and out points to the specified absolute frame numbers.
225 INSERT {unit} {filename} [ [+|-]clip [ in out ] ]
226 Insert a clip into the units playlist at the specified clip index or relative
227 to the currently playing clip index.
229 REMOVE {unit} [ [+|-]clip ]
230 Removes a clip from the specified clip index or position relative to the
231 currently playing clip index.
234 Removes all by the playing clip.
237 Removes all clips before the playing clip.
239 MOVE {unit} [+|-]clip [ [+|-]clip ]
240 Move a clip in the playlist to position specified or position relative to the
241 currently playing clip.
244 Commence unit playback from the current position.
245 The default speed is 100% if not specified.
246 Speed is represented as a percentage value multiplied by 10. Therefore
247 the default playback speed is 1000 (1X or 100%), 2X is 2000.
248 Negative speed values play in reverse.
251 Terminate the unit playback resulting in no video being sent.
254 Pause the unit playback causing the current frame position to he held
259 If the unit it playing, then REW sets the playback speed to -2000
261 If the unit is stopped, then the frame position is reset to the first
262 frame. First frame depends upon the "points" unit configuration property
263 and whether an in point has been established for the clip using the SIN
265 Set the currently loaded clip's in point.
266 Frame is zero-based and absolute. It is not dependent upon the clip's
268 A frame-number of -1, resets the in point to 0.
271 Fast forward the unit.
272 If the unit it playing, then FF sets the playback speed to 2000 (200%
274 If the unit is stopped, then the frame position is reset to the first
275 frame. First frame depends upon the "points" unit configuration property
276 and whether an in point has been established for the clip using the SIN
279 STEP {unit} {number-of-frames}
280 Adjust the current frame position by the number of frames specified.
281 Number-of-frames can accept positive or negative values.
283 GOTO {unit} {frame-number} [ [+|-]clip ]
284 Set the current frame position to frame-number.
285 Frame-number is zero-based and absolute within the clip, which means it is
286 relative to the file beginning and not the clip in point.
287 It does not alter the playback status of the unit.
289 SIN {unit} {frame-number} [ [+|-]clip ]
290 Set the currently loaded clip's in point.
291 The in point is the logical starting frame of the clip.
292 Frame is zero-based and absolute. It is not dependent upon the clip's
294 A frame-number of -1, resets the in point to 0.
296 SOUT {unit} {frame-number} [ [+|-]clip ]
297 Set the currently loaded clip's out point.
298 The out point is the logical last frame of the clip.
299 Frame is zero-based and absolute. It is not dependent upon the clip's
301 A frame-number of -1, resets the out point to the number of frames in
305 Get the unit status report.
306 The response body contains the following fields delimited by spaces:
307 - unit number: U0, U1, U2, or U3 without the "U" prefix
308 - mode: (offline|not_loaded|playing|stopped|paused|disconnected|unknown)
309 "unknown" means the unit has not been added
310 "disconnected" means the server has closed the connection to the client.
311 - current clip name: filename
312 - current position: in absolute frame number units
313 - speed: playback rate in (percent * 10)
314 - fps: frames-per-second of loaded clip
315 - current in-point: starting frame number
316 - current out-point: ending frame number
318 - buffer tail clip name: filename
319 - buffer tail position: in absolute frame number units
320 - buffer tail in-point: starting frame number
321 - buffer tail out-point: ending frame number
322 - buffer tail length: length of clip in buffer tail
323 - seekable flag: indicates if the current clip is seekable (relates to head)
324 - playlist generation number
325 - current clip index (relates to head)
327 The status contains information based not only on the current frame being
328 output (current above) but also based upon the most recent frame read by
329 the disk reader thread and added to the tail of the input buffer queue
332 XFER {unit} {target-unit}
333 Transfer the unit's clip to the target unit.
334 The clip inherently includes the in- and out-point information.
335 The target unit's "points" configuration property is set to "use."