Appendix A. Multiport Video Computer Protocol (MVCP) Command Summary

The base Video Server Toolkit (VST) software includes a protocol processor, which provides full-featured control of VST via a textual TCP/IP-based protocol called the Multiport Video Computer Protocol, or MVCP.

This appendix describes the MVCP commands.

Protocol Format

MVCP is a simple request/response protocol which is implemented over a TCP byte-stream connection (i.e., a stream socket). The protocol is similar in nature to the FTP control protocol in that requests consist of two- to four-character commands with a varying number of space- delimited arguments terminated by a carriage-return/line-feed.

Responses consist of a textually-represented numeric result code with an associated informational message terminated by a CR/LF. Success is indicated with a response code of the form 2xx. Unless otherwise stated, a command will return the result code 200 if the command is successful.

Unlike FTP, certain MVCP responses may also include a single response line or multiple response lines terminated by a single blank (CR/LF- only) line. The successful result code is 202 if a single response line is returned and 201 if a response list (one or more lines terminated by a blank line) is returned.

All MVCP command arguments and responses are space-delimited. Command or response arguments which contain spaces are surrounded by double quotation marks. In some cases, response arguments that do not contain spaces may be double-quoted, so the application should always be prepared to handle them.


Note: Future enhancements to MVCP may result in additional arguments being added to commands or responses. When new arguments are added to a command, omission of the new arguments will result in the behavior associated with the original command; hence, existing applications will continue to work in a compatible manner.

An application should not depend on the exact number of arguments on a response line returned by an MVCP command as additional arguments may be added as future enhancements to the protocol. An application should expect and process those arguments which it understands but should be prepared to ignore additional arguments which it does not expect and understand.

Unit Management

A single MVCP connection can control multiple VST units (each unit is a logical VTR transport capable of loading, cueing, and playing a clip). MVCP commands which pertain to a specific unit include the unit name as the first argument of the request while global commands, commands which do not pertain to a specific unit, do not include a unit name.

For example:

CINF clip1 (global: retrieve clip information)
LOAD U1 CLIP3.DIF OUT (unit: load clip into unit U1)

When the unit name is omitted or specified as '*' with a unit command, the unit most recently created is used. The unit name can be omitted only if the unit command has no required arguments.

Units can either be created (using the UADD command) or opened (using the UOPN command). When a unit is opened, it must have previously been created by another controller (which could be another MVCP control connection or another external control processor such as a station automation system or on-line editor). Of course, due care must be exercised when sharing control of a unit between two controllers. Interfering with a unit owned by one of the VST external protocol processors (e.g., Sony, Louth, Odetics) will lead to unpredictable behavior.

Establishing an Interactive MVCP Connection

To establish an interactive MVCP connection, use telnet to establish a control connection to the MVCP port on the VST host.

The following example establishes an interactive connection to the MVCP port (which is usually port 5250) on the VST host “originserver.” The MVCP PLS (List Ports) command is run and then the BYE command is used to terminate the control connection:

% telnet originserver 5250 
Trying 133.144.166.34...
Connected to originserver.abc.com.
Escape character is '^]'.
100 VTR Ready
PLS
201 OK
vlan_1 BOTH "VLAN Deck Control" DECK
DIVO_0 BOTH "SGI XT-DIVO Digital Video Option" VID
DIVO_1 BOTH "SGI XT-DIVO Digital Video Option" VID
...
BYE 
200 Goodbye
Connection closed by foreign host.
%

Rules for Using MVCP Commands

The following rules apply to the use of the MVCP commands:

  • The commands are case-sensitive and must be entered exactly as shown in this chapter.

  • All MVCP command arguments are space-delimited. Command arguments that contain spaces should be surrounded by double quotation marks.

  • Each command must end with a carriage return and line feed.

  • The command set is divided into two subsets. One subset contains the global commands, which do not pertain to a specific unit. The other subset contains the unit commands, which pertain to a specific unit. (See “Global Commands” and “Unit Commands” for detailed information about these command subsets.)

  • MVCP commands that pertain to a specific unit contain the unit name as the first argument of the request. Global commands do not include a unit name. For example, the following is a global command that requests information about the clip named “NA40125D.” This command does not have a unit name:

    CINF NA40125D           (get clip information)
    

    The following is a unit command that loads the clip named “NA40125D” for output into the unit identified by “U1”:

    LOAD U1 NA40125D OUT           (load clip into unit U1)
    

  • MVCP responds to each command with a response header line, which is terminated with a carriage return and line feed. All MVCP responses are space-delimited. Response arguments that contain spaces are surrounded by double quotation marks. (See “Response Codes” for information.)


Note: Future enhancements to MVCP may result in additional arguments being added to commands or responses. The additional arguments will be added in such a way that the commands or responses will be backward-compatible with the existing commands or responses, so that existing applications will continue to work correctly.


Command Sets

The protocol command set is divided into two subsets. One subset includes the global commands, those commands which do not pertain to a specific unit. The other subset includes the unit commands.

In general, global commands affect the global state of VST and thus all control connections (through MVCP or other protocols). However, certain commands affect only the connection on which the commands are executed.

Displaying MVCP Commands

One way to learn MVCP commands is to see how they are used in the applications included in VST, such as mcstat, mcpanel, and mcclips. To display in the console window the MVCP commands as they are sent to VST and the MVCP responses as they are received from VST, start the applications with the -v3 option:

# mcpanel -v3

Command Triggers

More precise control of command execution can be accomplished by specifying the time at which a given command should begin execution. This feature is supported only for certain commands such as PLAY, REC, and STOP.


Note: On video devices, command timing is ignored when the unit is not in play or record mode.


Time-of-day triggering

To specify a command time, at the beginning of the command line, include an at-sign (@) followed by the desired time-of-day. Several formats for specifying time are understood:

The timecode form, HH:MM:SS:FF may be used to specify the time relative to midnight local time calculated using current frame rate (which defaults to 29.97 and can be set with FRAT). For instance, 14:14:00:00 specifies that the command should start at exactly 2:14pm local time.

Optionally, the timecode may also include a date by prepending the timecode with yyyymmddT (for example, 19980828T12:34:00:02).

The ISO 8601 date/time form, yyyymmddThhmmss.ssssssZ, may be used to specify the command time.

Finally, the time-of-day form, SEC.USEC, may be used to specify the time using a more traditional UNIX timebase. SEC is the number of seconds since the standard Epoch, Jan 1, 1970. USEC is microseconds.

Example:

LOAD U1 a/COMM OUT
/SEQA CUE U1
/SEQA @17:31:00:02 PLAY U1


Note: f the system is receiving house timecode, command timing will be based on the incoming time; otherwise, the system time will be used.


Response Codes

The MVCP processor responds to all commands with a single response header line. Some commands also return either a single response data line or multiple response data lines. When multiple data lines are returned, they are terminated by a single blank line.

The response header line has the following format:

xxx  message_text 

where

  • xxx is a three-digit decimal response code.

  • message_text is a textual message describing the response.

This response header line may be followed by one or more data lines, depending on the response code.

Each of the following is an example of a response header line:

200 OK
410 Invalid clip time
500 Server error

The following is an example of a response header line that is followed by two data lines: In this example, a blank line follows the second data line.

ULS
201 OK
U1 mvcp/originserver mvp BOTH * DONE IDLE * 0 *
U2 mvcp/originserver mvp BOTH * DONE IDLE * 0 *


Caution: Additional fields may be added as future enhancements to response lines. The additional fields will be added in such a way that the responses will be backward-compatible so that existing applications will continue to work correctly.

The response codes are divided into the following categories:

  • 2xx, successful command execution

  • 4xx, command format or setup errors

  • 5xx, command execution errors

Some error codes have more than one error message. The message depends on the error.

