+++ /dev/null
-
-dv1394d Control Protocol (DVCP) Reference Documentation
-
-Copyright (C) 2003 Ushodaya Enterprised Limited
-Author: Dan Dennedy <dan@dennedy.org>
-Last Revision: 2003-01-13
-
-General Format
---------------
- DVCP is an ASCII-based request/response TCP protocol much like FTP and
- inspired by the SGI MVCP (Multiport Video Computer Protocol). Each
- command is three to eight characters long followed by zero or more
- arguments. Every item (command or argument) in the request is delimited
- by a space and terminated with a new line. Arguments that contain spaces
- must be surrounded by double quotation marks. The new line must contain
- a line feed optionally preceeded by a carriage return. There are no
- request header lines or body.
-
-
-Response Codes
---------------
- Responses consist of a numeric result code followed by a space folowed
- by a brief textual description of the result. No quoting is applied to
- descriptions regardless if it contains spaces. The result codes are
- grouped by the hundreds into general categories of responses. Anything
- in the 200-299 range is considered a success and anything 300 and above
- is an error or exception. Most responses do not contain a body except
- some of the success results that report information and sometimes the
- 500 Server Error returns specific information.
- A 200 result code contains no body.
- A 201 result code contains one or more lines in the body, and a empty
- line terminates the response.
- A 202 result code contains only a single response line in the body.
-
- Errors in the 400 range indicate a normally handled error where the
- command could not perform its action due to protocol syntax errors or
- problems with validation of one or more of the arguments. This usually
- indicates that the client is responsible for performing an illegal
- request.
-
- Errors in the 500 range indicate a server error or exception.
-
- The following is a list of response codes and their descriptions:
- 200 OK
- 201 OK
- 202 OK
- 400 Unknown command
- 401 Operation timed out
- 402 Argument missing
- 403 Unit not found
- 404 Failed to locate or open clip
- 405 Argument value out of range
- 500 Server Error
-
-
-Establishing a Connection
--------------------------
- One can connect to the miracle server using telnet or a custom client,
- preferrably one developed using the valerie client API. The default port
- is 5250. Connections can be broken at will or use the BYE command to
- request the server to terminate the connection.
-
-
-General Command Information
----------------------------
-
- All commands are case insensitive. Arguments may or may not be case
- sensitive. There are two categories of commands: global and unit. Global
- commands operate at the server level. Unit commands address a specific
- unit. miracle is a multi-unit system. Units are named as U? where ?
- is the unit number, for example, U0. As units are added to the server,
- the unit number increases; the first unit is U0.
-
- The command HELP lists all commands known to the server with a brief
- description of their purpose and arguments. Most commands take zero or
- one argument outside of the unit name. Sometimes an argument is
- optional, and an optional argument always follows required arguments.
- All units command required a unit name argument.
-
- {} = required argument
- [] = optional argument
- () = one of a set of pre-defined values
-
-
-Global Commands
----------------
-
-HELP
- List the commands and their brief description.
-
-BYE
- Close the connection.
-
-SHUTDOWN
- Shutdown the server and all client connections.
-
-SET {key=value}
- Set a global server configuration property.
- Currently, the only planned key is "root" to set the base directory
- path for the CLS and LOAD commands. The default root value is /.
-
-GET {key}
- Get the current value of a configuration property.
- The value is returned by itself in the body of the response.
-
-CLS {path}
- List the clips and subdirectories at {path} on the server.
- Only subdirectories, non-hidden regular files, symbolic links, and NFS
- shares are supported.
- The response body contains one line per item.
- The name of the subdirectory/file is always surrounded by double
- quotation marks in case it contains spaces.
- Subdirectories are listed before files and have a trailing / in their
- name.
- File entries have a size value in bytes in the second column position.
-
-RUN {file}
- Process the commands in a file located on the server.
- Commands are executed one after the other with no delay until the end
- of file is reached or a command returns a response code not in the 200
- range.
- The response body contains each command sent along with its arguments,
- followed by each command's response status code and response body.
-
-
-STATUS
- Responds with the output of USTA for each unit and accepts no further
- input. Each time the state of the unit changes, a new row is returned by
- the server containing the state of the unit.
-
-Unit Management
-
- The following global commands manage the DV units within the server.
- Currently there is a maximum of four units, and units can not be
- removed. Each unit may be in an online or offline state. Offline units
- can not be used, and any unit commands issued against an offline unit
- results in a 403 response.
-
-NLS
- * NOT IMPLEMENTED IN MIRACLE YET *
-
-
-UADD mlt-consumer[:argument]
- Add a unit based upon the mlt-consumer id and optional constructor
- argument.
- If the consumer is not found, then it still added but in an
- offline manner. Later, by adding the device to the bus, the unit will
- automatically become online.
- The response body contains the name of the new unit: U0, U1, U2, or U3.
- Channel is an optional setting.
-
-ULS
- List the units.
- The response body contains a space-delimited row for each unit in the
- server containing the following columns:
- - unit name (one of U0, U1, U2, or U3)
- - mlt-consumer[:argument] from uadd
- - 1394 node GUID (defunt - always 0 with miracle for now)
- - online flag (1 = online, 0 = offline)
-
-SHUTDOWN
- Shutdown the server.
-
-
-Unit Commands
--------------
-
- The first argument of any unit command is the unit name (U0 - U3). A
- unit must be loaded with a file before it can play anything. A "clip"
- refers to the presence of a file loaded into the unit. A clip can
- contain an in and out point to set the playback region. The default in
- point is 0, and the default out point is the number of frames in the
- file minus one. Therefore, all frame positions are zero-based.
-
-USET {unit} {key=value}
- Set a unit's configuration property.
- Key is one of the following: eof, points.
-
- Property "eof" determines what the playback engine does when it reaches
- the end of a clip. The eof property takes one of the following values:
- stop, loop, continue or pause. The default is pause.
-
- Property "points" determines whether the playback engine restricts the
- playback region to the in and out points. It takes one of the following
- values: use, ignore.
-
-UGET {unit} {key}
- Get a unit's configuration property.
- Key is one of the following: eof, points.
- The response body contains only the key's value. See USET for information
- about each property.
-
-LIST {unit}
- List the clips associated to the unit.
- The response body consists of two sections - the first section is a single row
- containing the generation number of the playlist associated to the unit (an
- integer starting from 0 which is incremented on each action which changes the
- playlist). The second sections contais a space-delimited row for each clip in the
- units playlistcontaining the following columns:
- - clip index (starts from 0)
- - file name
- - in point
- - out point
- - real length of the files
- - calculated length of file
- When USET points=use is specified (default), the calculated size is (out-in)+1.
- When points are ignored, the real length of the file is returned.
-
-LOAD {unit} {filename} [in out]
- Load a clip into the unit.
- Optionally set the in and out points to the specified absolute frame numbers.
- Sets the current position to the first frame in the clip.
- Preface the filename with '!' to tell the disk reader thread to remove only
- duplicate frames from the tail of its buffer queue (from a previously loaded
- and playing clip). Otherwise, miracle flushes all of its buffers upon LOAD
- to make the effect of LOAD instantaneous. The LOAD !, USET eof=pause, and
- extended USTA information can be used for client-side playlists (see the
- demo programs).
-
-APND {unit} {filename} [in out]
- Append a clip onto the unit's playlist.
- Optionally set the in and out points to the specified absolute frame numbers.
-
-INSERT {unit} {filename} [ [+|-]clip [ in out ] ]
- Insert a clip into the units playlist at the specified clip index or relative
- to the currently playing clip index.
-
-REMOVE {unit} [ [+|-]clip ]
- Removes a clip from the specified clip index or position relative to the
- currently playing clip index.
-
-CLEAN {unit}
- Removes all by the playing clip.
-
-MOVE {unit} [+|-]clip [ [+|-]clip ]
- Move a clip in the playlist to position specified or position relative to the
- currently playing clip.
-
-PLAY {unit} [speed]
- Commence unit playback from the current position.
- The default speed is 100% if not specified.
- Speed is represented as a percentage value multiplied by 10. Therefore
- the default playback speed is 1000 (1X or 100%), 2X is 2000.
- Negative speed values play in reverse.
-
-STOP {unit}
- Terminate the unit playback resulting in no video being sent.
-
-PAUSE {unit}
- Pause the unit playback causing the current frame position to he held
- indefinitely.
-
-REW {unit}
- Rewind the unit.
- If the unit it playing, then REW sets the playback speed to 2000
- (200%).
- If the unit is stopped, then the frame position is reset to the first
- frame. First frame depends upon the "points" unit configuration property
- and whether an in point has been established for the clip using the SIN
- command.
- Set the currently loaded clip's in point.
- Frame is zero-based and absolute. It is not dependent upon the clip's
- current in point.
- A frame-number of -1, resets the in point to 0.
-
-FF {unit}
- Fast forward the unit.
- If the unit it playing, then FF sets the playback speed to -2000 (200%
- in reverse).
- If the unit is stopped, then the frame position is reset to the first
- frame. First frame depends upon the "points" unit configuration property
- and whether an in point has been established for the clip using the SIN
- command.
-
-STEP {unit} {number-of-frames}
- Adjust the current frame position by the number of frames specified.
- Number-of-frames can accept positive or negative values.
-
-GOTO {unit} {frame-number} [ [+|-]clip ]
- Set the current frame position to frame-number.
- Frame-number is zero-based and absolute within the clip, which means it is
- relative to the file beginning and not the clip in point.
- It does not alter the playback status of the unit.
-
-SIN {unit} {frame-number} [ [+|-]clip ]
- Set the currently loaded clip's in point.
- The in point is the logical starting frame of the clip.
- Frame is zero-based and absolute. It is not dependent upon the clip's
- current in point.
- A frame-number of -1, resets the in point to 0.
-
-SOUT {unit} {frame-number} [ [+|-]clip ]
- Set the currently loaded clip's out point.
- The out point is the logical last frame of the clip.
- Frame is zero-based and absolute. It is not dependent upon the clip's
- current out point.
- A frame-number of -1, resets the out point to the number of frames in
- the file minus 1.
-
-USTA {unit}
- Get the unit status report.
- The response body contains the following fields delimited by spaces:
- - unit number: U0, U1, U2, or U3 without the "U" prefix
- - mode: (offline|not_loaded|playing|stopped|paused|disconnected|unknown)
- "unknown" means the unit has not been added
- "disconnected" means the server has closed a connection to a client running
- STATUS.
- - current clip name: filename
- - current position: in absolute frame number units
- - speed: playback rate in (percent * 10)
- - fps: frames-per-second of loaded clip
- - current in-point: starting frame number
- - current out-point: ending frame number
- - length of the clip
- - buffer tail clip name: filename
- - buffer tail position: in absolute frame number units
- - buffer tail in-point: starting frame number
- - buffer tail out-point: ending frame number
- - buffer tail length: length of clip in buffer tail
- - seekable flag: indicates if the current clip is seekable (relates to head)
- - playlist generation number
- - current clip index (relates to head)
-
- The status contains information based not only on the current frame being
- output (current above) but also based upon the most recent frame read by
- the disk reader thread and added to the tail of the input buffer queue
- (buffer tail above).
-
-XFER {unit} {target-unit}
- Transfer the unit's clip to the target unit.
- The clip inherently includes the in- and out-point information.
- The target unit's "points" configuration property is set to "use."
-
-
-
-
projects / mlt / blobdiff