adopt to winsock
[melted] / docs / mvcp.txt
1 MLT Video Control Protocol (MVCP) Reference Documentation
2
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
7
8
9 General Format
10 --------------
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.
19
20         [1] http://techpubs.sgi.com/library/tpl/cgi-bin/getdoc.cgi?coll=0650&db=bks&fname=/SGI_EndUser/MSB3xx_UG/ch09.html
21
22
23 Response Codes
24 --------------
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. 
33
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.
38
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
43         request.
44         
45         Errors in the 500 range indicate a server error or exception.
46         
47         The following is a list of response codes and their descriptions:
48         200 OK
49         201 OK
50         202 OK
51         400 Unknown command
52         401 Operation timed out
53         402 Argument missing
54         403 Unit not found
55         404 Failed to locate or open clip
56         405 Argument value out of range
57         500 Server Error
58
59
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.
66
67
68 General Command Information
69 ---------------------------
70
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.
77         
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.
83         
84         {} = required argument
85         [] = optional argument
86         () = one of a set of pre-defined values
87         
88
89 Global Commands
90 ---------------
91
92 HELP
93         List the commands and their brief description.
94
95 BYE
96         Close the connection.
97         
98 SHUTDOWN
99         Shutdown the server and all client connections.
100
101 SET {key=value}
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 /.
105
106 GET {key}
107         Get the current value of a configuration property.
108         The value is returned by itself in the body of the response.
109
110 CLS {path}
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
118         name.
119         File entries have a size value in bytes in the second column position.
120
121 RUN {file}
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
125         range.
126         The response body contains each command sent along with its arguments,
127         followed by each command's response status code and response body.
128
129 STATUS
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. 
133
134
135 Unit Management
136
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. 
142         
143 NLS
144         * NOT IMPLEMENTED IN MELTED YET *
145
146 UADD mlt-consumer[:argument]
147         Add a unit based upon the mlt-consumer id and optional constructor
148         argument.
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. 
154
155 ULS
156         List the units.
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)
163
164 SHUTDOWN
165         Shutdown the server.
166
167
168 Unit Commands
169 -------------
170
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.
177
178 USET {unit} {key=value}
179         Set a unit's configuration property.
180         Key is one of the following: eof, points.
181         
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.
185         
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
188         values: use, ignore. (not currently implemented)
189         
190 UGET {unit} {key}
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 
194         about each property.
195
196 LIST {unit}
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)
204         - file name
205         - in point
206         - out point
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.
211
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 
221         demo programs).
222
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.
226         
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.
230
231 REMOVE {unit} [ [+|-]clip ]
232         Removes a clip from the specified clip index or position relative to the 
233         currently playing clip index.
234         
235 CLEAN {unit}
236         Removes all but the playing clip.
237         
238 WIPE {unit}
239         Removes all clips before the playing clip.
240         
241 MOVE {unit} [+|-]clip [ [+|-]clip ]
242         Move a clip in the playlist to position specified or position relative to the
243         currently playing clip.
244
245 PLAY {unit} [speed]
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.
251
252 STOP {unit}
253         Terminate the unit playback resulting in no video being sent.
254
255 PAUSE {unit}
256         Pause the unit playback causing the current frame position to he held
257         indefinitely.
258
259 REW {unit}
260         Rewind the unit.
261         If the unit it playing, then REW sets the playback speed to -2000
262         (200%).
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         (not currently implemented)     and whether an in point has been established
266         for the clip using the SIN command.
267
268 FF {unit}
269         Fast forward the unit.
270         If the unit it playing, then FF sets the playback speed to 2000 (200%
271         in reverse).
272         If the unit is stopped, then the frame position is reset to the first
273         frame. First frame depends upon the "points" unit configuration property
274         (not currently implemented) and whether an in point has been established
275         for the clip using the SIN command.
276
277 STEP {unit} {number-of-frames}
278         Adjust the current frame position by the number of frames specified.
279         Number-of-frames can accept positive or negative values.
280
281 GOTO {unit} {frame-number} [ [+|-]clip ]
282         Set the current frame position to frame-number.
283         Frame-number is zero-based and absolute within the clip, which means it is 
284         relative to the file beginning and not the clip in point.
285         It does not alter the playback status of the unit. 
286
287 SIN {unit} {frame-number} [ [+|-]clip ]
288         Set the currently loaded clip's in point.
289         The in point is the logical starting frame of the clip.
290         Frame is zero-based and absolute. It is not dependent upon the clip's
291         current in point.
292         A frame-number of -1, resets the in point to 0.
293
294 SOUT {unit} {frame-number} [ [+|-]clip ]
295         Set the currently loaded clip's out point.
296         The out point is the logical last frame of the clip.
297         Frame is zero-based and absolute. It is not dependent upon the clip's
298         current out point.
299         A frame-number of -1, resets the out point to the number of frames in
300         the file minus 1.
301
302 USTA {unit}
303         Get the unit status report.
304         The response body contains the following fields delimited by spaces:
305         - unit number: U0, U1, U2, or U3 without the "U" prefix
306         - mode: (offline|not_loaded|playing|stopped|paused|disconnected|unknown)
307           "unknown" means the unit has not been added
308           "disconnected" means the server has closed the connection to the client.
309         - current clip name: filename
310         - current position: in absolute frame number units
311         - speed: playback rate in (percent * 10)
312         - fps: frames-per-second of loaded clip
313         - current in-point: starting frame number
314         - current out-point: ending frame number
315         - length of the clip
316         - buffer tail clip name: filename
317         - buffer tail position: in absolute frame number units
318         - buffer tail in-point: starting frame number
319         - buffer tail out-point: ending frame number
320         - buffer tail length: length of clip in buffer tail
321         - seekable flag: indicates if the current clip is seekable (relates to head)
322         - playlist generation number
323         - current clip index (relates to head)
324          
325         The status contains information based not only on the current frame being
326         output (current above) but also based upon the most recent frame read by
327         the disk reader thread and added to the tail of the input buffer queue
328         (buffer tail above).
329
330 XFER {unit} {target-unit}
331         Transfer the unit's clip to the target unit.
332         The clip inherently includes the in- and out-point information.
333         The target unit's "points" configuration property is set to "use."
334
335 PUSH {unit}
336 {size}
337 {XML}
338         Append an in-band MLT XML document to the unit.
339         Do note that the size and XML arguments are on new lines.
340         Size is the size of the XML payload in bytes.
341         Returns 404 if the XML is malformed or if the XML producer fails parsing.