Response Text

200 OK Success with no additional data
201 OK Success with N data lines followed by a blank line
202 OK Success with one data line
400 Command invalid
401 Port name missing
402 Unit name missing
403 Clip not found
403 Unit not found
403 Unit not open
404 Access mode missing or invalid
405 Clip name missing
405 New clip name missing
406 Command not supported
407 Load mode missing or invalid

410 Invalid clip time
411 Event function missing or invalid
412 Clock time missing or invalid
413 Numeric argument missing or invalid
414 Invalid direction
415 <not used>
416 Insertion id missing or invalid
417 Event insertion failed
418 Invalid play speed
418 Invalid speed/count
419 Invalid number of passes

420 Must specify start time
421 Bad create flag
422 Invalid command sync
423 Invalid protection
424 Missing or invalid sort order
425 Missing or invalid time
426 Clip monitor not active
427 Invalid parameter format
428 Node type missing or invalid
429 Invalid event type

432 Too many units specified
433 Invalid timestamp format
434 Frame-rate missing
434 Unable to add clip
435 Filename missing
436 f1f2 has to be in CAP
436 Still-frame mode invalid
436 Frame interleave mode invalid
437 Cannot specify both in and out as relative
438 Unit already open
439 Sync modifier not supported for this command

440 Invalid frame-rate
448 Too many arguments
457 User name missing
458 Password missing
460 Must provide USERname first
500 General error (message varies)
501 Unable to copy clip
501 Unable to find clip in archive
501 Unable to find pending get-from-archive request
501 Unable to issue delete-from--archive request
501 Unable to issue get-from-archive request
501 Unable to issue put-to-archive request
501 Unable to link clip
501 Unable to rename clip

510 General error (message varies)
510 Invalid clip time
511 General error (message varies)
540 Invalid frame-rate
548 Too many arguments

OK Response

After issuing a command, the system may respond, “OK.” This response means that the command has been parsed, not that it has been executed. For example, if you:

LOAD Unit clipName

without a mode or CRTE argument, and clip does not exist, the command returns an “OK,” even though a CRTE is required.

Whether or not the command will succeed depends on things such as:

  • What type of media port is being controlled.

  • Whether or what type of clip is loaded.

  • What state the unit is in.

  • What state the hardware is in.

It is impossible for MVCP to know anything beyond the syntactic validity of a unit command.

One way of getting a response when the command has been executed is to issue the command with /SYNC. For example, if you:

/SYNC LOAD Unit clipName

an error message is returned immediately.

Using P2 Commands with MVCP Commands

You cannot mix MVCP and P2 commands. You must either control a port using only MVCP commands (LOAD/CUER/REC), or the P2 protocol (AUTOEDIT or CUE/PLAY/EDIT_ON/EDIT_OFF).

There is one exception: you can use the following MVCP command to load a new clip onto a port being controlled through P2:

SSET <control-port> vtr.control.clip.name <clip-name>

where control-port can be vtr_1, vtr_2, etc.

Global Commands

Global commands affect the entire system, as opposed to unit commands described in “Unit Commands” that only effect specified units.

There are many different kinds of global commands:

Table A-1 identifies the global MVCP commands that are documented in this section.

Table A-1. Global MVCP Commands

Command

Function

AFND

Locate a clip in an available a StudioCentral 2.0 archive system

AFNG

Locate a pending or in-progress get-from-archive command for a clip

AGET

Retrieve a clip from a StudioCentral 2.0 archive system

ALSG

List the get-from-archive operations that are waiting or being processed

ALSP

List the put-to-archive operations that are waiting or being processed

APUT

Store a clip to a StudioCentral 2.0 archive system

ARM

Delete a clip from a StudioCentral 2.0 archive system

ARMG

Cancel all pending or in-progress get-from-archive operations

BYE

Terminate the current control connection

CADD

Add a clip that has been inserted into the clip cache through an external means

CCHP

Add specified protections to, or remove them from, a clip

CCP

Create a new clip by copying it from an existing clip

CCST

Get the current status of the VST Clip Cache

CEDP

Set the edit points for a clip

CGP

Get clip protections

CIMG

Copy an image to a file

CINF

Get information about a clip

CLN

Create a new clip that shares the clip media content of another clip

CLS

Get a list of all the clips in the VST clip cache

CLSA

List the clips that have been added to the clip cache since the last time the CLSA command was issued or since the CMON command that created this clip monitor was executed

CLSR

List the clips that have been removed from the clip cache since the last time the CLSR command was issued or since the CMON command that created this clip monitor was executed

CMIN

Get the number of clips that have been added to, or removed from, the clip cache

CMON

Initiate monitoring of the clip cache

CMV

Rename a clip

CRM

Delete a clip from the clip cache

CRMA

Delete all clips currently residing in the clip cache

ERR

Get the code and description of the last global error that occurred for a controller

FRAT

Set the frame rate used in translating timecodes for command timing

GTOD

Get the current system time

MON

Place control connections into event monitoring mode

PASS

Sets the password for access control

PLS

Get the list of supported media ports

SGET

Retrieves the values of system controls for the subsystem(s)

SORD

Set the sort order that's used when lists are returned

SSET

Sets system controls for the subsystem

STLS

List statistics

STOD

Set the system time

STST

Calculate various statistics

STZ

Reset statistics

UADD

Create a new unit

ULS

Get a list of the existing VST units

USER

Sets the user for access control


Access Control

This section lists those global commands that deal with system access.

USER *username*

The USER command sets the *username* for access control purposes.

The USER command applies only to the current MVCP connection.

PASS *password*

The PASS command sets the *password* for access control purposes and must follow the corresponding USER command.

The PASS command applies only to the current MVCP connection.

Ports

This section lists those global commands that deal with ports.

PLS

The PLS (List Ports) command returns the list of supported media ports. If successful, the response code is 201 and one response line for each port is returned. The format of each line is:

*name* *mode* "*description*" *type* *port-physical-name*

Where:

  • *name* is the name of the port.

  • *mode* is the port's input/output mode (IN, OUT, or BOTH).

  • *description* is a description of the port.

  • *type* is the type of the port, one of NET (network), VID (video), DECK (deck control), or DISK (disk storage).

  • *port-physical-name* is the physical name of the media port.

For example:

PLS
201 OK
vlan_1 BOTH "VLAN Deck Control" DECK
DIVO_0 BOTH "SGI XT-DIVO Digital Video Option" VID
DIVO_1 BOTH "SGI XT-DIVO Digital Video Option" VID
DIVO_2 BOTH "SGI XT-DIVO Digital Video Option" VID
DIVO_3 BOTH "SGI XT-DIVO Digital Video Option" VID
DIVO_4 BOTH "SGI XT-DIVO Digital Video Option" VID
DIVO_5 BOTH "SGI XT-DIVO Digital Video Option" VID
DIVO_6 BOTH "SGI XT-DIVO Digital Video Option" VID
DIVO_7 BOTH "SGI XT-DIVO Digital Video Option" VID

Units

This section lists those global commands that affect all units in the system.

UADD *media-port-name* *storage-port-name* *port-sharing-mode* [ *owner-info* ]

The UADD (Add Unit) command creates a new unit. The name of the media port accessed by the unit is specified by *media-port-name*. The storage port accessed by the unit is specified by *storage-port- name* (use '*' to specify the default storage system).

Certain media ports must be opened without a storage port (e.g., deck-control ports). Specify 'null' for the storage port to create a unit which does not have a storage port.

The *port-sharing-mode* specifies how access is shared between multiple units accessing the same media port and takes one of the following values: EXCL, SHAR, or CONC.

Exclusive access (EXCL) means only one unit may exist which uses the media port at any given time. If a unit already exists for that port, the UADD will fail.

