git.sesse.net Git - mlt/blob - docs/dvcp.txt

   1 Miracle Control Protocol (DVCP) Reference Documentation
   2
   3 Copyright (C) 2004 Ushodaya Enterprised Limited
   4 Author: Dan Dennedy <dan@dennedy.org>
   5 Last Revision: 2004-03-20
   6
   7
   8 General Format
   9 --------------
  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.
  18
  19
  20 Response Codes
  21 --------------
  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
  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.
  35
  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
  40         request.
  41
  42         Errors in the 500 range indicate a server error or exception.
  43
  44         The following is a list of response codes and their descriptions:
  45         200 OK
  46         201 OK
  47         202 OK
  48         400 Unknown command
  49         401 Operation timed out
  50         402 Argument missing
  51         403 Unit not found
  52         404 Failed to locate or open clip
  53         405 Argument value out of range
  54         500 Server Error
  55
  56
  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.
  63
  64
  65 General Command Information
  66 ---------------------------
  67
  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.
  74
  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.
  80
  81         {} = required argument
  82         [] = optional argument
  83         () = one of a set of pre-defined values
  84
  85
  86 Global Commands
  87 ---------------
  88
  89 HELP
  90         List the commands and their brief description.
  91
  92 BYE
  93         Close the connection.
  94
  95 SHUTDOWN
  96         Shutdown the server and all client connections.
  97
  98 SET {key=value}
  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 /.
 102
 103 GET {key}
 104         Get the current value of a configuration property.
 105         The value is returned by itself in the body of the response.
 106
 107 CLS {path}
 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
 115         name.
 116         File entries have a size value in bytes in the second column position.
 117
 118 RUN {file}
 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
 122         range.
 123         The response body contains each command sent along with its arguments,
 124         followed by each command's response status code and response body.
 125
 126
 127 STATUS
 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.
 131
 132 Unit Management
 133
 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.
 139
 140 NLS
 141         * NOT IMPLEMENTED IN MIRACLE YET *
 142
 143
 144 UADD mlt-consumer[:argument]
 145         Add a unit based upon the mlt-consumer id and optional constructor
 146         argument.
 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.
 152
 153 ULS
 154         List the units.
 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)
 161
 162 SHUTDOWN
 163         Shutdown the server.
 164
 165
 166 Unit Commands
 167 -------------
 168
 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.
 175
 176 USET {unit} {key=value}
 177         Set a unit's configuration property.
 178         Key is one of the following: eof, points.
 179
 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.
 183
 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
 186         values: use, ignore.
 187
 188 UGET {unit} {key}
 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
 192         about each property.
 193
 194 LIST {unit}
 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)
 202         - file name
 203         - in point
 204         - out point
 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.
 209
 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
 219         demo programs).
 220
 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.
 224
 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.
 228
 229 REMOVE {unit} [ [+|-]clip ]
 230         Removes a clip from the specified clip index or position relative to the
 231         currently playing clip index.
 232
 233 CLEAN {unit}
 234         Removes all by the playing clip.
 235
 236 MOVE {unit} [+|-]clip [ [+|-]clip ]
 237         Move a clip in the playlist to position specified or position relative to the
 238         currently playing clip.
 239
 240 PLAY {unit} [speed]
 241         Commence unit playback from the current position.
 242         The default speed is 100% if not specified.
 243         Speed is represented as a percentage value multiplied by 10. Therefore
 244         the default playback speed is 1000 (1X or 100%), 2X is 2000.
 245         Negative speed values play in reverse.
 246
 247 STOP {unit}
 248         Terminate the unit playback resulting in no video being sent.
 249
 250 PAUSE {unit}
 251         Pause the unit playback causing the current frame position to he held
 252         indefinitely.
 253
 254 REW {unit}
 255         Rewind the unit.
 256         If the unit it playing, then REW sets the playback speed to 2000
 257         (200%).
 258         If the unit is stopped, then the frame position is reset to the first
 259         frame. First frame depends upon the "points" unit configuration property
 260         and whether an in point has been established for the clip using the SIN
 261         command.
 262         Set the currently loaded clip's in point.
 263         Frame is zero-based and absolute. It is not dependent upon the clip's
 264         current in point.
 265         A frame-number of -1, resets the in point to 0.
 266
 267 FF {unit}
 268         Fast forward the unit.
 269         If the unit it playing, then FF sets the playback speed to -2000 (200%
 270         in reverse).
 271         If the unit is stopped, then the frame position is reset to the first
 272         frame. First frame depends upon the "points" unit configuration property
 273         and whether an in point has been established for the clip using the SIN
 274         command.
 275
 276 STEP {unit} {number-of-frames}
 277         Adjust the current frame position by the number of frames specified.
 278         Number-of-frames can accept positive or negative values.
 279
 280 GOTO {unit} {frame-number} [ [+|-]clip ]
 281         Set the current frame position to frame-number.
 282         Frame-number is zero-based and absolute within the clip, which means it is
 283         relative to the file beginning and not the clip in point.
 284         It does not alter the playback status of the unit.
 285
 286 SIN {unit} {frame-number} [ [+|-]clip ]
 287         Set the currently loaded clip's in point.
 288         The in point is the logical starting frame of the clip.
 289         Frame is zero-based and absolute. It is not dependent upon the clip's
 290         current in point.
 291         A frame-number of -1, resets the in point to 0.
 292
 293 SOUT {unit} {frame-number} [ [+|-]clip ]
 294         Set the currently loaded clip's out point.
 295         The out point is the logical last frame of the clip.
 296         Frame is zero-based and absolute. It is not dependent upon the clip's
 297         current out point.
 298         A frame-number of -1, resets the out point to the number of frames in
 299         the file minus 1.
 300
 301 USTA {unit}
 302         Get the unit status report.
 303         The response body contains the following fields delimited by spaces:
 304         - unit number: U0, U1, U2, or U3 without the "U" prefix
 305         - mode: (offline|not_loaded|playing|stopped|paused|disconnected|unknown)
 306           "unknown" means the unit has not been added
 307           "disconnected" means the server has closed the connection to the client.
 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
 314         - length of the clip
 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)
 323
 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
 327         (buffer tail above).
 328
 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."
 333
 334
 335
 336