2 dv1394d Control Protocol (DVCP) Reference Documentation
4 Copyright (C) 2003 Ushodaya Enterprised Limited
5 Author: Dan Dennedy <dan@dennedy.org>
6 Last Revision: 2003-01-13
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.
30 A 200 result code contains no body.
31 A 201 result code contains one or more lines in the body, and a empty
32 line terminates the response.
33 A 202 result code contains only a single response line in the body.
35 Errors in the 400 range indicate a normally handled error where the
36 command could not perform its action due to protocol syntax errors or
37 problems with validation of one or more of the arguments. This usually
38 indicates that the client is responsible for performing an illegal
41 Errors in the 500 range indicate a server error or exception.
43 The following is a list of response codes and their descriptions:
48 401 Operation timed out
51 404 Failed to locate or open clip
52 405 Argument value out of range
56 Establishing a Connection
57 -------------------------
58 One can connect to the miracle server using telnet or a custom client,
59 preferrably one developed using the valerie client API. The default port
60 is 5250. Connections can be broken at will or use the BYE command to
61 request the server to terminate the connection.
64 General Command Information
65 ---------------------------
67 All commands are case insensitive. Arguments may or may not be case
68 sensitive. There are two categories of commands: global and unit. Global
69 commands operate at the server level. Unit commands address a specific
70 unit. miracle is a multi-unit system. Units are named as U? where ?
71 is the unit number, for example, U0. As units are added to the server,
72 the unit number increases; the first unit is U0.
74 The command HELP lists all commands known to the server with a brief
75 description of their purpose and arguments. Most commands take zero or
76 one argument outside of the unit name. Sometimes an argument is
77 optional, and an optional argument always follows required arguments.
78 All units command required a unit name argument.
80 {} = required argument
81 [] = optional argument
82 () = one of a set of pre-defined values
89 List the commands and their brief description.
95 Shutdown the server and all client connections.
98 Set a global server configuration property.
99 Currently, the only planned key is "root" to set the base directory
100 path for the CLS and LOAD commands. The default root value is /.
103 Get the current value of a configuration property.
104 The value is returned by itself in the body of the response.
107 List the clips and subdirectories at {path} on the server.
108 Only subdirectories, non-hidden regular files, symbolic links, and NFS
109 shares are supported.
110 The response body contains one line per item.
111 The name of the subdirectory/file is always surrounded by double
112 quotation marks in case it contains spaces.
113 Subdirectories are listed before files and have a trailing / in their
115 File entries have a size value in bytes in the second column position.
118 Process the commands in a file located on the server.
119 Commands are executed one after the other with no delay until the end
120 of file is reached or a command returns a response code not in the 200
122 The response body contains each command sent along with its arguments,
123 followed by each command's response status code and response body.
127 Responds with the output of USTA for each unit and accepts no further
128 input. Each time the state of the unit changes, a new row is returned by
129 the server containing the state of the unit.
133 The following global commands manage the DV units within the server.
134 Currently there is a maximum of four units, and units can not be
135 removed. Each unit may be in an online or offline state. Offline units
136 can not be used, and any unit commands issued against an offline unit
137 results in a 403 response.
140 * NOT IMPLEMENTED IN MIRACLE YET *
143 UADD mlt-consumer[:argument]
144 Add a unit based upon the mlt-consumer id and optional constructor
146 If the consumer is not found, then it still added but in an
147 offline manner. Later, by adding the device to the bus, the unit will
148 automatically become online.
149 The response body contains the name of the new unit: U0, U1, U2, or U3.
150 Channel is an optional setting.
154 The response body contains a space-delimited row for each unit in the
155 server containing the following columns:
156 - unit name (one of U0, U1, U2, or U3)
157 - mlt-consumer[:argument] from uadd
158 - 1394 node GUID (defunt - always 0 with miracle for now)
159 - online flag (1 = online, 0 = offline)
168 The first argument of any unit command is the unit name (U0 - U3). A
169 unit must be loaded with a file before it can play anything. A "clip"
170 refers to the presence of a file loaded into the unit. A clip can
171 contain an in and out point to set the playback region. The default in
172 point is 0, and the default out point is the number of frames in the
173 file minus one. Therefore, all frame positions are zero-based.
175 USET {unit} {key=value}
176 Set a unit's configuration property.
177 Key is one of the following: eof, points.
179 Property "eof" determines what the playback engine does when it reaches
180 the end of a clip. The eof property takes one of the following values:
181 stop, loop, continue or pause. The default is pause.
183 Property "points" determines whether the playback engine restricts the
184 playback region to the in and out points. It takes one of the following
188 Get a unit's configuration property.
189 Key is one of the following: eof, points.
190 The response body contains only the key's value. See USET for information
194 List the clips associated to the unit.
195 The response body consists of two sections - the first section is a single row
196 containing the generation number of the playlist associated to the unit (an
197 integer starting from 0 which is incremented on each action which changes the
198 playlist). The second sections contais a space-delimited row for each clip in the
199 units playlistcontaining the following columns:
200 - clip index (starts from 0)
204 - real length of the files
205 - calculated length of file
206 When USET points=use is specified (default), the calculated size is (out-in)+1.
207 When points are ignored, the real length of the file is returned.
209 LOAD {unit} {filename} [in out]
210 Load a clip into the unit.
211 Optionally set the in and out points to the specified absolute frame numbers.
212 Sets the current position to the first frame in the clip.
213 Preface the filename with '!' to tell the disk reader thread to remove only
214 duplicate frames from the tail of its buffer queue (from a previously loaded
215 and playing clip). Otherwise, miracle flushes all of its buffers upon LOAD
216 to make the effect of LOAD instantaneous. The LOAD !, USET eof=pause, and
217 extended USTA information can be used for client-side playlists (see the
220 APND {unit} {filename} [in out]
221 Append a clip onto the unit's playlist.
222 Optionally set the in and out points to the specified absolute frame numbers.
224 INSERT {unit} {filename} [ [+|-]clip [ in out ] ]
225 Insert a clip into the units playlist at the specified clip index or relative
226 to the currently playing clip index.
228 REMOVE {unit} [ [+|-]clip ]
229 Removes a clip from the specified clip index or position relative to the
230 currently playing clip index.
233 Removes all by the playing clip.
235 MOVE {unit} [+|-]clip [ [+|-]clip ]
236 Move a clip in the playlist to position specified or position relative to the
237 currently playing clip.
240 Commence unit playback from the current position.
241 The default speed is 100% if not specified.
242 Speed is represented as a percentage value multiplied by 10. Therefore
243 the default playback speed is 1000 (1X or 100%), 2X is 2000.
244 Negative speed values play in reverse.
247 Terminate the unit playback resulting in no video being sent.
250 Pause the unit playback causing the current frame position to he held
255 If the unit it playing, then REW sets the playback speed to 2000
257 If the unit is stopped, then the frame position is reset to the first
258 frame. First frame depends upon the "points" unit configuration property
259 and whether an in point has been established for the clip using the SIN
261 Set the currently loaded clip's in point.
262 Frame is zero-based and absolute. It is not dependent upon the clip's
264 A frame-number of -1, resets the in point to 0.
267 Fast forward the unit.
268 If the unit it playing, then FF sets the playback speed to -2000 (200%
270 If the unit is stopped, then the frame position is reset to the first
271 frame. First frame depends upon the "points" unit configuration property
272 and whether an in point has been established for the clip using the SIN
275 STEP {unit} {number-of-frames}
276 Adjust the current frame position by the number of frames specified.
277 Number-of-frames can accept positive or negative values.
279 GOTO {unit} {frame-number} [ [+|-]clip ]
280 Set the current frame position to frame-number.
281 Frame-number is zero-based and absolute within the clip, which means it is
282 relative to the file beginning and not the clip in point.
283 It does not alter the playback status of the unit.
285 SIN {unit} {frame-number} [ [+|-]clip ]
286 Set the currently loaded clip's in point.
287 The in point is the logical starting frame of the clip.
288 Frame is zero-based and absolute. It is not dependent upon the clip's
290 A frame-number of -1, resets the in point to 0.
292 SOUT {unit} {frame-number} [ [+|-]clip ]
293 Set the currently loaded clip's out point.
294 The out point is the logical last frame of the clip.
295 Frame is zero-based and absolute. It is not dependent upon the clip's
297 A frame-number of -1, resets the out point to the number of frames in
301 Get the unit status report.
302 The response body contains the following fields delimited by spaces:
303 - unit number: U0, U1, U2, or U3 without the "U" prefix
304 - mode: (offline|not_loaded|playing|stopped|paused|disconnected|unknown)
305 "unknown" means the unit has not been added
306 "disconnected" means the server has closed a connection to a client running
308 - current clip name: filename
309 - current position: in absolute frame number units
310 - speed: playback rate in (percent * 10)
311 - fps: frames-per-second of loaded clip
312 - current in-point: starting frame number
313 - current out-point: ending frame number
315 - buffer tail clip name: filename
316 - buffer tail position: in absolute frame number units
317 - buffer tail in-point: starting frame number
318 - buffer tail out-point: ending frame number
319 - buffer tail length: length of clip in buffer tail
320 - seekable flag: indicates if the current clip is seekable (relates to head)
321 - playlist generation number
322 - current clip index (relates to head)
324 The status contains information based not only on the current frame being
325 output (current above) but also based upon the most recent frame read by
326 the disk reader thread and added to the tail of the input buffer queue
329 XFER {unit} {target-unit}
330 Transfer the unit's clip to the target unit.
331 The clip inherently includes the in- and out-point information.
332 The target unit's "points" configuration property is set to "use."