Shared access (SHAR) means multiple units may be created which all access the same port; however, only one unit may actually use the hardware at any given time. Shared access is only available on media ports which support it (in their interface module).

Concurrent access (CONC) means multiple units may use the media port at the same time. This mode is used most commonly on multiplexed networking ports (such as ATM).

The *owner-info* is optional and sets the owner info for the new unit. The owner info is included in certain status commands such as UINF, UGIN, and ULS.

If the unit is successfully created, the response code is 202 and a single response line is returned containing the name of the newly created unit.


Note: An application must not make any assumptions about the name of the unit including the format of the name. Unit naming is subject to change in future releases.


ULS

The ULS (List Units) command returns a list of the existing VST units. A snapshot of the state of each unit is included.

If the ULS command is successful, the response code is 201 and one response line for each unit is returned followed by a blank line. The format of each unit state is:

*name* *owner* *port* *mode* *clip* *status* *function* *location*     *speed* *frame-rate* *command-id*

Where:

  • *name* is the name of the unit.

  • *owner* is the name of the controller that created the unit.

  • *port* is the name of the unit's media port.

  • *mode* is the mode of the media port (IN, OUT, or BOTH).

  • *clip* is the name of the loaded clip ("*" if no clip is loaded).

  • *status* is the status of the current function (BUSY is the initial state, RUN is the running state, DONE is the completed state, ERR is the error state).

  • *function* is the current function: IDLE, LOAD, UNLD (Unload), CUE, CUER (Cue for record), PLAY, STEP, SHTL (Shuttle), REC (Record), PAUS (Pause), STON (StandbyOn), STOP, FF (Fast Forward), REW (Rewind), REVU (Review), EDIT (Edit), RHRS (Rehearse).

  • *location* is the current clip location in the format hours:minutes:seconds:frames. In drop-frame mode, the final colon (:) is replaced by a period (.).

  • *speed* is the current playback speed (1000 = normal 1x speed).

  • *frame-rate* is the frame-rate (in frames/sec) of the current clip. 525-line timing is specified in its approximate form, 29.97.

  • *command-id* is the id of the command currently being processed by the unit.

For example:

ULS
201 OK
U1 mvcp/originserver mvp BOTH * DONE IDLE * 0 *
U2 mvcp/originserver mvp BOTH * DONE IDLE * 0 *

MON [*unit-name* ... ] [ / *event-type* ... ]

The MON (Monitor) command places the current control connection into event monitoring mode. In this mode, a single response line is returned whenever a monitored event occurs. If one or more units are specified, unit events for only the specified units are returned; otherwise, unit events for all units are returned.

A list of one or more event types may be specified (preceded by a single forward slash). The event types are UADD (unit added), URM (unit removed), UCHG (unit state change), ULOC (unit location change), UCTL (unit control change), UERR (unit error), CADD (clip added), CRM (clip removed). Only the specified types of events are returned.

If no event-type list is specified, UCHG, URM, UERR, and UCTL events are returned, and if no units are specified, UADD events are also returned.

Event monitoring is terminated by closing the control connection.

The format of the event response line is one of the following:

UADD *owner* *port* *mode* *port-physical-name*

  • *owner* is the name of the controller that created the unit.

  • *port* is the name of the unit's media port.

  • *mode* is the mode of the media port (IN, OUT, or BOTH).

  • *port-physical-name* is the physical name of the media port controlled by the unit.

CADD *clip* *format* *size* *resident-size* *start* *end* *in* *out* *frame-rate*

  • *clip* is the name of the clip.

  • *format* is the format of the clip.

  • *size* is the size of the clip content in bytes.

  • *resident-size* is the size of the content that is currently resident on the clip cache disk system.

  • *start* is the timecode of the first frame of the clip.

  • *end* is the timecode of the frame after the last frame of the clip.

  • *in* is the current mark-in point of the clip.

  • *out* is the current mark-out point of the clip.

  • *frame-rate* is the frame-rate (in frames/sec) of the current clip.

  • 525-line timing is specified in its approximate form, 29.97.

UOPN *unit-name*

The UOPN (Unit Open) command opens an existing unit and makes it controllable by this MVCP connection.

If the unit is opened successfully, the response code is 202 and a single response line is returned containing the name of the opened unit.


Warning: Opening a unit owned by a Sony, Louth, or Odetics port using MVCP commands (for example, UOPN) causes unpredictable behavior.


Archive Management

This section lists those global commands that deal with archiving clips.

AFND *clip*

The AFND (Find Clip in Archive) command attempts to locate the clip specified by *clip* in an available archive system. If successful, the response code is 201, and a response line is returned for each archive system in which the clip is found. The response format is:

*archive-type* *archive-host*

Where:

  • *archive-type* is the type of archive system.

  • *archive-host* is the specific host name of the archive system containing the specified clip.

For example:

AFND NA1001
201 OK
mediahub mhhost

AFNG *clip*

The AFNG (Find Archive Get) command attempts to locate a pending or in-progress archive get command for the clip specified by *clip*. If found, the response code is 202, and a single response line is returned in the following format:

*clip* *atype* *ahost* *requester* *requested* *started* *eta*

Where:

  • *clip* is the name of the clip.

  • *atype* is the type of archive system.

  • *ahost* is the specific host name of the archive system.

  • *requester* is the name of the controller requesting the clip.

  • *requested* is the time the retrieval was requested.

  • *started* is the time the retrieval was started.

  • *eta* is the time the retrieval is expected to complete.

AGET *clip* [*archive-clip-name* *archive-host*]

The AGET (Get from Archive) command enqueues a get-from-archive operation to retrieve the clip specified by *clip* from an attached archive system. If *archive-clip-name* is not specified or the default *archive-clip-name*, '*', is specified, *clip* will be used.

If *archive-host* is specified, VST attempts to retrieve the clip from only that specific archive. Otherwise, the clip is retrieved from the first archive in which it can be located.

If a get-from-archive operation is already pending for the clip, AGET does not add a new one.

AGET always returns immediately with response code 200.

Archive operations are processed in-order by the VST Archive Manager which can process a configurable number of concurrent operations for each attached archive system.

If the clip cannot be successfully retrieved from the archive, the failure will be logged in the VST status log. In addition, a clip monitor or event monitor will see the failing clip as having been removed from the clip cache.

ALSG The ALSG (List Archive Gets) command lists the get-from-archive operations that are waiting or being processed. The response code is 201, and a single response line is returned for each archive request in the following format:

*clip* *atype* *ahost* *requester* *requested* *started* *eta*

Where:

  • *clip* is the name of the clip.

  • *atype* is the type of archive system.

  • *ahost* is the specific host name of the archive system.

  • *requester* is the name of the controller requesting the clip.

  • *requested* is the time the archive operation was requested.

  • *started* is the time the archive operation was started.

  • *eta* is the time the archive operation is expected to complete.

ALSP

The ALSP (List Archive Puts) command lists the put-to-archive operations that are waiting or being processed. The response code is 201, and a single response line is returned for each archive request in the following format:

*clip* *atype* *ahost* *requester* *requested* *started* *eta*

Where:

  • *clip* is the name of the clip.

  • *atype* is the type of archive system.

  • *ahost* is the specific host name of the archive system.

  • *requester* is the name of the controller requesting the clip.

  • *requested* is the time the archive operation was requested.

  • *started* is the time the archive operation was started.

  • *eta* is the time the archive operation is expected to complete.

APUT *clip* [*archive-clip-name* [*archive-host*]]

The APUT (Put to Archive) command enqueues a put-to-archive operation to store the clip specified by *clip* to an attached archive system. If *archive-clip-name* is not specified or the default *archive-clip-name*, '*', is specified, *clip* will be used.

If *archive-host* is specified, the clip is stored into that specific archive. Otherwise, the clip is stored into the default archive.

