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

   1
   2 dv1394d Control Protocol (DVCP) Reference Documentation
   3
   4 Copyright (C) 2003 Ushodaya Enterprised Limited
   5 Author: Dan Dennedy <dan@dennedy.org>
   6 Last Revision: 2003-01-13
   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                 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.
  34
  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
  39         request.
  40
  41         Errors in the 500 range indicate a server error or exception.
  42
  43         The following is a list of response codes and their descriptions:
  44         200 OK
  45         201 OK
  46         202 OK
  47         400 Unknown command
  48         401 Operation timed out
  49         402 Argument missing
  50         403 Unit not found
  51         404 Failed to locate or open clip
  52         405 Argument value out of range
  53         500 Server Error
  54
  55
  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.
  62
  63
  64 General Command Information
  65 ---------------------------
  66
  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.
  73
  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.
  79
  80         {} = required argument
  81         [] = optional argument
  82         () = one of a set of pre-defined values
  83
  84
  85 Global Commands
  86 ---------------
  87
  88 HELP
  89         List the commands and their brief description.
  90
  91 BYE
  92         Close the connection.
  93
  94 SHUTDOWN
  95         Shutdown the server and all client connections.
  96
  97 SET {key=value}
  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 /.
 101
 102 GET {key}
 103         Get the current value of a configuration property.
 104         The value is returned by itself in the body of the response.
 105
 106 CLS {path}
 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
 114         name.
 115         File entries have a size value in bytes in the second column position.
 116
 117 RUN {file}
 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
 121         range.
 122         The response body contains each command sent along with its arguments,
 123         followed by each command's response status code and response body.
 124
 125
 126 STATUS
 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.
 130
 131 Unit Management
 132
 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.
 138
 139 NLS
 140         * NOT IMPLEMENTED IN MIRACLE YET *
 141
 142
 143 UADD mlt-consumer[:argument]
 144         Add a unit based upon the mlt-consumer id and optional constructor
 145         argument.
 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.
 151
 152 ULS
 153         List the units.
 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)
 160
 161 SHUTDOWN
 162         Shutdown the server.
 163
 164
 165 Unit Commands
 166 -------------
 167
 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.
 174
 175 USET {unit} {key=value}
 176         Set a unit's configuration property.
 177         Key is one of the following: eof, points.
 178
 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.
 182
 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
 185         values: use, ignore.
 186
 187 UGET {unit} {key}
 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
 191         about each property.
 192
 193 LIST {unit}
 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)
 201         - file name
 202         - in point
 203         - out point
 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.
 208
 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
 218         demo programs).
 219
 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.
 223
 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.
 227
 228 REMOVE {unit} [ [+|-]clip ]
 229         Removes a clip from the specified clip index or position relative to the
 230         currently playing clip index.
 231
 232 CLEAN {unit}
 233         Removes all by the playing clip.
 234
 235 MOVE {unit} [+|-]clip [ [+|-]clip ]
 236         Move a clip in the playlist to position specified or position relative to the
 237         currently playing clip.
 238
 239 PLAY {unit} [speed]
 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.
 245
 246 STOP {unit}
 247         Terminate the unit playback resulting in no video being sent.
 248
 249 PAUSE {unit}
 250         Pause the unit playback causing the current frame position to he held
 251         indefinitely.
 252
 253 REW {unit}
 254         Rewind the unit.
 255         If the unit it playing, then REW sets the playback speed to 2000
 256         (200%).
 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
 260         command.
 261         Set the currently loaded clip's in point.
 262         Frame is zero-based and absolute. It is not dependent upon the clip's
 263         current in point.
 264         A frame-number of -1, resets the in point to 0.
 265
 266 FF {unit}
 267         Fast forward the unit.
 268         If the unit it playing, then FF sets the playback speed to -2000 (200%
 269         in reverse).
 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
 273         command.
 274
 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.
 278
 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.
 284
 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
 289         current in point.
 290         A frame-number of -1, resets the in point to 0.
 291
 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
 296         current out point.
 297         A frame-number of -1, resets the out point to the number of frames in
 298         the file minus 1.
 299
 300 USTA {unit}
 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
 307                 STATUS.
 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