1 MLT Video Control Protocol (MVCP) Reference Documentation
3 Copyright (C) 2004-2009 Ushodaya Enterprised Limited
4 Copyright (C) 2010-2011 Dan R. Dennedy
5 Author: Dan Dennedy <dan@dennedy.org>
6 Last Revision: 2011-04-17
11 MVCP is an ASCII-based request/response TCP protocol much like FTP and
12 inspired by the SGI MVCP [1] (Multiport Video Computer Protocol). Each
13 command is three to eight characters long followed by zero or more
14 arguments. Every item (command or argument) in the request is delimited
15 by a space and terminated with a new line. Arguments that contain spaces
16 must be surrounded by double quotation marks. The new line must contain
17 a line feed optionally preceeded by a carriage return. There are no
18 request header lines or body.
20 [1] http://techpubs.sgi.com/library/tpl/cgi-bin/getdoc.cgi?coll=0650&db=bks&fname=/SGI_EndUser/MSB3xx_UG/ch09.html
25 Responses consist of a numeric result code followed by a space folowed
26 by a brief textual description of the result. No quoting is applied to
27 descriptions regardless if it contains spaces. The result codes are
28 grouped by the hundreds into general categories of responses. Anything
29 in the 200-299 range is considered a success and anything 300 and above
30 is an error or exception. Most responses do not contain a body except
31 some of the success results that report information and sometimes the
32 500 Server Error returns specific information.
34 A 200 result code contains no body.
35 A 201 result code contains one or more lines in the body, and an empty
36 line terminates the response.
37 A 202 result code contains only a single response line in the body.
39 Errors in the 400 range indicate a normally handled error where the
40 command could not perform its action due to protocol syntax errors or
41 problems with validation of one or more of the arguments. This usually
42 indicates that the client is responsible for performing an illegal
45 Errors in the 500 range indicate a server error or exception.
47 The following is a list of response codes and their descriptions:
52 401 Operation timed out
55 404 Failed to locate or open clip
56 405 Argument value out of range
60 Establishing a Connection
61 -------------------------
62 One can connect to the melted server using telnet or a custom client,
63 preferrably one developed using the libmvcp client API. The default port
64 is 5250. Connections can be broken at will or use the BYE command to
65 request the server to terminate the connection.
68 General Command Information
69 ---------------------------
71 All commands are case insensitive. Arguments may or may not be case
72 sensitive. There are two categories of commands: global and unit. Global
73 commands operate at the server level. Unit commands address a specific
74 unit. melted is a multi-unit system. Units are named as U? where ?
75 is the unit number, for example, U0. As units are added to the server,
76 the unit number increases; the first unit is U0.
78 The command HELP lists all commands known to the server with a brief
79 description of their purpose and arguments. Most commands take zero or
80 one argument outside of the unit name. Sometimes an argument is
81 optional, and an optional argument always follows required arguments.
82 All units command required a unit name argument.
84 {} = required argument
85 [] = optional argument
86 () = one of a set of pre-defined values
93 List the commands and their brief description.
99 Shutdown the server and all client connections.
102 Set a global server configuration property.
103 Currently, the only planned key is "root" to set the base directory
104 path for the CLS and LOAD commands. The default root value is /.
107 Get the current value of a configuration property.
108 The value is returned by itself in the body of the response.
111 List the clips and subdirectories at {path} on the server.
112 Only subdirectories, non-hidden regular files, symbolic links, and NFS
113 shares are supported.
114 The response body contains one line per item.
115 The name of the subdirectory/file is always surrounded by double
116 quotation marks in case it contains spaces.
117 Subdirectories are listed before files and have a trailing / in their
119 File entries have a size value in bytes in the second column position.
122 Process the commands in a file located on the server.
123 Commands are executed one after the other with no delay until the end
124 of file is reached or a command returns a response code not in the 200
126 The response body contains each command sent along with its arguments,
127 followed by each command's response status code and response body.
130 Responds with the output of USTA for each unit and accepts no further
131 input. Each time the state of the unit changes, a new row is returned by
132 the server containing the state of the unit.
137 The following global commands manage the playout units within the server.
138 Currently there is a maximum of four units, and units can not be
139 removed. Each unit may be in an online or offline state. Offline units
140 can not be used, and any unit commands issued against an offline unit
141 results in a 403 response.
144 * NOT IMPLEMENTED IN MELTED YET *
146 UADD mlt-consumer[:argument]
147 Add a unit based upon the mlt-consumer id and optional constructor
149 If the consumer is not found, then it still added but in an
150 offline manner. Later, by adding the device to the bus, the unit will
151 automatically become online.
152 The response body contains the name of the new unit: U0, U1, U2, or U3.
153 Channel is an optional setting.
157 The response body contains a space-delimited row for each unit in the
158 server containing the following columns:
159 - unit name (one of U0, U1, U2, or U3)
160 - mlt-consumer[:argument] from uadd
161 - 1394 node GUID (defunt - always 0 with melted for now)
162 - online flag (1 = online, 0 = offline)
171 The first argument of any unit command is the unit name (U0 - U3). A
172 unit must be loaded with a file before it can play anything. A "clip"
173 refers to the presence of a file loaded into the unit. A clip can
174 contain an in and out point to set the playback region. The default in
175 point is 0, and the default out point is the number of frames in the
176 file minus one. Therefore, all frame positions are zero-based.
178 USET {unit} {key=value}
179 Set a unit's configuration property.
180 Key is one of the following: eof, points.
182 Property "eof" determines what the playback engine does when it reaches
183 the end of a clip. The eof property takes one of the following values:
184 stop, loop, continue or pause. The default is pause.
186 Property "points" determines whether the playback engine restricts the
187 playback region to the in and out points. It takes one of the following
191 Get a unit's configuration property.
192 Key is one of the following: eof, points.
193 The response body contains only the key's value. See USET for information
197 List the clips associated to the unit.
198 The response body consists of two sections - the first section is a single row
199 containing the generation number of the playlist associated to the unit (an
200 integer starting from 0 which is incremented on each action which changes the
201 playlist). The second sections contais a space-delimited row for each clip in the
202 units playlistcontaining the following columns:
203 - clip index (starts from 0)
207 - real length of the files
208 - calculated length of file
209 When USET points=use is specified (default), the calculated size is (out-in)+1.
210 When points are ignored, the real length of the file is returned.
212 LOAD {unit} {filename} [in out]
213 Load a clip into the unit.
214 Optionally set the in and out points to the specified absolute frame numbers.
215 Sets the current position to the first frame in the clip.
216 Preface the filename with '!' to tell the disk reader thread to remove only
217 duplicate frames from the tail of its buffer queue (from a previously loaded
218 and playing clip). Otherwise, melted flushes all of its buffers upon LOAD
219 to make the effect of LOAD instantaneous. The LOAD !, USET eof=pause, and
220 extended USTA information can be used for client-side playlists (see the
223 APND {unit} {filename} [in out]
224 Append a clip onto the unit's playlist.
225 Optionally set the in and out points to the specified absolute frame numbers.
227 INSERT {unit} {filename} [ [+|-]clip [ in out ] ]
228 Insert a clip into the units playlist at the specified clip index or relative
229 to the currently playing clip index.
231 REMOVE {unit} [ [+|-]clip ]
232 Removes a clip from the specified clip index or position relative to the
233 currently playing clip index.
236 Removes all but the playing clip.
239 Removes all clips before the playing clip.
241 MOVE {unit} [+|-]clip [ [+|-]clip ]
242 Move a clip in the playlist to position specified or position relative to the
243 currently playing clip.
246 Commence unit playback from the current position.
247 The default speed is 100% if not specified.
248 Speed is represented as a percentage value multiplied by 10. Therefore
249 the default playback speed is 1000 (1X or 100%), 2X is 2000.
250 Negative speed values play in reverse.
253 Terminate the unit playback resulting in no video being sent.
256 Pause the unit playback causing the current frame position to he held
261 If the unit it playing, then REW sets the playback speed to -2000
263 If the unit is stopped, then the frame position is reset to the first
264 frame. First frame depends upon the "points" unit configuration property
265 and whether an in point has been established for the clip using the SIN
267 Set the currently loaded clip's in point.
268 Frame is zero-based and absolute. It is not dependent upon the clip's
270 A frame-number of -1, resets the in point to 0.
273 Fast forward the unit.
274 If the unit it playing, then FF sets the playback speed to 2000 (200%
276 If the unit is stopped, then the frame position is reset to the first
277 frame. First frame depends upon the "points" unit configuration property
278 and whether an in point has been established for the clip using the SIN
281 STEP {unit} {number-of-frames}
282 Adjust the current frame position by the number of frames specified.
283 Number-of-frames can accept positive or negative values.
285 GOTO {unit} {frame-number} [ [+|-]clip ]
286 Set the current frame position to frame-number.
287 Frame-number is zero-based and absolute within the clip, which means it is
288 relative to the file beginning and not the clip in point.
289 It does not alter the playback status of the unit.
291 SIN {unit} {frame-number} [ [+|-]clip ]
292 Set the currently loaded clip's in point.
293 The in point is the logical starting frame of the clip.
294 Frame is zero-based and absolute. It is not dependent upon the clip's
296 A frame-number of -1, resets the in point to 0.
298 SOUT {unit} {frame-number} [ [+|-]clip ]
299 Set the currently loaded clip's out point.
300 The out point is the logical last frame of the clip.
301 Frame is zero-based and absolute. It is not dependent upon the clip's
303 A frame-number of -1, resets the out point to the number of frames in
307 Get the unit status report.
308 The response body contains the following fields delimited by spaces:
309 - unit number: U0, U1, U2, or U3 without the "U" prefix
310 - mode: (offline|not_loaded|playing|stopped|paused|disconnected|unknown)
311 "unknown" means the unit has not been added
312 "disconnected" means the server has closed the connection to the client.
313 - current clip name: filename
314 - current position: in absolute frame number units
315 - speed: playback rate in (percent * 10)
316 - fps: frames-per-second of loaded clip
317 - current in-point: starting frame number
318 - current out-point: ending frame number
320 - buffer tail clip name: filename
321 - buffer tail position: in absolute frame number units
322 - buffer tail in-point: starting frame number
323 - buffer tail out-point: ending frame number
324 - buffer tail length: length of clip in buffer tail
325 - seekable flag: indicates if the current clip is seekable (relates to head)
326 - playlist generation number
327 - current clip index (relates to head)
329 The status contains information based not only on the current frame being
330 output (current above) but also based upon the most recent frame read by
331 the disk reader thread and added to the tail of the input buffer queue
334 XFER {unit} {target-unit}
335 Transfer the unit's clip to the target unit.
336 The clip inherently includes the in- and out-point information.
337 The target unit's "points" configuration property is set to "use."
342 Append an in-band MLT XML document to the unit.
343 Do note that the size and XML arguments are on new lines.
344 Size is the size of the XML payload in bytes.
345 Returns 404 if the XML is malformed or if the XML producer fails parsing.