If a put-to-archive operation is already pending for the clip, APUT does not add a new one.

If the specified clip does not exist, APUT returns an appropriate error response code. Otherwise, APUT immediately returns response code 200.

Archive operations are processed in-order by the VST Archive Manager which can process a configurable number of concurrent operations for each attached archive system.

If the clip cannot be successfully stored into the archive, the failure will be logged in the VST status log.

ARM *archive-clip-name* [*archive-host*]

The ARM (Delete from Archive) command enqueues a delete-from-archive operation to delete the clip specified by *archive-clip-name* from an attached archive system. If a delete-from-archive operation is already pending for the clip, ARM does not add a new one.

ARM always immediately returns response code 200.

Archive operations are processed in-order by the VST Archive Manager which can process a configurable number of concurrent operations for each attached archive system.

ARMG

The ARMG (Cancel Archive Gets) cancels all pending or in-progress get-from-archive operations.

ARMG always immediately returns response code 200.

Clip Management

This section lists those global commands that deal with clip management.

CADD *clip* [ *format* ]

The CADD (Add Clip) command adds a new clip that has been inserted into the clip cache through an external means. The name of the new clip is specified by *clip*. The format of the clip is specified by *format*. If *format* is not specified, the clip file's *clip.format* attribute will be used, if it exists, or VST will attempt to automatically detect the format of the clip.

The clip media file must be placed in the appropriate location in the clip cache before issuing the CADD command. If the clip format requires an index, the index file must also be placed in the appropriate index directory before issuing the command.


Note: CADD is no longer required to make a clip available to other VST commands (such as loading it into a unit). VST will automatically attempt to locate and add a clip whenever a controller references the clip.

However, CADD may be used to add a clip to VST's internal clip tables such that it will appear in the clip listing returned by CLS. CADD will also generate the appropriate clip-add event messages for controllers that are monitoring the clip cache.

CCHP *clip* {{*+*|*-*}*protection-type* ...}

The CCHP (Change Clip Protection) command adds to and/or removes from the clip specified by *clip* the protections specified by the *protection-type* arguments.

The types of protection include ATTR (Attribute Protect), MV (Rename Protect), REC (Record Protect), and RM (Delete Protect). For example, the command "CCHP NA1001 +RM -ATTR" sets the protection on NA1001 such that the clip cannot be deleted but can have its attributes (such as its edit points) changed.

If successful, the response code is 200.

CCP *clip* *new-clip*

The CCP (Copy Clip) command creates an new clip named *new-clip* by copying the clip specified by *clip*. After the copy is created, there is no association between the new clip and the original clip.

If successful, the response code is 200.


Note: CCP does not realign a clip as it is being copied. For clip formats which require clip alignment that is compatible with the file system on which it is stored (such as the VST VFrame format), if CCP is used to copy a clip between two different file systems, the file systems must have identical major and minor alignments.


CCST

The CCST (Clip Cache Status) command returns the current status of the VST Clip Cache. The response code is 202 and a single response line is returned in the following format:

*num-clips* *bytes-used* *bytes-avail* *bytes-avail-contiguous*

Where:

  • *num-clips* is the number of clips resident in the clip cache.

  • *bytes-used* is the number of bytes used on the storage systems which hold the clip cache.

  • *bytes-avail* is the number of free bytes available on the storage systems which holds the clip cache.

  • *bytes-avail-contiguous* is the number of free bytes available on the storage system which has the greatest amount of free space.

CEDP *clip* *mark-in* *mark-out*

The CEDP (Set Clip Edit Points) command sets the edit points for the clip specified by *clip*. The *mark-in* and *mark-out* arguments are specified in HH:MM:SS:FF format. The new edit points will not be seen by any unit until the clip is loaded (or reloaded). If the clip is already loaded into a unit, the original edit points will apply.

Specifying '*' for *mark-in* or *mark-out* removes the respective edit point.

If the command is successful, the response code is 200.

CGP *clip*

The CGP (Get Clip Protection) command returns the current protection of the clip specified by *clip*.

If successful, the response code is 202, and a single response line is returned which contains a list of the protections currently enabled for the clip. The protections are ATTR (Attribute Protect), MV (Rename Protect), REC (Record Protect), and RM (Delete Protect).

CIMG *clip* *timecode* *interleave* *filename* [*format*]

The CIMG (Create Clip Image) command extracts the image data associated with the frame specified by *timecode* of the clip specified by *clip* and writes the image to the file specified by *filename*.

*interleave* specifies how to construct the image from the two fields of the frame: F1 (odd field only), F2 (even field only), F1F2 (both fields interleave), F1F1 (odd field line-doubled), F2F2 (even field line-doubled).

*format* specifies the image format to use. Possible values are "rice", "rgb", "yuv", "jpeg", and "tiff" (or others as supported by the Image Format Library). If *format* is not specified, the format is inferred from the filename extension (".rice", ".rgb", ".yuv", ".jpg", ".tiff").

For example:

CIMG bigclip 00:01:00:02 F1F2 x.jpg jpeg
200 OK

CINF *clip*

The CINF (Clip Info) command returns the attributes of the clip specified by *clip*. If the clip currently exists in the clip cache, the response code is 202 and a single response line is returned in the following format:

  • *clip* *format* *size* *resident-size* *start* *end* *in* *out* *frame-rate*

  • *clip* is the name of the clip.

  • *format* is the format of the clip.

  • *size* is the size of the clip content in bytes.

  • *resident-size* is the size of the content that is currently resident on the clip cache disk system.

  • *start* is the timecode of the first frame of the clip.

  • *end* is the timecode of the frame after the last frame of the clip.

  • *in* is the current mark-in point of the clip.

  • *out* is the current mark-out point of the clip.

  • *frame-rate* is the frame-rate (in frames/sec) of the clip. 525-line timing is specified in its approximate form, 29.97.

CLN *clip* *new-clip*

The CLN (Link Clip) command creates a new clip named *new-clip* which shares the clip media content of the clip named by *clip*. The clip attributes (such as edit points) of the new clip may be set independently of the original clip.

If the original clip is deleted, the new clip still retains the content of the original clip until the new clip is also deleted.

This command is useful for creating clips which refer to segments of other clips.

If successful, the response code is 200.

CLS The CLS (List Clips) command returns a list of all the clips in the VCP- Recorder clip cache. The response code is 201 and one response line is returned for each clip in the cache. The format of the response line is:

  • *clip* *format* *size* *resident-size* *start* *end* *in* *out* *frame-rate*

  • *clip* is the name of the clip.

  • *format* is the format of the clip.

  • *size* is the size of the clip content in bytes.

  • *resident-size* is the size of the content that is currently resident on the clip cache disk system.

  • *start* is the timecode of the first frame of the clip.

  • *end* is the timecode of the frame after the last frame of the clip.

  • *in* is the current mark-in point of the clip.

  • *out* is the current mark-out point of the clip.

  • *frame-rate* is the frame-rate (in frames/sec) of the clip. 525-line timing is specified in its approximate form, 29.97.

CLSA

