Chapter 4. MVCP Reference
Prev |  | Next

## Chapter 4. MVCP Reference

This chapter contains detailed information about using the Silicon Graphics Multiple-Unit Video Computer Protocol (MVCP) command set. MVCP enables full-featured control of VCP-Recorder using a TCP/IP stream connection.

The MVCP commands are used by applications written specifically for use with VCP-Recorder. The commands can also be used by establishing an interactive VCP-Recorder connection, as discussed in “Establishing an Interactive MVCP Connection”. This is useful for interactive testing of features of VCP-Recorder.

The following topics are discussed in this chapter:

- “Using the MVCP Commands”

- “MVCP Global Commands”

- “MVCP Unit Commands”

## Using the MVCP Commands

This section contains general information about using the MVCP commands. The following topics are discussed:

- “Establishing an Interactive MVCP Connection”

- “Rules for Using MVCP Commands”

- “About MVCP Timecodes”

- “MVCP Responses”

- “Synchronization of Unit Commands and Responses”

- “Command Timing”

| Note: MVCP is similar in operation to that of `ftpd`, with the exceptions that are noted in this section.

### Establishing an Interactive MVCP Connection

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

The following example establishes an interactive connection to the MVCP port (which is usually port 5250) on the VCP-Recorder 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 are those commands that do not pertain to a specific unit. The other subset contains the unit commands, which are those commands that pertain to a specific unit. (See “MVCP Global Commands” and “MVCP 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 “MVCP Responses” 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.

### About MVCP Timecodes

Timecodes are used in MVCP commands to indicate

- a clip's frame number and edit points (see individual commands described in “MVCP Global Commands” and “MVCP Unit Commands”)

- the time of day (see “STOD (Set System Time)”)

- the time at which a command should be executed (see “Command Timing”)

These MVCP timecodes are specified in the following 24-hour format:

[[[hh:]mm:]ss:]ff

where hh is the hours, mm is the minutes, ss is the seconds, and ff is the frame number. In drop-frame mode, the final colon is replaced by a period (hh:mm:ss.ff ).

When a frame number is specified in a timecode, a frame rate is used to determine the equivalent time. For example, if the frame rate is 30 frames per second, 00:00:00.15 (15 frames) refers to 0.5 seconds. If the frame rate is 25 frames per second, 00:00:00.15 refers to 0.6 seconds.

| Note: When specifying frame numbers and edit points, the frame rate associated with the clip is used. When specifying the time at which a command is executed, the frame rate set by the `FRAT` command is used; the default frame rate (29.97) is used for command timing if the `FRAT` command has not been run.

Examples of timecodes are shown in Table 4-1.

Table 4-1. MVCP Timecode Examples

Timecode | Description
--- | ---
15 | equivalent to 00:00:00:15; actual time depends on frame rate frame numbers and edit points example: if clip frame rate is 25 frames per second, 00:00:00:15 is 0.6 seconds command timing example: if frame rate is 25 frames per second, 00:00:00:15 is 0.6 seconds past midnight
15:00 | equivalent to 00:00:15:00 frame numbers and edit points: 15 seconds command timing: 15 seconds past midnight
15:00.00 | equivalent to 00:15:00.00 frame numbers and edit points: 15 minutes command timing: 15 minutes past midnight
15:00:00.00 | frame numbers and edit points: 15 hours command timing: 15 hours past midnight (3 p.m.)
10:00:00:00 | frame numbers and edit points: 10 hours command timing: 10 hours past midnight (10 a.m.)
00:00:30:15 | actual time depends on frame rate frame numbers and edit points example: if clip frame rate is 30 frames per second, 00:00:30:15 is 30.5 seconds command timing example: if frame rate is 30 frames per second, 00:00:30:15 is 30.5 seconds past midnight

The following examples, which are all equivalent, cue the clip in unit U1 at 15 seconds:

    CUE U1 00:00:15.00
    CUE U1 00:15.00
    CUE U1 15.00

The following example requests that the `PLAY` command be executed at 30 minutes after midnight:

    @30:00:00 PLAY U1

### MVCP Responses

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:

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

| Note: In this example, a blank line follows the second data line.

| 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

#### 2xx Response Codes

A response header line with a 2xx response code indicates the successful completion of the command. Each 2xx response header line may be followed by one or more data lines, according to the following:

- 200 response header lines are not followed by any data lines.

- 201 response header lines are followed by more than one data line. The last data line is followed by a blank line (that is, a line with just a carriage return and line feed).

- 202 response header lines are followed by a single data line.

#### 4xx Response Codes

The 4xx format error codes include the following:

    401 Port name missing
    402 Unit name missing
    403 Port not found
    404 Access mode missing or invalid
    405 Clip name missing
    406 Command not supported
    407 Load mode missing or invalid
    408 <not used>
    409 <not used>
    410 <not used>
    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 speed
    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
    435 Filename missing
    436 Still-frame mode invalid
    437 Cannot specify both in and out as relative

#### 5xx Response Codes

The 5xx execution error codes include the following:

    500 General error (message varies)
    510 General error (message varies)
    511 General error (message varies)

### Synchronization of Unit Commands and Responses

VCP-Recorder unit commands execute asynchronously with the control processors that run them. By default, when a command is issued to a unit, if that command has no format or setup errors, the command queue for that unit is flushed and the new command is placed on the command queue. In other words, the new command preempts all other commands issued to the unit, even if those commands have not completed their execution. Also by default, the MVCP control processor returns its response as soon as the command has been parsed for command format and setup errors and has been placed on the unit's command queue.

This section describes how to modify this default behavior. The following topics are discussed:

- “Changing the Synchronization Mode”

- “Changing Command Sequencing”

#### Changing the Synchronization Mode

The following are the available synchronization modes:

- ASYN, which is async mode. This is the default mode, which behaves as described. That is, the control processor responds as soon as a command is queued.

- SYNI, which is sync-init mode. This mode delays the response to the command 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.

- SYNR, which is sync-run mode. This mode delays the response to the command 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, which is sync-complete mode. This mode delays the response to the command until the unit has reached the “complete” state on the command. This means that the unit does 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 begin 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, 201, or 202, as appropriate. If an error occurs before the unit reaches the desired state, a 5XX error response code is returned.

The default command synchronization mode for a unit can be changed using the `USYN` command. In addition, the default can be overridden on an individual command basis by prepending a forward slash (/) and the sync mode to the unit command. This is shown in the following example, which specifies that the `REC` command should be executed in SYNC mode:

    /SYNC REC U1

| Note: When a unit is first created, its default sync mode is set to ASYN. This default synchronization mode for a unit can be changed by using the unit command `SSYN`. The mode specified in this command is used for all unit commands that do not specify an explicit sync mode.

#### Changing 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 that determine how a command is issued and processed: the preemption mode and the queueing mode.

The preemption mode determines whether a command preempts the previous command or waits for the previous command to complete before being executed by the unit. The available preemption modes are immediate (IMM) and sequential (SEQ). An immediate command preempts the previous command, while a sequential command is not executed until the previous command completes on that unit.

The available queueing modes are PRE (prepend), APP (append), and FLSH (flush). These queueing modes determine whether a command is placed at the beginning of the unit command queue for a unit (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 default command sequencing is flush-immediate, 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.

| Note: If you use the `USYN` command to change the command sequencing mode for a unit, the change applies only to that unit. The change does not apply to other units that may be active.

The default can be overridden on an individual command basis by including a forward slash (/) and the sequencing mode at the beginning of 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 sequencing modes are overridden individually. For example, /APP /SEQ 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 /SEQ

- /IMMP is equivalent to /IMM /PRE

- /IMMF is equivalent to /IMM /FLSH

For example, /APP /SEQ PLAY U5 is equivalent to /SEQA PLAY U5.

### Command Timing

More precise control of command execution can be accomplished by specifying the time at which a given command should begin execution.

| Note: This feature is supported only for unit transport commands, such as `PLAY`, `REC`, and `STOP`. Command timing is ignored on all other commands.

To specify a command time, include an at-sign (@) followed by the desired wall-clock time at the beginning of the command line. Two formats for specifying time are supported:

- The timecode form (hh:mm:ss:ff, or hh:mm:ss.ff in drop-frame mode) can be used to specify the time relative to midnight local time; it is calculated using the current frame rate. (The frame rate defaults to 29.97 and can be set with `FRAT`.) For example, 14:14:00:00 specifies that the command should start at 2:14 p.m. local time.

  See “About MVCP Timecodes” for information about the timecode format.

- The time-of-day form, SEC.USEC, can 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.

The following example loads a clip into a unit, cues the clip for playout, and then plays it at 5:30 p.m. The CUE and

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

| Note: The command timing feature is intended to provide timed control over starting and stopping playback and recording. It is not intended for use in long-term scheduling because delays of more than a few seconds are possible.

## MVCP Global Commands

Table 4-2 identifies the global MVCP commands that are documented in this section.

Table 4-2. MVCP Global Commands

Command | Function
--- | ---
AFND | Locate a clip in an available archive system
AFNG | Locate a pending or in-progress get-from-archive command for a clip
AGET | Retrieve a clip from an 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 an attached archive system
ARM | Delete a clip from an attached 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 VCP-Recorder 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 VCP-Recorder 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
PLS | Get the list of supported media ports
SORD | Set the sort order that's used when lists are returned
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 VCP-Recorder units

### AFND (Find Clip in Archive)

To locate a clip in an attached archive system, use the following command:

    AFND clip-name [archive-host]

where

- clip-name is the name of the clip to be located.

- archive-host is the hostname of the attached archive system that should be searched. If not provided, all attached archive systems are searched.

The `AFND` command attempts to locate the clip specified by clip-name in an attached archive system. If the command is successful, the response code is 201, and a response line is returned for the first archive system in which the clip is found. The response line is in the following format:

    archive-type archive-host

where

- archive-type is the type of archive system.

- archive-host is the specific hostname of the archive system containing the clip.

For example:

    AFND NA1001
    201 OK
    mediahub mhhost

| Note: VCP-Recorder supports multiple MediaHub archive systems. If a specific archive system is not provided on the command, only the first archive host that has the requested clip name is returned, regardless of how many attached archive systems have a clip with that name. To find all the archive systems that have the clip, execute the `AFND` command multiple times, specifying a different archive hostname each time.

### AFNG (Find Archive Get)

To locate a pending or in-progress get-from-archive command for a clip, use the following command:

    AFNG clip-name

where clip-name is the name of the clip in VCP-Recorder.

The `AFNG` command attempts to locate a pending or in-progress get-from-archive command for the clip specified by clip-name. If the archive get command is 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 hostname of the archive system.

- requester is the name of the controller requesting the clip.

- requested is the time the retrieval was requested in ISO 8601 format.

- started is the time the retrieval was started in ISO 8601 format.

- eta is the time the retrieval is expected to complete in ISO 8601 format.

### AGET (Get From Archive)

To retrieve a clip from an archive system, use the following command:

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

where

- clip-name is the clip name in the VCP-Recorder clip cache.

- archive-clip-name is the clip name in the archive system. If archive-clip-name is not specified, or the default archive-clip-name (“*”) is specified, clip-name is used.

  archive-clip-name must be specified if either an archive host is specified or the clip name in the archive system is different from the clip name in VCP-Recorder.

- archive-host is the name of the archive host. If archive-host is specified, VCP-Recorder 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.

The following example gets a clip named “NA1002” from the archive host named “mhhost.” The clip name will be “NA1002” in the VCP-Recorder clip cache:

    AGET NA1002 NA1002 mhhost

This command queues a get-from-archive operation to retrieve the clip specified by clip-name from the specified attached archive system. If a get-from-archive operation is pending for the clip, `AGET` does not add a new one.

If there are no format or setup errors in the command, `AGET` always returns immediately with a response code of 200.

| Note: Archive operations are processed in order by the VCP-Recorder 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 is logged in the VCP-Recorder status log. In addition, a clip monitor or event monitor treats the failing clip as having been removed from the clip cache.

### ALSG (List Archive Gets)

To list the get-from-archive operations that are waiting or being processed, use the following command:

    ALSG

This 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 hostname of the archive system.

- requester is the name of the controller requesting the clip.

- requested is the time the retrieval was requested in ISO 8601 format.

- started is the time the retrieval was started in ISO 8601 format.

- eta is the time the retrieval is expected to completed in ISO 8601 format.

### ALSP (List Archive Puts)

To list the put-to-archive operations that are waiting or being processed, use the following command:

    ALSP

This 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 hostname of the archive system.

- requester is the name of the controller requesting the clip.

- requested is the time the retrieval was requested in ISO 8601 format.

- started is the time the retrieval was started in ISO 8601 format.

- eta is the time the retrieval is expected to complete in ISO 8601 format.

| Note: atype and requester can be null.

### APUT (Put to Archive)

To store a clip to an attached archive system, use the following command:

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

where

- clip-name is the clip name in the VCP-Recorder clip cache.

- archive-clip-name is the clip name in the archive system. If archive-clip-name is not specified, or the default archive-clip-name (“*”) is specified, clip-name is used.

  archive-clip-name must be specified if either an archive host is specified or the clip name in the archive system is different from the clip name in VCP-Recorder.

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

The following example stores a clip named “NA1004” in the archive host named “mhhost.” The clip name will be “NA1002” in the archive host:

    APUT NA1004 NA1002 mhhost

The `APUT` (Put to Archive) command queues a put-to-archive operation to store the clip specified by clip-name to an attached archive system. If a put-to-archive operation is 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.

| Note: Archive operations are processed in order by the VCP-Recorder 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 is logged in the VCP-Recorder status log.

### ARM (Delete From Archive)

To delete a clip from an attached archive system, use the following command:

    ARM archive-clip-name [archive-host]

where

- archive-clip-name is the name of the clip to be deleted.

- archive-host is the name of the archive host. If it is omitted, the first archive system is used.

This command queues 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 pending for the clip, `ARM` does not add a new one.)

If there are no format or setup errors in the command, `ARM` always returns immediately with a response code 200.

Archive operations are processed in order by VCP-Recorder, which can process a configurable number of concurrent operations for each attached archive system.

### ARMG (Cancel Archive Gets)

To cancel all pending or in-progress get-from-archive operations, use the following command:

    ARMG

This command cancels all pending or in-progress get-from-archive operations.

If there are no format or setup errors in the command, `ARMG` always returns immediately with a response code 200.

### BYE

To terminate the current control connection, use the following command:

    BYE

### CADD (Add Clip)

To add a clip that has been inserted into the clip cache through an external means, use the following command:

CADD clip-name [clip-format]

where

- clip-name is the name of the new clip.

- clip-format is the format of the clip. The format of the clip must be specified unless the clip already has the “clip.format” attribute attached.

  This parameter can be one of the following:

  - movie/vframe/uncompressed (uncompressed VCP-Recorder variable-frame format movies)

  - movie/vframe/rice (compressed VCP-Recorder variable-frame format movies using Rice compression)

  - movie/vframe/jpeg (motion JPEG)

  - movie/stream/mpeg/mpeg2/program (MPEG-2 program stream)

  - movie/stream/mpeg/mpeg2/transport (MPEG-2 transport stream)

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 in `/usr/vtr/index` before issuing the command. For example, if the media file is `/usr/vtr/clips/news/current/stocks`, the index file would be stored in `/usr/vtr/index/news/current/stocks`.

### CCHP (Change Clip Protection)

To add specified protections to, or remove them from, a clip, use the following command:

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

where

- clip-name is the name of the clip.

- protection-type is the type of protection. This parameter can be one of the following:

  - ATTR, which protects the clip from changes to the edit in-point and edit out-point attributes

  - MV, which protects the clip from renaming

  - REC, which protects the clip from recording

  - RM, which protects the clip from deletes

  The plus sign (“+”) indicates that the protection should be added, and the minus sign (“-”) indicates that it should be removed.

| Note: The default is that a clip has no protections set. Therefore, you must use this command if you want the clip to have any protections.

For example, the following command sets the protection on the clip named “NA1001” such that the clip cannot be deleted but it can have its attributes (that is, its edit in- and out-points) changed:

    CCHP NA1001 +RM -ATTR

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

### CCP (Copy Clip)

To create a new clip by copying it from an existing clip, use the following command:

    CCP clip-name new-clip-name

where

- clip-name is the name of the existing clip used to create the new clip.

- new-clip-name is the name of the clip that is created.

The clip is created with all the same attributes as the original clip. However, after it has been created, the newly created clip has no association with the original clip.

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

### CCST (Clip Cache Status)

To get the current status of the VCP-Recorder clip cache, use the following command:

    CCST

This command returns a single response line (response code of 202) that is in the following format:

    num-clips bytes-used bytes-available 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 disk system that holds the clip cache.

- bytes-available is the number of free bytes on the disk system that holds the clip cache.

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

### CEDP (Set Edit Point)

To set the edit points for a clip, use the following command:

    CEDP clip-name in-point out-point

where

- clip-name is the clip for which the edit points are set.

- in-point is the edit in-point, specified in HH:MM:SS:FF format (HH:MM:SS.FF in drop-frame mode). Specifying “*” for in-point removes the respective edit point.

- out-point is the edit out-point, specified in HH:MM:SS:FF format (HH:MM:SS.FF in drop-frame mode). Specifying “*” for out-point removes the respective edit point.

This command sets the edit points to the specified values. The new edit points are not seen by any unit until the clip is loaded. If the clip is already loaded into a unit when this command is run, the original edit points still apply.

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

### CGP (Get Clip Protection)

To get the current protections for a clip, use the following command:

    CGP clip-name

where clip-name is the name of the clip for which the protections are wanted.

If this command is successful, the response code is 202, and a single response line is returned. The response line contains a list of the protections currently enabled for the clip. The protections may be the following:

- ATTR (Attribute Protect)

- MV (Rename Protect)

- REC (Record Protect)

- RM (Delete Protect)

### CIMG (Create Clip Image)

To copy an image from a clip to a file, use the following command:

    CIMG clip-name timecode interleave filename [format]

where

- clip-name is the name of the clip.

- timecode is the timecode of the frame to be extracted (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- 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).

- filename is the name of the file.

- 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”).

