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:
This section contains general information about using the MVCP commands. The following topics are discussed:
 | Note: MVCP is similar in operation to that of ftpd, with the exceptions that are noted in this section. |
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. % |
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. |
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 |
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
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.
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 |
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:
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. |
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.
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. |
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 |
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. |
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.
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.
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.
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. |
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.
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.
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.
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.
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.
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.
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.
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.
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)
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.
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).
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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. |
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 |
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.
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 |
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.
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.
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).
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.
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* |
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.
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 * |
Table 4-3 identifies the MVCP unit commands that are described in this section. These commands are used with a specific unit.
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.
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 |
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” |
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). |
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).
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.
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).
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).
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).
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).
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" |
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. |
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. |
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. |
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).
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.
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.
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.
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). |
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.
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). |
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.
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 |
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.
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.
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.
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.
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.
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.
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.
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.
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. |
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.
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.
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).
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 |
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”.
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.