The CLSA (List Added Clips> command lists the clips that have been added to the clip cache since the last time the CLSA command was issued (or since the CMON command which created this clip monitor was executed).

Before the CLSA command may be issued by a controller, the CMON (Clip Monitor) command must be issued to initiate monitoring of the clip cache for this controller.

If successful, the response code is 201 and one response line is returned for each newly added clip which contains the clip's name. A blank line terminates the list of clips.

CLSR

The CLSR (List Removed Clips> command lists the clips that have been removed from the clip cache since the last time the CLSR command was issued (or since the CMON command which created this clip monitor was executed).

Before the CLSR command may be issued by a controller, the CMON (Clip Monitor) command must be issued to initiate monitoring of the clip cache for this controller.

If successful, the response code is 201 and one response line is returned for each removed clip which contains the clip's name. A blank line terminates the list of clips.

CMIN

The CMIN (Clip Monitor Info) command returns the number of clips that have been added to and/or removed from the clip cache and will be returned by the CLSA and CLSR commands respectively.

The response code is 200, and a single response line is returned in the following format:

*num-clips-added* *num-clips-removed*

Where:

  • *num-clips-added* is the number of clips that have been added.

  • *num-clips-removed* is the number of clips that have been removed.

CMON

The CMON (Clip Monitor> command initiates monitoring of the clip cache. The CLSA and CLSR commands are used to retrieve, respectively, the clips that have been added to or removed from the clip cache.

If the CMON command is issued for a second or subsequent time, the current list of added and removed clips is discarded and monitoring is initialized again.

The response code is 200.

CMV *clip* *new-clip*

The CMV (Move Clip) command renames the clip specified by *clip* to a new name specified by *new-clip*.

If successful, the response code is 200.


Note: CMV cannot be used to move clips between file systems; use CCP instead.


CRM *clip*

The CRM (Delete Clip) command deletes the clip specified by *clip*. If any units currently have the clip loaded, actual deletion of the clip will be deferred until all units have unloaded the clip.

If the command is successful, the response code is 200.

CRMA

The CRMA (Delete All Clips) command deletes all clips currently residing in the clip cache. Clips which are currently being retrieved from an archive system may or may not be deleted depending on the progress of the retrieval.

If the command is successful, the response code is 200.

System Controls

This section lists those global commands that deal with system controls.

SGET *subsystem-pattern* *control-name-pattern*

The SGET (System Get Control) command retrieves the values of system controls for the subsystem(s) specified by *subsystem-pattern*. The possible values for *control-name-pattern* are subsystem-dependent and are described elsewhere. If the subsystem or control patterns contains wildcards, the values of all controls that match the specified patterns will be returned.

If successful, response code is 201, and one response line is returned for each matching control in the following format:

*subsystem-name* *control-name* "*control-value*"

SSET *subsystem-name* *control1-name* *control1-value* ...

The SSET (System Set Control) command sets system controls for the subsystem specified by *subsystem-name*. For each control, a name and a value must be provided. At least one control name/value pair must be specified. If the control value contains any spaces or tabs, the value must be enclosed in double quotes.

The possible values for *control-name* and *control-value* are subsystem-dependent and are described elsewhere.

Statistics

This section lists those global commands that deal with statistics gathering.

STLS [ *component-pattern* [ *statistic-pattern* ]]

The STLS (List Statistics) command lists the component name, statistic name, and current value of each statistical value matching the specified patterns.

If the command is successful, the response code is 201, and a response line is returned for each matching statistical value in the following format:

*component-name* *statistic-name* *value* ...

Where:

  • *component name* is the name of the instance of the component that is generating the statistic.

  • *statistic name* is the name of the statistical value.

  • *value* is the current value of the integer or floating-point statistic. The value of certain types of statistics (e.g., histogram) may include more than one number.

STST [*component-pattern* [*statistic-pattern*]]

The STST (Statistics Statistics) command calculates various statistics over all of the statistical values matching the specified patterns.

If the command is successful, the response code is 202, and a single response line is returned in the following format:

*values* *samples* *min* *max* *sum* *mean* *stddev*

Where:

  • *values* is the number of statistical values matching the pattern.

  • *samples* is the total number of samples collected.

  • *min* is the minimum value.

  • *max* is the maximum value.

  • *sum* is the sum of the values.

  • *mean* is the mean of the values.

  • *stddev* is the standard deviation of the values.

STZ [*component-pattern* [*statistic-pattern*]]

The STZ (Statistics Reset) command resets the values of all the statistics matching the specified patterns.

Miscellaneous

This section lists all global commands not coverecd in the previous sections

BYE

The BYE command terminates the current control connection.

ERR

The ERR command returns the code and description for the last global error that occurred for this controller. Errors that occur on units are retrieved using the UERR command. This command returns errors for all Clip Management commands and other commands which do not pertain to a specific unit.

The response code is 202, and a single response line is returned in the following format:

*code* "*description*"

Where:

  • *code* is the error code.

  • *description* is the error description.

FRAT *frame-rate*

The <FRAT> (Frame Rate) command sets the frame rate used in translating timecodes for command timing. The *frame-rate* is specified as frames per second. Supported values are 24, 25, 29.97, and 30.

The FRAT command applies only to the current MVCP connection.

GTOD

The GTOD (Get Time-of-Day) command returns the current VST system time. The response code is 202, and a single response line is returned with three forms of the current time (time code, ISO 8601, and Unadjusted System Time):

*hh:mm:ss:ff* *yyyymmddThhmmss.ssssssZ* *UST*

For example:

GTOD
202 OK
14:24:01.11 19980105T222400.890307Z 94038459071434

SORD *order-type*

The SORD (Set Sort Order) command sets the type of ordering used when lists are returned. The possible values of *order-type* are NAME, which sorts lists by clip name, and TIME, which sorts lists by creation time.

STOD *time*

The STOD (Set Time-of_Day) command sets the VST system time as specified by *time* which is specified either as a time code (hh:mm:ss:ff) or in the ISO 8601-compatible format (yyyymmddThhmmss.ssssssZ).

Unit Commands

The unit commands all have as their first argument the name of unit to which the command is to be applied.

Table A-2 identifies the MVCP unit commands that are described in this section. .

Table A-2. MVCP Unit Commands

Command

Function

CUE

Cue for playback the clip currently loaded in a unit

CUER

Cue for recording the clip currently loaded in a unit

EDIT

Cue for recording and then begin recording

FCLR

Erase the audio and video from specified frames in a clip

FF

Fast forward the unit

FINS

Move frames within a clip

FNEW

Insert blank frames within a clip

FOVR

Overwrite frames within a clip

FRM

Remove frames from within a clip

GET

Get the values of controls

GOTO

Jump a unit's transport to a specified location

JOG

Move a unit forward or reverse by the number of frames

LIMS

Modify the edit limits being used by the current playback or record function

LOAD

Load a clip into a unit

PAUS

Pause a unit

PLAY

Begin playback on a unit

REC

Begin recording on a unit or resume normal recording after a PAUS command

REVU

Do the equivalent of a cue for playback and then begin playing

REW

Fast reverse the unit

RHRS

Cue for playback and then begin playing, with the media port switched to end-to-end mode for playback

RSUM

Resume playback or recording

SET

Set controls for the unit

SHTL

Shuttle a unit at a specified speed

STON

Sets the speed of the unit specified.

STON

Halts playback but does not decue the unit.

STOP

Stop playback or recording on a unit

UCLS

Close an opened or created unit

UERR

Get the code and description of the last error that occurred on a unit

UFLS

Flush the command queue for a unit

UGIN

Get the owner and port information for a unit

UINF

Get the owner and port information for a unit

UINT

Interrupt the command currently being processed by a unit

ULOC

Return the current transport location

UNLD

Unload the clip currently loaded in a unit

UOPN

Open an existing unit and make it controllable

USTA

Get the status of a unit

USYN

Set the default synchronization mode for a unit specified

UUWT

Synchronize command execution between two units

UWAT

Wait for the completion of the last command that was issued to a unit

Before you can use these unit commands, you must either create the unit or open it, according to the following:

  • When you want to use a unit that does not already exist, you create the unit using the global UADD command.

    When you create the unit, you identify the media port and you specify the port access mode, which determines how access is shared among multiple units that access the same media port. You can specify exclusive access, shared access, or concurrent access of the media port.

    When you create the unit it is automatically opened.

  • When you want to share a unit that has already been created, you open the unit using the global UOPN command.

    When you open a unit, it must have previously been created by another control port. Units can be shared with either another MVCP control connection or with another external control processor, such as a station automation system.


    Caution: Extreme care must be exercised when sharing control of a unit between two controllers. Interfering with a unit owned by one of the automation protocol processors (for example, a Louth controller) leads to unpredictable behavior.


Unit Command Modes

The VST units execute asynchronously with the control processors that are controlling them. How the MVCP control processor interacts with the units it controls and the client application that is issuing the MVCP commands is determined by the command synchronization processing. By default, when a command is issued to a unit, the unit's command queue is immediately flushed of any commands which are waiting to be executed by the unit, and the command preempts the previous command that was issued to the unit, even if that command has not completed executing. Also by default, the MVCP control processor returns a response to the client as soon as the command has been queued for the unit, so the OK response to a command means only that the command was successfully queued, not that the command completed successfully or has even started executing.

Synchronization Mode

The synchronization mode determines when the MVCP control processor returns a command response to the MVCP client. The available synchronization modes are: ASYN (async), SYNI (sync-init), SYNR (sync-run), and SYNC (sync-complete). Async (ASYN) mode is as has been described: the control processor responds as soon as the command is queued.

Sync-init (SYNI) mode delays the response until the unit has reached the initialization state on the command. This does not mean that the unit has begun to process the command, and in fact it may have to wait for a shared resource (such as the media port) to become available before it can continue.

Sync-run (SYNR) mode delays the response until the unit has reached the "running" state on the command. This means that the unit is actively processing the command. For instance, the running state for a PLAY command means that video is actually being played.

Sync-complete (SYNC) mode delays the response until the unit has reached the "complete" state on the command. This means that the unit will do no further processing for this command. If the command is CUE, the complete state is reached when the unit has been fully cued and is ready to being playback. If the command is PLAY, the complete state is reached when playback has finished.

If no error occurs in the unit before the desired sync state has been reached, the response code is 200 (or 201, or 202, as appropriate). If an error occurs before the unit reaches the desired state, a 5XX error response code will be returned.

The default command synchronization mode for a unit may be changed using the USYN command. Or, the default may be overridden on a individual command basis by prepending a forward slash (/) and the sync mode to the unit command. For example, the command "PLAY U5" uses the default sync mode, while the command "/SYNC PLAY U5" specifies that the command response should not be sent until the PLAY command has completed executing.

Command Sequencing

Command sequencing refers to the way in which consecutive commands are issued to and processed by the target unit. There are two variables which determine how a command is issued and processed: the preemption mode and the queuing mode.

Preemption

The preemption mode determines whether a command will preempt the previous command or wait for the previous command to reach a certain status before being executed by the unit. Preemption is controlled by both the "previous" command and the "next" command.

The "previous" command may be issued with a qualifier that defers execution the "next" command until the "previous" command has reached a certain status. The "next" command may be issued with a qualifier that defers its execution until the "previous" command has reached a certain status.

The preemption modes available for the "previous" command are NNO (no deferral), NINI (defer next until Init), NRUN (defer next until Running), NCMP (defer next until Complete).

The preemption modes available for the "next" command are PNO (no deferral), PINI (defer until previous Init), NRUN (defer until previous Running), NCMP (defer until previous Complete). POVR may also be used to override the defer-next preemption mode of the "previous" command.


Note: The IMM and SEQ qualifiers have been superceded by the new preemption qualifiers, but are still supported for compatibility. IMM corresponds to PNO and SEQ corresponds to PCMP.


Queuing

The queuing mode determines whether a command is placed at the beginning of the unit command queue (making it the next command to be executed), placed at the end of the command queue (making it the last command), or whether the command queue is flushed before adding the new command. The available queuing modes are prepend (PRE), append (APP), and flush (FLSH).

The default command sequencing is flush/no-defer-next/no-defer- previous, meaning that when an MVCP command is issued, the unit command queue is flushed and the command preempts whatever command is currently being executed by the unit.

The default command sequencing mode for a unit may be changed using the USYN command. Or, the default may be overridden on a individual command basis by prepending a forward slash (/) and the sequencing mode to the unit command. For example, the command "PLAY U5" uses the default sequencing mode, while the command "/APP PLAY U5" specifies that the command should be appended to the unit's command queue.

The default preemption and queuing modes are overridden individually. For example, "/APP /PCMP PLAY U5" places the PLAY command at the end of the command queue and the command does not begin executing until the previous command has completed.

Three common sequencing combinations can be abbreviated:

  • /SEQA is equivalent to /APP /PCMP.

  • /IMMP is equivalent to /PRE /PNO.

  • /IMMF is equivalent to /FLSH /PNO.

Unit Commands

This section lists the commands that affect specific units.

CUE [ *unit-name* [ *in* [ *out* [ *direction* [ *passes* ]]]]]

The CUE (Cue For Play) command cues for playback the clip currently loaded in the unit specified by *unit-name*. If *in* is specified, the clip is cued at the specified frame. If *in* is missing or specified as '*', the mark-in point stored with the clip is used, or if mark-in is not set, the first recorded frame of the clip is used.

If *out* is specified, the clip is cued with the specified out point, meaning playback will terminate at the specified frame. If *out* is missing or specified as '*', the mark-out point stored with the clip is used, or if mark-out is not set, no out point is used.

If *out* is specified, *in* must be specified.

If either *in* or *out* is specified, the other may be specified as a duration by adding a '+' prefix character. For example "1:00:01:00 1:00:06:00", "1:00:01:00 +5:00", and "+5:00 1:00:06:00" all refer to the same edit range.

The optional *direction* argument specifies the playback direction: FWD is forward, BWD is backward, F/B is forward followed by backward, B/F is backward followed by forward. The default direction is forward (FWD).

The optional *passes* argument specifies how many passes through the clip are made. The default is 1 pass. Specify passes as 0 to repeat indefinitely (use the STOP command to stop).

If *passes* is specified as -1, the unit is cued in free-range mode (only on media devices that support free-range cueing). In free-range mode, the *in* point is used only as the initial location but does not define the lower limit of playback. The lower limit is defined by the vtr.media.clip.limit.start control, if set, or the start of the clip if the clip limit control is not set.

In free-range mode, the upper limit of playback is defined by the specified out-point. If the out-point is not set, the upper limit is defined by the vtr.media.clip.limit.end control, if set, or the end of the clip if the clip limit control is not set.

CUER [ *unit-name* [ *in* [ *out* ]]]

The CUER (Cue For Record) command cues for recording the clip currently loaded in the unit specified by *unit-name*. If *in* is specified, the clip is cued at the specified frame. If *in* is missing or specified as '*', the unit cues to the mark-in point stored with the clip or if mark-in is not set.

If *out* is specified, the clip is cued with that out-point, meaning recording will terminate at the specified frame. If *out* is missing or specified as '*', recording will continue until the unit is stopped. if *out* is specified, *in* must be specified.

If either *in* or *out* is specified, the other may be specified as a duration by adding a '+' prefix character. For example "1:00:01:00 1:00:06:00", "1:00:01:00 +5:00", and "+5:00 1:00:06:00" all refer to the same edit range.

EDIT [ *unit-name* [ *in* [ *out* ]]]

The EDIT (Edit) command performs an auto-edit for the edit range *in* *out*. The unit prerolls for the duration specified by the setting of the vtr.edit.preroll control and postrolls for the duration specified by the vtr.edit.postroll control.

FCLR *unit-name* *in* *out*

The FCLR (Clear Frames) command clears (erases) the frames of the clip loaded into the unit specified by *unit-name* from the frame specified by *in* (inclusive) to the frame specified by *out* (exclusive). The video and audio associated with the cleared frames is removed, but the frames themselves remain. This contrasts with FRM which removes the frames, closing the hole in the clip. The clip must be loaded for input (IN) or input/output (BOTH).

FF [ *unit-name* ]

The FF (Fast Forward) command fast forwards the unit specified by *unit-name*. The fast forward speed is device-dependent.

FINS *unit-name* *source-in* *source-out* *dest-in*

The FINS (Insert Frames) command moves the frames in the range *source-in* to *source-out* of the clip loaded into the unit specified by *unit-name*, inserting them at the point specified by the timecode *dest-in*. The frames are removed from the original location, and the duration of the clip remains the same. The clip must be loaded for input (IN) or input/output (BOTH).

FNEW *unit-name* *in* *out*

The FNEW (Insert New Frames) command inserts blank frames into the clip loaded into the unit specified by *unit-name* between the frame specified by *in* (inclusive) and *out* (exclusive). FNEW opens a hole in the clip, and the duration of the clip will increase. The clip must be loaded for input (IN) or input/output (BOTH).

FOVR *unit-name* *source-in* *source-out* *dest-in*

The FOVR (Overwrite Frames) command moves the frames in the range *source-in* to *source-out* of the clip loaded into the unit specified by *unit-name*, overwriting the frames starting at the timecode specified by *dest-in*. The frames are removed from the original location. The duration of the clip will decrease, though if the source and target overlap, the duration will decrease by a fewer number of frames than are represented by the source range. The clip must be loaded for input (IN) or input/output (BOTH).

FRM *unit-name* *in* *out*

The FRM (Remove Frames) command removes the frames of the clip loaded into the unit specified by *unit-name* from the frame specified by *in* (inclusive) to the frame specified by *out* (exclusive). This command removes the frames altogether, moving the frames after the removed frames down in the timeline to close the hole. This contrasts with FCLR which simply erases the video and audio associated with the frames but does not remove the frames themselves.

The clip must be loaded for input (IN) or input/output (BOTH).

GET *unit-name* *dev-type* *control-name-pattern* ...

The GET (Get Control) command retrieves the values of device controls for the unit specified by *unit-name*. The *dev-type* specifies whether the controls are queried in the media (MED) or storage (STOR) device assigned to the unit.

The possible values for *control-name-pattern* are device- dependent and are described elsewhere. If the pattern contains wildcards, the values of all controls that match the specified pattern will be returned.

If successful, response code is 201, and one response line is returned for each matching control in the following format:

*control-name* "*control-value*"

The following example gets the values of the device controls that begin with “vtr.media.clip” for unit U1:

GET U1 MED vtr.media.clip* 
201 OK
vtr.media.clip.limit.end "*"
vtr.media.clip.preset.start "01:00:00:00"
vtr.media.clip.limit.start "*"
vtr.media.clip.format "movie/vframe"

GOTO *unit-name* *timecode*

The GOTO (Goto) command jumps the unit transport specified by *unit-name* to the location specified by *timecode*. The unit transport continues the function that is was executing starting at the target of the Goto command.

STEP [ *unit-name* [ *frames* ]]

The STEP (Step) command steps the unit specified by *unit-name* by the number of frames specified by *frames* (1 frame, if not specified). Positive numbers step forward. Negative numbers step backward. If the distance specified by *frames* takes the unit past the current edit limits, the unit will stop (or pause, if the unit is configured to pause instead).

Some media ports require that the unit already be in a playback state when STEP is issued.

LIMS *unit-name* *in* [*out* [*direction* [*passes*]]]

The LIMS (Set Edit Limits) command modifies the edit limits being used by the current playback or record function. Which edit parameters may be changed is device-dependent. In general, only the out-point may be changed as a way to stop playback or recording at a specific point even if the unit was cued without a out-point.

LOAD *unit-name* *clip* [*load-mode*]

The LOAD (Load Clip) command loads the clip specified by *clip* into the unit specified by *unit-name*. The *load-mode* indicates whether the clip is being loaded for input (IN), output (OUT), or both input and output (BOTH). The default is output (OUT).

If successful, the response code is 202 and a single response line is returned in the following format:

  • *format* *size* *resident-size* *start* *end* *in* *out* *frame- rate*

  • *format* is the format of the clip.

  • *size* is the size of the clip content in bytes.

  • *resident-size* is the size of the content that is currently resident on the clip cache disk system.

  • *start* is the timecode of the first frame of the clip.

  • *end* is the timecode of the frame after the last frame of the clip.

  • *in* is the current mark-in point of the clip.

  • *out* is the current mark-out point of the clip.

  • *frame-rate* is the frame-rate (in frames/sec) of the clip. 525- line timing is specified in its approximate form, 29.97.

PAUS [ *unit-name* ]

The PAUS (Pause) command pauses the unit specified by *unit- name*. The unit must be in a playback or record state. The RSUM, PLAY, STEP, SHTL, FF, or REW commands are used to resume playback. The RSUM or REC commands are used to resume recording.

If the unit is playing, the video output will be a still frame at the paused clip location.

PLAY [ *unit-name* [ *speed* ]]

The PLAY command begins (or resumes) playback on the unit specified by *unit-name*. If *speed* is not specified, normal playback speed, 1000, is used. Some media ports may support other playback speeds.

Some media ports must be explicitly cued before starting playback. For those devices, PLAY cannot be used to resume playback after a STOP command is issued. The unit must be re- cued.

REC *unit-name*

The REC (Record) command begins recording on the unit specified by *unit-name*. REC can also be used to resume normal recording after a PAUS command. Some media ports must be explicitly cued before starting recording. For those devices, REC cannot be used to resume recording after a STOP command is issued. The unit must be re- cued.

REVU *unit-name* *in* *out*

The REVU (Review) command performs a edit review for the edit range *in* to *out*. The unit prerolls for the duration specified by the setting of the vtr.edit.preroll control and postrolls for the duration specified by the vtr.edit.postroll control.

REW *unit-name*

The REW (Rewind) command rewinds the unit specified by *unit- name*. The rewind speed is device-dependent and may be settable with a control.

RHRS *unit-name* *in* *out*

The RHRS (Rehearse) command performs an auto-edit for the edit range *in* *out*, but during the actual edit range switches the output to E-to-E mode rather than recording. The unit prerolls for the duration specified by the setting of the vtr.edit.preroll control and postrolls for the duration specified by the vtr.edit.postroll control.

RSUM [ *unit-name* ]

The RSUM (Resume) command resumes the playback or recording function that was paused by a PAUS command on the unit specified by *unit-name*.

SET *unit-name* *dev-type* *control1-name* *control1-value* ...

The SET (Set Control) command sets device controls for the unit specified by *unit-name*. The *dev-type* specifies whether the controls are to be set in the media (MED) or storage (STOR) device assigned to the unit.

For each control, a name and a value must be provided. At least one control name/value pair must be specified. If the control value contains any spaces or tabs, the value must be enclosed in double quotes.

The possible values for *control-name* and *control-value* are device-dependent and are described elsewhere.

The following example sets the value of a storage control for unit U1 so that frames are automatically cleared from the clip after being played:

SET U1 STOR vtr.storage.fs.clear_after_play true 
200 OK

SHTL *unit-name* *speed*

The SHTL (Shuttle) command shuttles the unit specified by *unit- name* at the speed specified by *speed*. A speed of 1000 is normal 1x speed. The speed scale is linear, so a speed of 100 is 1/10th normal speed and a speed of 10000 is 10x speed.

Positive speeds play forward. Negative speeds play backward.

The actual shuttle speeds available are device-dependent.

SSPD *unit-name* *speed*

The SSPD (Set Speed) command sets the speed of the unit specified by *unit-name* to the speed specified by *speed*. SSPD is used to change speeds without changing the current unit transport function (either PLAY or SHTL).

STON [ *unit-name* ]

The STON (Standby On) command halts playback but does not stop the unit. This releases the output port for use by another unit, but allows the unit to resume playback quickly when a new playback command arrives.

STON is supported by only some media ports.

STOP [ *unit-name* ]

The STOP (Stop) command stops playback or recording.

For some media ports, playback or recording cannot be resumed until the unit is re-cued with a CUE or CUER command, respectively.

UCLS [ *unit-name* ]

The UCLS (Unit Close) command closes an opened or created unit. This controller's access will be terminated, and if no other controllers have the unit open, the unit will be deleted.

If the command is successful, response code 200 is returned.

UERR *unit* *error-code* "*error-message*"

  • *unit* is the name of the unit.

  • *error-code* is the code of the error.

  • *error-message* is the textual error message.

UERR [ *unit-name* ]

The UERR (Unit Error) command returns the code and description for the last error that occurred on the specified unit.

If the command is successful, the response code 202 is returned followed by a data line:

*code* "*description*"

Where:

  • *code* is the error code of the last error.

  • *description* is a textual description of the error.

UFLS [ *unit-name* ]

The UFLS (Flush Unit) command flushes the command queue for the unit specified by *unit-name*.

UGIN *unit-name*

The UGIN (Get Unit Info) command returns the owner and port information for the unit specified by *unit-name*. The specified unit does not need to be opened by the current control connection (the UINF returns the identical information for an opened unit).

If the unit exists, the response code is 202 and a single response line is returned with this format:

*owner* *port-name* *port-mode* *port-physical-name*

Where:

  • *owner* is the name of the controller that created the unit.

  • *port-name* is the name of the media port controlled by the unit.

  • *port-mode* is the input/output mode supported by the unit. The possible values are IN, OUT, and BOTH.

*port-physical-name* is the physical name of the media port controlled by the unit.

UINF [ *unit-name* ]

The UINF (Get Unit Info) command returns the owner and port information for the unit specified by *unit-name*. The unit must be opened (or created) by the current controller.

The response code is 202 and single response line is returned in the following format:

*owner* *port-name* *port-mode* *port-physical-name*

Where:

  • *owner* is the name of the controller that created the unit.

  • *port-name* is the name of the media port controlled by the unit.

  • *port-mode* is the input/output mode supported by the unit. The possible values are IN, OUT, and BOTH.

  • *port-physical-name* is the physical name of the media port controlled by the unit.

UINT [ *unit-name* ]

The UINT (Unit Interrupt) command interrupts the command currently being processed by the unit specified by *unit-name*. The command will be terminated with error EINTR.

ULOC *unit* *location*

  • *unit* is the name of the unit.

  • *location* is the current clip location in the format hours:minutes:seconds:frames. In drop-frame mode, the final colon (:) is replaced by a period (.).

  • UCTL *unit* *control-name* "*control-value*"

  • *unit* is the name of the unit.

  • *control-name* is the name of the control.

*control-value* is the new value of the control.

ULOC [ *unit-name* ]

The ULOC (Unit Location) command returns the current transport location for the unit specified by *unit-name*. The response code is 202 and a single response line is returned in the following format:

*clip-loc* *vitc* *ltc* *UTC-time* *UST-time*

Where:

  • *clip-loc* is the clip location, which roughly corresponds to a CTL (control track) timecode.

  • *vitc* is the VITC (vertical interval timecode) of the frame.

  • *ltc* is the LTC (longitudinal timecode) of the frame.

  • *UTC-time* is the UTC time when the unit was at the specified location. This time can be used to account for application or network latency in time reporting. This time is reported in the ISO 8601-compatible format: yyyymmddThhmmss.ssssssZ.

  • *UST-time* is the UST (unadjusted system time) time when the unit was at the specified location. This time can be used to account for application or network latency in time reporting.

UNLD [ *unit-name* ]

The UNLD (Unload Clip) command unloads the clip currently loaded in the unit specified by *unit-name*. If successful, the response code is 200.

URM *unit*

  • *unit* is the name of the unit.

  • UCHG *unit* *clip* *status* *function* *location* *speed* *frame- rate* *command-id*

  • *unit* is the name of the unit.

  • *clip* is the name of the loaded clip ("*" if no clip is loaded).

  • *status* is the status of the current function (BUSY is the initial state, RUN is the running state, DONE is the completed state, ERR is the error state).

  • *function* is the current function: IDLE, LOAD, UNLD (Unload), CUE, CUER (Cue for record), PLAY, STEP, SHTL (Shuttle), REC (Record) , PAUS (Pause), STON (StandbyOn), STOP, FF (Fast Forward), REW (Rewind), REVU (Review), EDIT (Edit), RHRS (Rehearse).

  • *location* is the current clip location in the format hours:minutes:seconds:frames. In drop-frame mode, the final colon (:) is replaced by a period (.).

  • *speed* is the current playback speed (1000 = normal 1x speed).

  • *frame-rate* is the frame-rate (in frames/sec) of the current clip. 525-line timing is specified in its approximate form, 29.97.

  • *command-id* is the id of the command currently being processed by the unit.

USTA [ *unit-name* ]

The USTA (Unit Status) command returns the status of the unit specified by *unit-name*. The unit my be opened (or created) by the current controller.

If successful, the response code is 202, and a single response line is returned in the following format:

  • *clip* *status* *function* *location* *speed* *frame-rate* *command-id*

  • *clip* is the name of the loaded clip ("*" if no clip is loaded).

  • *status* is the status of the current function (BUSY is the initial state, RUN is the running state, DONE is the completed state, ERR is the error state).

  • *function* is the current function: IDLE, LOAD, UNLD (Unload), CUE, CUER (Cue for record), PLAY, STEP, SHTL (Shuttle), REC (Record) , PAUS (Pause), STON (StandbyOn), STOP, FF (Fast Forward), REW (Rewind), REVU (Review), EDIT (Edit), RHRS (Rehearse).

  • *location* is the current clip location in the format hours:minutes:seconds:frames. In drop-frame mode, the final colon (:) is replaced by a period (.).

  • *speed* is the current playback speed (1000 = normal 1x speed).

  • *frame-rate* is the frame-rate (in frames/sec) of the current clip. 525-line timing is specified in its approximate form, 29.97.

  • *command-id* is the id of the command currently being processed by the unit.

USYN [ *unit-name* ]

The USYN (Set Unit Synchronization) command sets the default command synchronization mode for the unit specified by *unit- name*. The mode is set as specified by the sync-mode qualifiers which precede the command name. See the section UNIT COMMAND SYNCHRONIZATION below for more information.

Once the USYN command has been used to set the default sync mode, all unit commands which do not specify a sync mode will use this default.

UUWT *unit-name* *wait-unit-name* *sync-mode* [ *wait-id* ]

The UUWT (Unit-Unit Wait) command provides a mechanism for synchronizing command execution between two units. The unit specified by *unit-name* waits until the unit specified by *wait-unit-name* reaches the execution status specified by *sync-mode* for the command specified by *wait-id*.

For the possible values of *sync-mode*, see the section UNIT COMMAND SYNCHRONIZATION below. Both units must be opened by the current control connection.

If *wait-id* is not specified, the unit waits for the command at the end of the target unit's command queue when the UUWT starts execution in the unit (not when the UUWT is issued to the unit).

The target command id can be obtained by using the /CID qualifier on the target unit command.

UWAT [ *unit-name* [ *sync-mode* ]]

The UWAT (Unit Wait) command waits for the last command issued to the unit specified by *unit-name* according to the synchronization mode specified by *sync-mode* or the default sync mode if the *sync-mode* argument is not provided.

For the possible values of *sync-mode*, see the section UNIT COMMAND SYNCHRONIZATION below.