MLT library
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

340 lines
13KB

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