The `CIMG` (Create Clip Image) command extracts the image data associated with the clips's frame (specified by timecode) and writes the image to the file specified by filename.

### CINF (Clip Info)

To get information about a clip, use the following command:

    CINF clip-name

where clip-name is the name of the clip.

This command returns the attributes of the clip specified by clip-name. If the clip exists in the clip cache, the response code is 202 and a single response line is returned in the following format:

    clip-name  format  size  resident-size  start  end  in-point  out-point frame-rate

where

- clip-name is the name of the clip.

- format is the format of the clip. The format can be one of the following:

  - movie/vframe/uncompressed (uncompressed VCP-Recorder variable-frame format movies)

  - movie/vframe/rice (compressed VCP-Recorder variable-frame format movies using Rice compression)

  - movie/vframe/jpeg (motion JPEG)

  - movie/stream/mpeg/mpeg2/program (MPEG-2 program stream)

  - movie/stream/mpeg/mpeg2/transport (MPEG-2 transport stream)

- 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 (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- end is the timecode of the frame after the last frame of the clip (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- in-point is the current edit in-point of the clip (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- out-point is the current edit out-point of the clip (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- frame-rate is the frame rate of the clip in frames per second. 525-line timing is specified in its approximate form (29.97 frames per second).

### CLN (Link Clip)

To create a new clip that shares the clip media content of another clip, use the following command:

    CLN clip-name new-clip-name

where

- clip-name is the name of the existing clip whose content is shared by the new clip.

- new-clip-name is the name of the clip that is created.

The new clip starts with all the same attributes and protections as the original clip. However, the attributes of the new clip (such as its edit points) can be set independently of the original clip.

If the original clip is deleted, the new clip retains the content of the original clip. If both clips are deleted, the content is also deleted.

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

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

### CLS (List Clips)

To get a list of all the clips in the VCP-Recorder clip cache, use the following command:

    CLS

The response code for this command is 201. The response header line is followed by one response line for each clip in the cache. The format of each of those lines is:

    clip-name format size resident-size start end in-point out-point frame-rate

where

- clip-name is the name of the clip.

- format is the format of the clip. The format can be one of the following:

  - movie/vframe/uncompressed (uncompressed VCP-Recorder variable-frame format movies)

  - movie/vframe/rice (compressed VCP-Recorder variable-frame format movies using Rice compression)

  - movie/vframe/jpeg (motion JPEG)

  - movie/stream/mpeg/mpeg2/program (MPEG-2 program stream)

  - movie/stream/mpeg/mpeg2/transport (MPEG-2 transport stream)

- 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 (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- end is the timecode of the frame after the last frame of the clip (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- in-point is the current edit in-point of the clip (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- out-point is the current edit out-point of the clip (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- frame-rate is the frame rate of the clip in frames per second. 525-line timing is specified in its approximate form (29.97 frames per second).

### CLSA (List Added Clips)

To 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), use the following command:

    CLSA

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 this command is successful, the response code is 201. One response line is returned for each newly added clip, listing just the clip's name. A blank line terminates the list of clips.

### CLSR (List Removed Clips)

To 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, use the following command:

    CLSR

Before this 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 this command is successful, the response code is 201. One response line is returned for each newly removed clip, listing just the clip's name. A blank line terminates the list of clips.

### CMIN (Clip Monitor Info)

To get the number of clips that have been added to or removed from the clip cache since the last time the `CLSA` and `CLSR` commands were issued, use the following command:

    CMIN

This command returns the same counts that would be retuned if the `CLSA` and `CLSR` commands were issued.

The response code for this command is 200 and a single response line is returned in the following format:

    num-clips-added num-clips-deleted

where

- num-clips-added is the number of clips that have been added since the last time the `CLSA` command was issued.

- num-clips-deleted is the number of clips that have been removed since the last time the `CLSR` command was issued.

### CMON (Clip Monitor)

To initiate monitoring of the clip cache, use the following command:

    CMON

This command initiates the monitoring of the clip cache for the `CLSA` and `CLSR` commands, which are used to get a list of the clips that have been added or removed, respectively.

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

The response code to this command is 200.

### CMV (Rename Clip)

To rename a clip, use the following command:

    CMV clip-name new-clip-name

where clip-name is the existing name of the clip and new-clip-name is its new name.

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

### CRM (Delete Clip)

To delete a clip from the clip cache, use the following command:

    CRM clip-name

where clip-name is the name of the clip to be deleted. If any units currently have the clip loaded, actual deletion of the clip is deferred until all units have unloaded the clip.

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

### CRMA (Delete All Clips)

To delete all clips currently residing in the clip cache, use the following command:

CRMA

Clips that 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.

### ERR (Error)

To get the code and description of the last global error that occurred for a controller, use the following command:

    ERR

This command returns the code and description of 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 that do not pertain to a specific unit.

The response code from this command is 200, 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 (Set Frame Rate)

To set the frame rate used in translating timecodes for command timing, use the following command:

    FRAT frame-rate

where frame-rate is the frame rate in frames per second. Supported values are 24, 25, 29.97, and 30.

| Note: The frame rate that is used for command timing defaults to 29.97 if the `FRAT` command is not run.

### GTOD (Get System Time)

To get the current VCP-Recorder system time, use the following command:

    GTOD

The response code for this command is 202. A single response line is returned in the following format:

    timecode  UTC-time  UST-time

where,

- timecode is the system time in ISO 8601 format.

- UTC-time is the system time in UTC (ISO 8806) format.

- UST-time is the Unadjusted System Time. This value is approximately the number of nanoseconds since the server was last booted.

For example:

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

### MON (Monitor)

To place control connections into event monitoring mode, use the following command:

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

where

- unit-name is the name of a unit for which the control connection should be placed in event monitoring mode. Up to 32 units may be specified.

- event-type is a list of one or more event types, each one preceded by a single forward slash. The event types are UADD (unit added), URM (unit removed), UCHG (unit state 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, and UCTL events are returned. If no units are specified, UADD events are also returned.

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.

Event monitoring is terminated by closing the control connection.

The following is the format of the event response line for a UADD:

    UADD owner port mode

where

- 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).

The following is the format of the event response line for a URM:

    URM unit

where unit is the name of the unit.

The following is the format of the event response line for a UCHG:

    UCHG unit clip status function location speed frame-rate

where

- 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. PEND is pending, BUSY is waiting to execute, RUN is running, DONE is the completed state, and ERR is the error state. The status can move forward (PEND -> BUSY -> RUN -> DONE -> ERR) but never backward.

  | Note: In the case of `CUE`, the status reports DONE when the unit is fully cued. However, when a unit is cued, it is sending frames to the video device. Therefore, it is possible that after the status has been reported as DONE, something may happen to create an error. If the `CUE` gets an error after having reported DONE, the subsequent `PLAY` fails because the unit is no longer cued.

- function is the current function: IDLE, LOAD, UNLD (Unload), CUE, CUER (Cue for record), PLAY, JOG (Jog), SHTL (Shuttle), REC (Record), PAUS (Pause), STOP, ERR (Error).

- location is the current clip location (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

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

- frame-rate is the frame rate of the clip in frames per second. 525-line timing is specified in its approximate form (29.97 frames per second).

The following is the format of the event response line for a UCTL:

    UCTL unit control-name "control-value"

where

- unit is the name of the unit.

- control-name is the name of the control.

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

The following is the format of the event response line for a UERR:

    UERR unit error-code "error-message"

where

- unit is the name of the unit.

- error-code is the code of the error.

- error-message is the textual error message.

The following is the format of the event response line for a CADD:

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

where

- clip is the name of the clip.

- format is the format of the clip. The format is specified using the MediaHub hierarchical syntax.

- 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 (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- end is the timecode of the frame after the last frame of the clip (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- in is the current edit in-point of the clip (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- out is the current edit out-point of the clip (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- frame-rate is the frame rate of the clip in frames per second. 525-line timing is specified in its approximate form (29.97 frames per second).

The following is the format of the event response line for a CRM:

    CRM clip

where clip is the name of the clip.

### PLS (List Ports)

To get the list of supported media ports, use the following command:

    PLS

This command returns the list of supported media ports. If the command is 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

where

- name is the name of the port.

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

- description is a more verbose description of the port.

- type is the type of the port, which may be one of the following:

  - VID (video)

  - DECK (deck control)

  - NET (network)

  - DISK (disk storage)[4]

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

### SORD (Set Sort Order)

To set the sort order that is used when lists are returned, use the following command:

    SORD order-type

where order-type specified the desired sort order. The possible values of order-type are

- NAME, which sorts lists by the clip name

- TIME, which sorts lists by creation time

The response code for this command is 200.

### STLS (List Statistics)

To list statistical information, use the following command:

    STLS [component-pattern [statistic-pattern]]

where

- component-pattern is a pattern that describes the names of the components for which you want to see statistics. If this is omitted, the command returns statistics for all components.

- statistic-pattern is a pattern that describes the names of the statistical values that you want to see. If this is omitted, the command returns all statistics for the components that are specified.

The asterisk (“*”) can be used when specifying the component-pattern or statistic-pattern in this command. For example, the following command lists all the statistics for components that contain “DIVO” in their names:

    STLS *DIVO*

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 (for example, histograms) may include more than one number.

### STOD (Set System Time)

To set the VCP-Recorder system time, use the following command:

    STOD time

where time is the time to which the system time is set. The time can be in either the VCP-Recorder timecode format (see “About MVCP Timecodes” for information) or the ISO 8601 format (yyyymmddThhmmss.ssssssZ).

### STST (Statistics Statistics)

To calculate various statistics, use the following command:

    STST [component-pattern [statistic-pattern]]

where

- component-pattern is a pattern that describes the names of the components for which you want to see statistics. If this is omitted, the command returns statistics for all components.

- statistic-pattern is a pattern that describes the names of the statistical values that you want to see. If this is omitted, the command returns all statistics for the components that are specified.

The asterisk (“*”) can be used when specifying the component-pattern or statistic-pattern in this command. For example, the following command calculates all the statistics for components that contain “DIVO” in their names:

    STST *DIVO*

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 (Reset Statistics)

To reset the VCP-Recorder statistics, use the following command:

    STZ [component-pattern [statistic-pattern]]

where

- component-pattern is a pattern that describes the names of the components for which you want the statistics reset. If this is omitted, the command resets statistics for all components.

- statistic-pattern is a pattern that describes the names of the statistical values that you want reset. If this is omitted, the command resets all statistics for the components that are specified.

The asterisk (“*”) can be used when specifying the component-pattern or statistic-pattern in this command. For example, the following command resets all the statistics for components that contain “DIVO” in their names:

    STZ *DIVO*

### UADD (Add Unit)

To create a new unit, use the following command:

    UADD media-port-name storage-port-name port-access-mode

where

- media-port-name is the name of the media port accessed by the unit.

- storage-port-name is the name of the storage port accessed by the unit. If storage-port-name is an asterisk (*), the default storage system is used.

- port-access-mode specifies how access is shared between multiple units that access the same media port. This parameter takes one of the following values:

  - EXCL, which indicates exclusive access. Only one unit that uses the media port can exist at any given time. If a unit already exists for that port, this command fails.

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

  - CONC, which indicates concurrent access. Multiple units can use the media port at the same time. This mode is used most commonly on multiplexed networking ports, such as ATM.

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

### ULS (List Units)

To get a list of the existing VCP-Recorder units, use the following command:

    ULS

This command returns a list of the existing VCP-Recorder units along with a snapshot of the state of each unit.

If this command is successful, the response code is 201. One response line for each unit is returned followed by a blank line. The format of each response line is

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

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, which can be one of the following:

  - BUSY, which is the initial state

  - RUN, which is the running state

  - DONE, which is the completed state

  - ERR, which is the error state

- function is the current function, which can be one of the following: IDLE, LOAD, UNLD (Unload), CUE, CUER (Cue for record), PLAY, JOG (Jog), SHTL (Shuttle), REC (Record), PAUS (Pause), STOP.

- location is the current clip location (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

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

- frame-rate is the frame rate of the clip in frames per second. 525-line timing is specified in its approximate form (29.97 frames per second).

For example:

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

## MVCP Unit Commands

Table 4-3 identifies the MVCP unit commands that are described in this section. These commands are used with a specific unit.

Table 4-3. 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 | Jog 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
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 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.

### CUE (Cue for Playback)

To cue the clip currently loaded in a unit for playback, use the following command:

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

where

- unit-name is the name of the unit to which the command applies.

- in-point is the in-point, specified as a frame, at which the clip is cued. If in-point is specified as “*” or is missing, the edit in-point stored with the clip is used, or, if the edit in-point is not set, the first recorded frame of the clip is used.

  This parameter must be specified if out-point is specified.

- out-point is the edit out-point, specified as a frame. If out-point is specified, the clip is cued with the specified out-point, meaning that playback terminates at the specified frame. If out-point is specified as “*” or is missing, the edit out-point stored with the clip is used, or, if the edit out-point is not set, no out-point is used and playback continues until the unit is stopped.

- direction specifies the playback direction. It can be one of the following:

  - FWD for forward direction

  - BWD for reverse direction

  - F/B for alternating forward and backward direction (that is, swing mode)

  - B/F for alternating backward and forward direction (that is, swing mode)

  The default direction is forward (FWD).

  | Note: If the direction is FWD or F/B, the clip is cued at its in-point. If the direction is BWD or B/F, the clip is cued at its out-point.

- passes is an integer that specifies how many passes through the clip are made. The default is one pass. If passes is zero, the clip repeats playing indefinitely until the `STOP` command is issued.

  | Note: A pass in a given direction counts as one. Therefore, a value of at least 2 should be specified for passes when direction is either F/B or B/F.

  If passes is specified as -1, the unit is cued in free-range mode. In this mode, in-point is used only as the initial location; it does not define the lower limit of playback. If the vtr.media.clip.limit.start control is set, it defines the lower limit of playback. If vtr.media.clip.limit.start is not set, the beginning of the clip defines the lower limit.

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

  | Note: See the `vcp-recorder-controls(5)` man page for information about the controls.

If either in-point or out-point is specified, the other may be specified as a duration by adding a “+” prefix character. The following examples all refer to the same edit range:

    “1:00:01:00 1:00:06:00”
    “1:00:01:00 +5:00”
    “+5:00 1:00:06:00”

The following example cues the clip in unit U1 for the alternating forward and backward direction. The clip is cued at 30 seconds and it plays continuously between the 30 second point and the end until the `STOP` command is issued:

    CUE U1 00:00:30.00 * F/B 0

### CUER (Cue for Record)

To cue the clip currently loaded in a unit for recording, use the following command:

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

where

- unit-name is the name of the unit to which the command applies.

- in-point is the in-point, specified as a frame, at which the clip is cued. If in-point is specified as “*” or is missing, the unit cues to the edit in-point stored with the clip.

  This parameter must be specified if out-point is specified.

- out-point is the edit out-point, specified as a frame. If out-point is specified, the clip is cued with the specified out-point, meaning that recording will terminate at the specified frame. If out-point is specified as “*” or is missing, recording continues until the unit is stopped.

If either in-point or out-point is specified, the other may be specified as a duration by adding a “+” prefix character. The following examples all refer to the same edit range:

    “1:00:01:00 1:00:06:00”
    “1:00:01:00 +5:00”
    “+5:00 1:00:06:00”

### EDIT (Edit)

To cue a unit for recording and then begin recording, use the following command:

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

where

- unit-name is the name of the unit to which the command applies.

- in-point is the in-point, specified as a frame, at which the clip is cued. If in-point is specified as “*” or is missing, the edit in-point stored with the clip is used.

  This parameter must be specified if out-point is specified.

- out-point is the out-point, specified as a frame, at which the clip is cued. If out-point is specified as “*” or is missing, the edit in-point stored with the clip is used.

The `EDIT` (Edit) command does the equivalent of a `CUER` command followed immediately by a `REC` command.

| Note: This command is implemented for only certain devices (for example, VLAN devices).

### FCLR (Clear Frames)

To erase the audio and video from specified frames in a clip, use the following command:

    FCLR unit-name in-frame out-frame

where

- unit-name is the name of the unit to which the command applies.

- in-frame is the first frame to be erased.

- out-frame is the frame after the last frame to be erased.

The `FCLR` command clears (erases) the frames of the clip loaded into the unit, beginning with the frame specified by in-frame (inclusive) and ending with the frame specified by out-frame (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 (Fast Forward)

To fast forward a unit, use the following command:

    FF unit-name

where unit-name is the name of the unit to which the command applies. The unit must have a clip that is either cued or playing. If the unit is idle (that is, a clip is not cued or playing), an error is written to the VCP-Recorder log.

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

### FINS (Insert Frames)

To move frames within a clip, use the following command:

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

where

- unit-name is the name of the unit to which the command applies.

- source-in is the first frame to be moved (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- source-out is the last frame to be moved (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- dest-in is the timecode to which the frames are moved (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

The `FINS` command moves the clip's frames in the range source-in to source-out, inserting them at the point specified by the timecode dest-in. After `FINS`, the duration of the clip is the same.

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

### FNEW (Insert New Frames)

To insert blank frames within a clip, use the following command:

    FNEW unit-name in-frame out-frame

where

- unit-name is the name of the unit to which the command applies.

- in-frame is the location in the clip of the first frame to be inserted (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- out-frame is the frame after the last frame that is inserted (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

The `FNEW` command opens a hole in the clip and inserts blank frames at the frame specified by in-frame (inclusive) up to out-frame (exclusive). The number of new frames added is given by out-frame - in-frame.

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

### FOVR (Overwrite Frames)

To overwrite frames within a clip, use the following command:

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

where

- unit-name is the name of the unit to which the command applies.

- source-in is the first frame to be moved (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- source-out is the frame after the last frame to be moved (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- dest-in is the timecode of the destination to be overwritten (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

The `FOVR` command moves the frames in the range source-in to source-out, to the frames starting at the timecode specified by dest-in. The frames starting at dest-in are overwritten. After the `FOVR` command, the duration of the clip is decreased. The amount depends on whether the source and target frames overlap.

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

### FRM (Remove Frames)

To remove frames from within a clip, use the following command:

    FRM unit-name in-frame out-frame

where

- unit-name is the name of the unit to which the command applies.

- in-frame is the first frame to be removed (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- out-frame is the frame after the last frame to be removed (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

The `FRM` command removes the frames of the clip, from the frame specified by in-frame (inclusive) to the frame specified by out-frame (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 (Get Control)

To get the values of the controls, use the following command:

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

where

- unit-name is the name of the unit to which the command applies. The `GET` (Get Control) command gets the values of device controls for the unit specified by unit-name.

- dev-type specifies whether the controls are queried in the media (MED) or storage (STOR) device assigned to the unit. The controls are device-dependent.

- control-name-pattern is the name of the control. The asterisk (“*”) can be used when specifying the control-name-pattern in this command.

  | Note: See the `vcp-recorder-controls(5)` man page for information about the controls.

If the command is successful, the response code is 201 and one response line is returned for each matching control. The format of each line is

    control-name control-value

where control-name is the name of the control and control-value is its 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 (GO TO)

To jump a unit's transport operation to a specified location, use the following command:

    GOTO unit-name timecode

where

- unit-name is the name of the unit to which the command applies.

- timecode is the location to which the unit's transport should be jumped (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

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 it was executing starting at the target of the `GOTO` command.

| Note: The `GOTO` (Goto) command does not work while the unit is idle.

### JOG (Jog)

To jog a unit by the number of specified frames, use the following command:

    JOG unit-name frames

where

- unit-name is the name of the unit to which the command applies. The unit must be paused before it can be jogged.

- frames is the number of frames to jog the unit. If the number is positive, the unit is jogged forward. If the number is negative, the unit is jogged backward.

| Note: If a device is not frame-accurate, it may report a clip location that is an estimate. After the first time the unit is jogged, however, the location will be frame-accurate.

### LIMS (Set Edit Limits)

To modify the edit limits being used by the current playback or record function, use the following command:

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

where

- unit-name is the name of the unit to which the command applies.

- in-point is the in-point, specified as a frame, at which the clip is cued.

- out-point is the edit out-point, specified as a frame.

- direction specifies the playback direction. It can be one of the following:

  - FWD for forward direction

  - BWD for reverse direction

  - F/B for alternating forward and backward direction (that is, swing mode)

  - B/F for alternating backward and forward direction (that is, swing mode)

- passes is an integer that specifies how many passes through the clip are made. The default is one pass. If passes is zero, the clip repeats playing indefinitely until the `STOP` command is issued.

  If passes is specified as -1, the unit is cued in free-range mode. In this mode, the unit is cued to the point specified by in-point; out-point is ignored. In addition, in-point is used only as the initial location; it does not define the lower limit of playback.

The `LIMS` (Set Edit Limits) command modifies the edit limits being used by the current playback or record function. The edit limits that can be changed are device-dependent. In general, only the out-point can be changed as a way to stop playback or recording at a specific point.

| Note: This function is not implemented on Vela ports.

### LOAD (Load Clip)

To load a clip into a unit, use the following command:

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

where

- unit-name is the name of the unit to which the command applies.

- clip-name is the name of the clip to be loaded.

- load-mode indicates whether the clip is being loaded for input (IN), output (OUT), or input and output (BOTH). The default is output (OUT).

- CRTE indicates that the clip should be created if it does not exist.

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

    format size resident-size size start end in-point out-point frame-rate

where

- format is the format of the clip. The format can be one of the following:

  - movie/vframe/uncompressed (uncompressed VCP-Recorder variable-frame format movies)

  - movie/vframe/rice (compressed VCP-Recorder variable-frame format movies using Rice compression)

  - movie/vframe/jpeg (motion JPEG)

  - movie/stream/mpeg/mpeg2/program (MPEG-2 program stream)

  - movie/stream/mpeg/mpeg2/transport (MPEG-2 transport stream)

- size is the size of the clip content in bytes.

- resident-size 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 (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- end is the timecode of the frame after the last frame of the clip (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- in-point is the current edit in-point of the clip (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- out-point is the current edit out-point of the clip (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

- frame-rate is the frame rate of the clip in frames per second. 525-line timing is specified in its approximate form (29.97 frames per second).

### PAUS (Pause)

To pause a unit, use the following command:

    PAUS unit-name

where unit-name is the name of the unit to which the command applies. The unit must be in a playback or record state for this command to take effect.

| Note: The `RSUM`, `PLAY`, `JOG`, `SHTL` or `REC` commands are used to resume playback or recording.

If the unit is playing, the video output is a still frame at the pause location.

### PLAY (Play Unit)

To begin playback on a unit, use the following command:

    PLAY unit-name speed

where

- unit-name is the name of the unit to which the command applies. The unit must be cued for playback or in a playback state (that is, paused, shuttle, jog).

- speed can be specified as 1000 (1x forward play) or -1000 (1x backward play).

| Note: The `PLAY` command is also used to resume normal playback after a `PAUS`, `SHTL`, or `JOG` command.

This command cannot be used to resume playback after a `STOP` command is issued, in which case the unit must be re-cued.

### REC (Record)

To begin recording on a unit or resume normal recording after a `PAUS` command, use the following command:

    REC unit-name

where unit-name is the name of the unit to which the command applies. The unit must be cued for recording or in a recording state (that is, paused).

This command cannot be used to resume recording after a `STOP` command is issued. The unit must be re-cued.

### REVU (Review)

To do the equivalent of a `CUE` command followed immediately by a `PLAY` command on a unit, use the following command:

    REVU unit-name [ in-point [ out-point [ direction [ passes ]]]]

where

- unit-name is the name of the unit to which the command applies.

- in-point is the in-point, specified as a frame, at which the clip is cued. If in-point is specified as “*” or is missing, the edit in-point stored with the clip is used.

  This parameter must be specified if out-point is specified.

- out-point is the out-point, specified as a frame, at which the clip is cued. If out-point is specified as “*” or is missing, the edit in-point stored with the clip is used.

- direction specifies the playback direction. It can be one of the following:

  - FWD for forward direction

  - BWD for reverse direction

  - F/B for alternating forward and backward direction (that is, swing mode)

  - B/F for alternating backward and forward direction (that is, swing mode)

  The default direction is forward (FWD).

  | Note: If the direction is FWD or F/B, the clip is cued at its in-point. If the direction is BWD or B/F, the clip is cued at its out-point.

- passes is an integer that specifies how many passes through the clip are made. The default is one pass. If passes is zero, the clip repeats indefinitely until the STOP command is issued.

| Note: This command is implemented for only certain devices (for example, VLAN devices).

### REW (Fast Reverse)

To fast reverse a unit, use the following command:

    REW unit-name

where unit-name is the name of the unit to which the command applies. The unit must have a clip that is either cued or playing. If the unit is idle (that is, a clip is not cued or playing), an error is written to the VCP-Recorder log.

The `REW` (Fast Reverse) command fast reverses the unit specified by unit-name. The reverse speed is device-dependent.

### RHRS (Rehearse)

To do the equivalent of a `CUE` command followed immediately by a `PLAY` command, while switching the media port to end-to-end mode during playback, use the following command:

    RHRS unit-name [ in-point [ out-point [ direction [ passes ]]]]

where

- unit-name is the name of the unit to which the command applies.

- in-point is the in-point, specified as a frame, at which the clip is cued. If in-point is specified as “*” or is missing, the edit in-point stored with the clip is used.

  This parameter must be specified if out-point is specified.

- out-point is the out-point, specified as a frame, at which the clip is cued. If out-point is specified as “*” or is missing, the edit in-point stored with the clip is used.

- direction specifies the playback direction. It can be one of the following:

  - FWD for forward direction

  - BWD for reverse direction

  - F/B for alternating forward and backward direction (that is, swing mode)

  - B/F for alternating backward and forward direction (that is, swing mode)

  The default direction is forward (FWD).

  | Note: If the direction is FWD or F/B, the clip is cued at its in-point. If the direction is BWD or B/F, the clip is cued at its out-point.

- passes is an integer that specifies how many passes through the clip are made. The default is one pass. If passes is zero, the clip repeats indefinitely until the `STOP` command is issued.

| Note: This command is implemented for only certain devices (for example, VLAN devices).

### RSUM (Resume)

To resume the playback or recording function that was paused, use the following command:

    RSUM unit-name

where unit-name is the name of the unit for which the playback or recording is resumed.

### SET (Set Control)

To set the controls for a unit, use the following command:

    SET unit-name dev-type control-name control-value [control-name control-value] ...

where

- unit-name is the name of the unit to which the command applies.

- The dev-type specifies whether the controls are to be set in the media (MED) or the storage (STOR) device assigned to the unit.

- control-name is the name of the control. The controls are device-dependent.

- control-value is the value to which the control is set. If the control value contains any spaces or tabs, the value must be enclosed in double quotation marks.

| Note: The possible values for control-name and control-value are defined in the `vcp-recorder-controls(5)` man page.

For each control, a name and a value must be provided. At least one control name/value pair must be specified.

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 (Shuttle)

To shuttle a unit at a specified speed, use the following command:

    SHTL unit-name speed

where

- unit-name is the name of the unit to which the command applies.

- speed is the speed at which the unit is shuttled. 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 and negative speeds play backward. (Some devices cannot play backwards.)

  | Note: The actual shuttle speeds available are device-dependent.

### STOP (Stop Unit)

To stop playback or recording on a unit, use the following command:

    STOP unit-name

where unit-name is the name of the unit to which the command applies. Playback or recording cannot be resumed on this unit until it is re-cued with the `CUE` or `CUER` command, respectively.

### UCLS (Unit Close)

To close an opened or created unit, use the following command:

    UCLS unit-name

where unit-name is the name of the unit to which the command applies. This controller's access is terminated and, if no other controllers have the unit open, the unit is deleted.

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

### UERR (Unit Error)

To get the code and description of the last error that occurred on a unit, use the following command:

    UERR unit-name

where unit-name is the name of the unit to which the command applies.

This command returns the code and description of 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 in the following format:

    code “description”

where

- code is the error code of the last error.

- description is a textual description of the error.

### UFLS (Flush Unit)

To flush the command queue for a unit, use the following command:

    UFLS unit-name

where unit-name is the name of the unit whose command queue is flushed.

See “Synchronization of Unit Commands and Responses” for a description of the command queue.

### UGIN (Get Unit Info)

To get the owner and port for a unit, use the following command:

    UGIN unit-name

where unit-name is the name of the unit for which the owner and port information is returned. 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

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 port. The possible values are IN, OUT, and BOTH.

### UINF (Get Unit Info)

To get the owner and port information for a unit, use the following command:

    UINF unit-name

where unit-name is the name of the unit to which the command applies. The unit must have been opened or created by the current controller.

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

    owner port-name port-mode

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 port. The possible values are IN, OUT, and BOTH.

### UINT (Unit Interrupt)

To interrupt the command currently being processed by a unit, use the following command:

    UINT unit-name

where unit-name is the name of unit for which the current command is interrupted. The command is terminated with error EINTR.

### ULOC (Unit Location)

To return the current transport location for a unit, use the following command:

    ULOC unit-name

where unit-name is the name of the unit to which the command applies.

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.

  | Note: The accuracy of the timecode that is returned depends on the capabilities of the device. If a device is not frame-accurate, it returns a best-effort estimate of the current location.

- 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) when the unit was at the specified location. This time can be used to account for application or network latency in time reporting.

For example:

    ULOC U2
    202 OK
    00:00:00.00 00:00:00:00/00:00:00:00 00:00:00:00/00:00:00:00
          19980108T205545.154669Z 174838119321533

| Note: The `ULOC` command returns a single response line. In this example, the second line is indented to indicate that it is part of the previous line.

### UNLD (Unload Clip)

To unload the clip currently loaded in a unit, use the following command:

    UNLD unit-name

where unit-name is the name of the unit to which the command applies.

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

### UOPN (Unit Open)

To open an existing unit and make it controllable by this MVCP connection, use the following command:

    UOPN unit-name

where unit-name is the name of an existing unit to be opened and made controllable by this control connection.

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

### USTA (Unit Status)

To get the status of a unit, use the following command:

    USTA unit-name

where unit-name is the name of the unit to which the command applies. The unit must be opened or created by the current controller.

If this command is successful, the response code is 202. A single response line in the following format is returned:

    clip status function location speed frame-rate

where

- clip is the name of the loaded clip (“*” if no clip is loaded).

- status is the status of the current function, which can be one of the following:

  - BUSY indicates the initial state

  - RUN indicates the running state

  - DONE indicates the completed state

  - ERR indicates the error state

- function is the current function, which can be one of the following: IDLE, LOAD, UNLD (Unload), CUE, CUER (Cue for record), PLAY, JOG (Jog), SHTL (Shuttle), REC (Record), PAUS (Pause), STOP.

- location is the current clip location (HH:MM:SS:FF, or HH:MM:SS.FF in drop-frame mode).

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

- frame-rate is the frame rate of the current clip in frames per second. 525-line timing is specified in its approximate form (29.97 frames per second).

### USYN (Set Unit Synchronization)

To set the default synchronization, preemption, and queuing modes for a specified unit, use the following command:

    [sync-mode] USYN unit-name

where

- sync-mode is the default value for the unit. This parameter can have any combination of the synchronization, preemption, and queuing modes described in “Synchronization of Unit Commands and Responses”.

  If this parameter is omitted, the default modes described in “Synchronization of Unit Commands and Responses” are used for this unit.

- unit-name is the name of the unit to which the command applies.

Once this command has been used to set new default modes for this unit, all subsequent commands for this unit that do not specify a synchronization, preemption, or queuing mode use the default set by the `USYN` command.

The following statement changes the default modes for unit U1 such that a new command will execute after the previous command completes (/SEQ) and the response to the command is delayed until the unit has reached the initialization state on the command (/SYNI):

    /SEQ /SYNI USYN U1

### UUWT (Unit Unit Wait)

To synchronize command execution between two units, use the following command:

    UUWT unit-name wait-unit-name sync-mode

where unit-name is the name of the unit that waits until the unit specified by wait-unit-name reaches the execution status specified by sync-mode. Both units must be opened by the current control connection.

For the possible values of sync-mode, see “Synchronization of Unit Commands and Responses”.

### UWAT (Unit Wait)

To wait for the completion of the last command that was issued to a unit, use the following command:

    UWAT unit-name [ sync-mode ]

where

- unit-name is the name of the unit to which the command applies.

- sync-mode is the synchronization mode to use. This parameter can have one of the following values: ASYN, SYNI, SYNR, and SYNC. (See “Changing the Synchronization Mode” for a description of these synchronization modes.)

  If this parameter is omitted, the default synchronization mode is used.

This command waits for the last command issued to the unit according to the synchronization mode specified by sync-mode or the default synchronization mode, if the sync-mode argument is not provided.

[4] The network and disk storage ports are not implemented.

Prev | Table of Contents | Next
Chapter 3. Using the Clip Manager |  | Appendix A. Using a MediaHub Archive System