NOTE: Lower case MVCP command strings will not parse. The command arguments may consist of any case combination of ASCII characters. Unprintable ASCII character passed as arguments are parsed as spaces, but retain their ASCII values, rendering these clips unmanagable by the MSB. Users should restrict command argument values to the inclusive ASCII range HEX 20 (space) and HEX 7E (~). Arguments with spaces as values must enclosed with quotation marks (HEX 22).
Protocol response message text consists of a numeric result code and an attributed informational message terminated by a CR/LF. Success is indicated with a response code of the form 2xx. Unless otherwise stated, a command returns the result code 200 if successfully parsed. However, a valid command parse does not automatically imply the underlying MSB resource executes successfully. Refer to UNIT COMMAND MODES for discussion of this behavior.
Like FTP, certain MVCP responses may also include a single response line or multiple response lines terminated by a single blank line (CR/LF). In this case, a result code of 202 is returned and a single response line follows. Result code 201 returns if (one or more lines terminated by a blank line) is subsequently generated.
All MVCP command arguments and responses are white space-delimited. Command arguments that contain spaces must be encapsulated by double quotation marks to enable consistent argument parse. In some cases, response arguments that do not contain spaces may be double-quoted, and the application should be prepared to handle these specifically.
NOTE: Future MVCP enhancements may alter command name, argument quantity, or reply results. When new arguments are added to a command, omission of the new arguments will result in the behavior associated with the original command; hence, existing applications will continue to work in a compatible manner. See the VERS command for information regarding protocol versioning, which aids the conditionalization of applications that track MVCP evolution.
For example:
CINF clip1 (global: retrieve clip information) 202 OK clip1 movie/stream/mpeg/mpeg2/sgi ... (additional metadata not shown)
LOAD U1 clip1 (unit: load clip into unit U1) 202 OK clip1 movie/stream/mpeg/mpeg2/sgi ... (additional metadata not shown)
When the unit name is omitted or specified as '*' with a unit command, the current unit is used. The unit name can be omitted only if the unit command has no required arguments.
Units can either be created (using the UADD command) or opened (using the UOPN command). When a unit is opened, it must have previously been created by another MVCP session (which could be another MVCP session or an external control processor such as a station automation system or on-line editor). Exercise caution when sharing control of a unit between two MVCP sessions. Interfering with a unit owned by an MSB external protocol processor (e.g., Sony, Harris, Odetics) may lead to unpredictable behavior.
The USER command applies only to the current MVCP session.
The files /usr/vtr/config/mvcp.allow or /usr/vtr/config/mvcp.deny must be specified to enable and disable individual user access to MSB via MVCP. A comma-separated list of user names must be given in each file. The user names must match the entries held in /etc/passwd to affect comparison during session initiation.
If successful, the USER command returns 331 Password required for user.
The PASS command applies only to the current MVCP session. The /etc/passwd value for the user's password must contain a valid, non-null entry to affect comparison.
If successful, the PASS command returns 200 OK.
NOTE: The access controls furnished with USER and PASS commands are not fully implemented and usage should be avoided.
If successful, the VERS command returns 202 OK, followed by the MVCP version label. This command is currently unimplemented.
name mode ``description'' type port-physical-name
where:
name identifies the port name as known to MSB.
mode identifies the port's input/output mode (IN, OUT, or BOTH).
description provides descriptive text about the port.
type identifies the port type. Currently MSB supports port types of NET (network), VID (video), DECK (deck control), or DISK (disk storage).
port-physical-name defines the media ports physical name used for unit creation and management.
For example:
PLS 201 OK MPEG422_6 OUT "SGI PCI-VIDAUD-MSB-B" VID "WHITE HOUSE OVAL OFFICE" MPEG422_7 OUT "SGI PCI-VIDAUD-MSB-B" VID "MAIN CASINO, ROULETTE TABLE 2" MPEG422_12 IN "SGI PCI-VIDAUD-MSB-B" VID "COUNT ROOM" MPEG422_13 OUT "SGI PCI-VIDAUD-MSB-B" VID "MAIN AND 1ST TRAFFIC LIGHT EAST BOUND"
Certain media ports have no attributed storage port, such as those assigned to deck control. Specify 'null' for the storage port to create a unit which does not have a storage port.
The port-sharing-mode specifies how access is shared between multiple units accessing the same media port and takes one of the following values: EXCL, SHAR, or CONC.
Exclusive access (EXCL) asserts that only one unit may exist at any instance, precluding creation of additional units through contemporaneous MVCP sessions. UADD will fail if a pre-existing unit was created with EXCL and currently active within a sibling MVCP session.
Shared access (SHAR) allows multiple unit creation on the same port. However, only one unit may actually use the hardware at any given time. Shared access is only available on media ports which support it (in their interface module).
Concurrent access (CONC) allows multiple units to simultaneously use the media port. This mode is used most commonly on multiplexed networking ports.
The owner-info is optional and establishes an ownership label for the new unit. The owner info is output by certain unit status commands (UINF, UGIN, and ULS).
If the unit is successfully created, a response code 202 returns and a single response line containing the newly created unit name is output.
For example:
UADD MFCODEC_6 * EXCL * 202 OK U1
If the unit exists, a response code 202 returns and a single response line is returned with this format:
owner port-name port-mode port-physical-name
where:
owner identifies the creating MVCP session name for the unit.
port-name identifies the media port label controlled by the unit.
port-mode identifies the input/output mode the unit supports. The possible values are IN, OUT, and BOTH.
port-physical-name identifies the media port physical name controlled by the unit.
For example:
UGIN U1 202 OK * MPEG422_6 OUT MFCODEC_6
If the ULS command is successful, a response code 201 returns and one response line for each unit is output followed by a terminating blank line. The display format for unit state is:
name owner port mode clip status function location speed rate command-id
where:
name identifies the unit.
owner identifies the MVCP session name that created the unit.
port identifies the unit's media port label.
mode identifies the media port mode (IN, OUT, or BOTH).
clip identifies the loaded clip name (``*'' if no clip is currently loaded).
status states the unit's current function status (BUSY - OP IN-PROGRESS, RUN - RUNNING, DONE - COMPLETE, ERR - ERROR).
function identifies the current function: IDLE, LOAD, UNLD (Unload), CUE (Cue for playout), CUER (Cue for record), PLAY, STEP, SHTL (Shuttle), REC (Record), PAUS (Pause), STON (StandbyOn), STOP, FF (Fast Forward), REW (Rewind).
location identifies the current clip location in hours:minutes:seconds:frames format. In drop-frame mode, a period (.) replaces the last colon in the timecode.
speed specifies the current playback speed (1000 = normal 1x speed).
rate specifies the frame rate (in frames/sec) corresponding to the unit location. 525-line drop-frame timing is specified in its approximate form, 29.97 (525 non-drop-frame is 30). 625-line is represented as 25 frames per second.
command-id identifies the unit's MVCP command in-process.
For example:
ULS 201 OK U1 * MPEG422_6 OUT * DONE IDLE * 0 * 0
A list of one or more event types may be specified (preceded by a single forward slash). The event types are: UADD (unit added), URM (unit closed), UCHG (unit state change), ULOC (unit location change), UCTL (unit control change), UERR (unit error), CADD (clip added), CRM (clip removed), CCHG (clip media modified), CMV (clip moved), CEDP (change in clip in/out points) and CCHP (clip attribute protection change). Only the specified types of events are returned.
If no event-type is specified, MON returns UCHG, URM, UERR, and UCTL events by default, and if no units are specified, UADD-related events are returned by default.
Event monitoring terminates by closing the MVCP session.
The event response line returned by MON consists of one of the following.
In response to UADD from an MVCP session, MON produces:
UADD unit-name owner_info media_port_name port_sharing_mode physical_port_name
UCHG unit-name clip status function location speed rate command-id
where:
unit-name is the name of the unit.
clip identifies the loaded clip name (``*'' if no clip is loaded).
status states the unit's current function status (BUSY - INITIALIZATION, RUN - RUNNING, DONE - COMPLETE, ERR - ERROR).
function states the unit's current function: IDLE, LOAD, UNLD (Unload), CUE, CUER (Cue for record), PLAY, STEP, SHTL (Shuttle), REC (Record), PAUS (Pause), STON (StandbyOn), STOP, FF (Fast Forward), REW (Rewind).
location is the current clip location in hours:minutes:seconds:frames format. A period (.) replaces the final colon (:) in drop-frame mode.
speed identifies the current playback speed (1000 = normal 1x speed).
rate is the frame rate (in frames/sec) corresponding to the unit location. 525-line drop-frame timing is specified in its approximate form, 29.97 (525 non-drop-frame is 30). 625-line is represented as 25 frames per second.
command-id identifies unit's in-process command.
In response to UCLS from an MVCP session, MON produces:
URM unit-name
unit-name identifies the unit name.
In response to ULS from an MVCP session, MON produces:
ULOC unit-name location rate
unit-name identifies the unit name.
location identifies the current clip location in hours:minutes:seconds:frames format. A period (.) replaces the final colon (:) in drop-frame mode.
rate identifies the timecode rate (in frames/sec) corresponding to the unit location. 525-line drop-frame timing is specified in its approximate form, 29.97 (525 non-drop-frame is 30).
In response to a SSET from an MVCP session, or in response to initial unit creation via UADD, MON produces:
UCTL unit-name control-name ``control-value''
unit-name identifies the unit name.
control-name identifies the control name.
control-value identifies the new value assigned to control-name.
In the event of a unit error, MON produces:
UERR unit-name error-code ``error-message''
unit-name identifies the unit name experiencing the error.
error-code identifies the error code number.
error-message identifes textual error message.
In response to CADD, MON produces:
CADD clip format size resident-size start end in out rate time-of-last-modification clip-type
clip identifies the clip name.
format identifies the clip format (mpeg2, dvcpro, vframe, etc).
size identifies clip content size in bytes.
resident-size identifies the cache-resident clip content size in bytes
start states the clip timecode of the first time.
end states the clip timecode of the last frame.
in identifies the clip current mark-in timecode.
out identifies the clip current mark-out timecode.
rate identifies the clip frame rate (in frames/sec). 525-line drop-frame timing is specified in its approximate form, 29.97 (525 non-drop-frame is 30). Drop-frame and non-drop-frame translation is not performed irrespective of FRAT setting.
time-of-last-modification specifies the clip modification time, the last time the clip content was modified and flushed to mass storage.
clip-type specifies either CL or LN. The value LN implies that clip creation was performed as a link to another clip. The value CL implies the clip is unassociated.
In respone to CRM, MON produces:
CRM clip
clip identifies the clip name.
In response to CCHG, MON produces:
CCHG clip format size resident-size start end in out rate time-of-last-modification clip-type
clip identifies the clip name.
format identifies the clip format.
size specifies clip content size in bytes.
resident-size specifies cache-resident clip content size in bytes.
start identifies the clip timecode of the first frame.
end identifies the clip timecode of the last frame.
in identifies the clip current mark-in point.
out identifies the clip current mark-out point.
rate identifies the clip frame rate (in frames/sec). 525-line drop-frame timing is specified in its approximate form, 29.97 (525 non-drop-frame is 30). Drop-frame and non-drop-frame translation is not performed regardless of FRAT setting.
time-of-last-modification specifies the clip modification time, the last time the clip content was modified and flushed to mass storage.
clip-type specifies either CL or LN. The value LN implies that clip creation was performed as a link to another clip. The value CL implies the clip is unassociated.
In response to CMV, MON produces:
CMV clip new-clip
clip identifies original clip name; new-clip identifies new clip name.
In response to CEDP, MON produces:
CEDP clip mark-in mark-out [tc-track]
mark-in mark-out identify the new clip in-out points. The optional argument tc-track specifies the time code track used for the mark-in and mark-out:
CLIP is the control track, VITC is the vitc track,
LTC is fis the ltc track. If not specified, the default time code track will be used.
In response to CCHP, MON produces:
CCHP clip {protection-type ...}
The returned protections values identify the new protections for clip. The protection values are ATTR (Attribute Protect), MV (Rename Protect), REC (Record Protect), and RM (Delete Protect).
If the unit opens successfully, a response code 202 and separate response line containing the unit name returns.
The source clip must possess a segmented format (i.e. movie/vclip), and be complete a virtual clips. Fetal vclips cannot be processed with CBLD. All segments in the source clip must be contiguous.
If start is given, the timecode of the first frame of new-clip is set to start; Otherwise, the first frame of new-clip is assigned that of clip.
A response code of 200 indicates success.
NOTE: CBLD requires the input clip to consist exclusively of I-frame content, since editing streams based on groups of picture is not supported. Building clips derived from different bitrates and chroma formats is discouraged.
A response code of 200 indicates success.
This command is analogous to the FCLR command, except that it does not take place in the context of a unit. The clip must have previously been opened or created via COPN or CMK during the current MVCP session.
track-mask must be specified as ``*''.
A response code of 200 indicates success.
This command is analogous to the FNEW command, except that it does not take place in the context of a unit. The clip must have previously been opened or created via COPN or CMK during the current MVCP session.
track-mask must be specified as ``*''.
A response code of 200 indicates success.
This command is analogous to the FRM command, except that it does not take place in the context of a unit. The clip must have previously been opened or created via COPN or CMK during the current MVCP session.
track-mask must be specified as ``*''.
A response code of 200 indicates success.
If succesful, response code 200 is returned, and the new clip possesses a ``fetal'' state. In this state, the clip will not appear in the clip cache, although it can be deleted using CRM. In order for the clip to be visible in the clip cache and usable in the system, an initial segment must be added to it via the CUPS command. At that point, the new clip file will be written to the clip cache and become usable within the system.
The new clip will remain open for subsequent clip editing operations (see COPN) within the MVCP session duration or until explicitly closed with the CCLS command.
The clip must have been previously opened by a COPN or CMK command in the current MVCP session.
A response code of 200 indicates success.
The clip must have been previously opened by a COPN or CMK command in the current MVCP session.
A response code of 200 indicates success.
If in is specified, only segments between in and the end are returned. If out is also specified, only segments between in (inclusive) and out (exclusive) are returned. If specified, track-mask must be specified as ``*''.
The clip must have been previously opened by a COPN or CMK command in the current MVCP session.
If succesful, a response code of 201 and the following per-segment information will be returned in the following format:
trk in out clip src-trk src-clip src-in src-out
trk is universally ``*''.
in identifies the segment in-point in the clip's timeline.
out identifies the segement out-point in the clip's timeline.
clip identifies the clip name in the clip-cache corresponding to this segment. Multiple segments may share the same value for clip if they are associated with the same source clip. The associated clip will link (see CLN) the original source clip, or an actual clip, if the segment was created via a REC command in the unit context. This clip is managed automatically by the system and should generally be ignored.
src-trk is universally ``*''.
src-in identifies the segment in-point of the original source clip.
src-out identifies the segment out-point of the original source clip.
src-clip identifies original source clip name from which this segment was taken, or ``*'' if the segment was created as a result of a REC command in the unit context.
The clip must have previously been opened or created via COPN or CMK during the current MVCP session.
A response code of 200 indicates success.
A segmented virtual clip (vclip) links segments from source content clip files into a structure for playout or record. The links specify in and out timecodes pointing to source content clips. CUPS populates fetal vclips with video segments extracted from clip content files.
The new segment can be either inserted into the destination clip's timeline or can overwrite audio/video in that timeline (see dest-op below).
A homogenous vclip structure is enforced. Mixing clip formats (DV, DVCPRO, MPEG2, or DIF, for instance) is not permitted.
Streaming source clips (primarily MPEG) integrated into a segmented vclip via CUPS are ineligible for direct play out or record operations (see CBLD). Fixed frame formats such as DV or DVCPRO are eligible for segmented vclip playout or record operations.
The specified frames in the source clip can be removed, cleared, or left unchanged. In addition, if the source clip is itself segmented, the new segment in the destination clip can either reference the source clip itself, or the appropriate segments in the source clip. In this later case, if the source clip is changed in the future, it will not affect the audio/video in the destination clip (see src-op below).
clip identifies the destination clip name, must possess a segmented format, and be open within the context of the current MVCP session. src-op specifies an operation performed against the source clip's specified frames.
The possible operations are:
FCP - Copy the appropriate segments from the source clip to the destination clip. Both the source and destination must be segmented vclips (see CMK). If the source vclip changes, the destination vclip will not be altered. However, if the underlying source content clip changes, the destination vclip will change, as the copied segments directly reference the source content clip.
FLN - Link the entire source clip into the destination clip as a single segment. Unlike the FCP operation, if the source clip changes in the future, the destination clip is immediately affected. Also unlike FCP, the source clip is not required to have a segmented format. This operation is the only choice for an unsegmented source clip.
FRM - Remove the appropriate frames from the source clip after they have been copied to the destination clip. The source clip must have a segmented format. This operation implies copy semantics as opposed to link semantics as described in the FLN and FCP operations. Refer to CFRM for a full description of frame removal.
FCL - Clear the appropriate frames from the source clip after they have been copied to the destination clip. The source clip must have a segmented format. This choice implies copy semantics as opposed to link semantics as described in the FLN and FCP operations. Refer to CFCL for a full description of frame clearing. The PCI-VIDAUD-MSB-B card does not support frame clearing.
dest-op specifies whether the new segment should be inserted (FINS) into the destination clip or should overwrite (FOVR) any part of existing segments.
trk-mask must be specified as ``*''.
in identifies the new segment in-point for the destination clip's timeline.
out identifies the new segment out-point in the destination clip's timeline.
src-clip identifies the source clip name. It need not be open. The source clip audio and video format parameters must match the destination clip, unless the destination clip possesses a fetal as described in CMK.
src-trk-mask must be specified as ``*''.
src-in identifies the segment in-point for the source clip timeline. If specified as ``*'', the source clip in-point value is used.
src-out identifies the segment out-point for the source clip timeline. If specified as ``*'', the source clip out-point value is used.
If successful, the response code is 200.
attr(1) for information on file attribute
extensions.
The clip content must exist within a specific location addressable by the
clip cache prior to issuing CADD (typcally /usr/vtr/clips). If the clip format requires an ancillary index
(as is common for MPEG formats), the index file must also exist in the
appropriate index directory (typically /usr/vtr/index) before issuing CADD. Refer to vtrftp(1) for a description of the mechanism
preferred for external clip transfer to MSB.
CADD need not be issued to resolve a clip for use by other MSB commands (such as causing it to load). MSB automatically attempts to resolve and reference a clip when an MVCP session invokes a command that explicitly names it.
CADD adds a clip to MSB's clip cache such that it appears when CLS is invoked. CADD also generates the appropriate clip-add event messages for MVCP sessions that monitor the clip cache.
If a clip currently exists within the clip cache, CADD causes MSB to update the size and attributes if the content has changed in response to an external process.
The protection attribute values include ATTR (Attribute Protect), MV (Rename Protect), REC (Record Protect), and RM (Delete Protect).
When set, ATTR value precludes clip metadata modifications, such as edit in/out point modification or frame removal (CFRM) or clear operations (CFCL). When set, MV precludes the clip from rename via CMV. When set, REC attribute precludes the clip from record or append. When set, RM precludes clip deletion via CRM.
For example, the command ``CCHP NA1001 +RM -ATTR'' sets the protection on NA1001 such that the clip cannot be deleted but can have its attributes (such as its edit points) changed.
If successful, the response code is 200.
If successful, the response code is 200.
For example:
CCP palmpeg0 newclip 200 OK
NOTE: CCP does not force realign a clip as the copy proceeds. Certain clip formats, such as MSB vframe, require destination filesystems to match major and minor alignment parameters of the source.
num-clips bytes-used bytes-avail bytes-avail-contiguous
where:
num-clips states the current count of cache-resident clips.
bytes-used states the total bytes used by the clip-cache.
bytes-avail states the available free bytes within the storage systems to contain the clip cache.
bytes-avail-contiguous states the largest available contiguous amount of free bytes in the storage system.
For example:
CCST 202 OK 1 53673984 436716306432 436662632448
Specifying '*' for mark-in or mark-out removes the respective edit point.
A response code 200 returns if the command succeeds.
If successful, the response code 202 returns, and a single response line is returned containing the protection attribute values currently enabled for the clip. The allowed attribute protection values are ATTR (Attribute Protect), MV (Rename Protect), REC (Record Protect), and RM (Delete Protect).
When set, ATTR value precludes clip metadata modifications, such as edit in/out point modification or frame removal (CFRM) or clear operations (CFCL). When set, MV precludes the clip from rename via CMV. When set, REC attribute precludes the clip from record or append. When set, RM precludes clip deletion via CRM.
interleave specifies how to construct the image from the two fields of the frame: F1 (odd field only), F2 (even field only), F1F2 (both fields interleave), F1F1 (odd field line-doubled), F2F2 (even field line-doubled).
format specifies the image format to use. Possible values are ``rice'', ``rgb'', ``yuv'', ``jpeg'', and ``tiff''. If format is not specified, the format is inferred from the filename extension (``.rice'', ``.rgb'', ``.yuv'', ``.jpg'', ``.tiff'').
A response code 200 returns if the command succeeds.
clip format size resident-size start end in out rate time-of-last-modification clip-type
clip identifies the clip name.
format identifies the clip format.
size identifies clip content size in bytes.
resident-size identifies the cache-resident clip content size in bytes
start states the clip timecode of the first time.
end states the clip timecode of the last frame.
in identifies the clip current mark-in timecode.
out identifies the clip current mark-out timecode.
rate specifies the frame rate (in frames/sec) corresponding to the unit location. 525-line drop-frame timing is specified in its approximate form, 29.97 (525 non-drop-frame is 30). Translation between drop-frame and non-drop-frame is not performed regardless of FRAT setting.
time-of-last-modification states clip modification time and disk update, and possesses the format yyyymmddThhmmss.microsecsZ. For example, a value of 19990316T020942.836820Z means the clip was last modified 16th March, 1999 at two hours, nine minutes, forty two seconds and 836820 microseconds past midnight GMT.
clip-type specifies either CL or LN. The value LN implies that clip creation was performed as a link to another clip. The value CL implies the clip is unassociated.
If the original clip is deleted, the new clip retains the the original clip content until the new clip is also deleted.
This command is useful for creating clips which refer to segments of other clips.
If successful, the response code is 200.
clip format size resident-size start end in out rate time-of-last-modification clip-type
clip identifies the clip name.
format identifies clip format.
size identifies clip content size in bytes.
resident-size identifies the cache-resident clip content size in bytes
start states the clip timecode of the first time.
end states the clip timecode of the last frame.
in identifies the clip current mark-in timecode.
out identifies the clip current mark-out timecode.
rate specifies the frame rate (in frames/sec) corresponding to the unit location. 525-line drop-frame timing is specified in its approximate form, 29.97 (525 non-drop-frame is 30). Translation between drop-frame and non-drop-frame is not performed regardless of FRAT setting.
time-of-last-modification states clip modification time and disk update, and possesses the format yyyymmddThhmmss.microsecsZ. For example, a value of 19990316T020942.836820Z means the clip was last modified 16th March, 1999 at two hours, nine minutes, forty two seconds and 836820 microseconds past midnight GMT.
clip-type specifies either CL or LN. The value LN implies that clip creation was performed as a link to another clip. The value CL implies the clip is unassociated.
The CMON (Clip Monitor) command must be issued to initiate clip cache monitoring before CLSA is entered by the current MVCP session.
If successful, the response code is 201 and one response line is returned for each newly added clip which contains the clip's name. A blank line terminates the list of clips.
If the command is successful, the response code is 201 and for each clip found, one response line is returned in the following format:
clip-name clip-type
clip-type contains LN (a clip link) or CL (an unassocated clip).
The CMON (Clip Monitor) command must be issued to initiate monitoring of the clip cache by the current MVCP session.
If successful, the response code is 201 and one response line is returned for each removed clip which contains the clip's name. A blank line terminates the list of clips.
The response code is 200, and a single response line is returned in the following format:
num-clips-added num-clips-removed
where:
num-clips-added identifies the number of added clips.
num-clips-removed identifies the number of removed clips.
If the CMON command is issued for a second or subsequent time, the current list of added and removed clips is discarded and monitoring is initialized again.
The response code is 200.
If successful, the response code is 200.
For example:
CMV newclip oldclip 200 OK
NOTE: CMV cannot be used to move clips between file systems; use CCP instead.
The following flags may be specified:
PRGE - Purge the clip from the clip cache (in memory), but do not actually delete it from the disk.
IMM - If the clip is currently loaded by a unit, fail instead of doing a deferred delete.
If the command is successful, the response code is 200.
If the command is successful, the response code is 200.
For example:
CRMA 200 OK CLS 201 OK
Since clip operations are synchronous, a separate MVCP session must issue the CINT command.
If there is no clip operation associated with clip or the operation completed, the response code is 505, ``Unable to interrupt clip operation''.
If the command succeeds, the response code is 200.
If successful, response code is 201, and one response line is returned for each matching control in the following format:
subsystem-name control-name ``control-value''
For example:
SGET clipmirror * 201 OK clipmirror vtr.clipmirror.local_server.hostname "" clipmirror vtr.clipmirror.max_threads "20" clipmirror vtr.clipmirror.primary_server.hostname "" clipmirror vtr.clipmirror.reconnect_interval "30"
The possible values for control-name and control-value are subsystem-dependent and in msb-controls(5).
For example:
SSET clipmirror vtr.clipmirror.max_threads 24 200 OK SGET clipmirror *thread* 201 OK clipmirror vtr.clipmirror.max_threads "24"
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 identifies the component instance name generating the statistic.
statistic name identifies the statistical value name.
value identifies the integer or floating-point statistical value. The value of certain types of statistics (e.g., histogram) may include more than one number.
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 identifies the number of statistical values matching the pattern.
samples identifies the total number of samples collected.
min identifies the minimum value.
max identifies the maximum value.
sum identifies the sum of the values.
mean identifies the mean of the values.
stddev identifies the standard deviation of the values.
The response code is 202, and a single response line is returned in the following format:
code ``description''
where:
code identifies the error code.
description identifies the error description. If no error occured from the last command a ``*'' is used for the message text.
For example:
ERR 202 OK 0 "*"
The frame rate is set initially according to the value of the system control vtr.main.timing_standard.
The FRAT command applies only to the current MVCP session.
hh:mm:ss:ff yyyymmddThhmmss.ssssssZ UST
If out is specified, the clip is cued with the specified out point, meaning playback will terminate at the specified frame. If out is missing or specified as '*', the mark-out point stored with the clip is used, or if mark-out is not set, no out point is used.
If out is specified, in must be specified.
If either in or out is specified and not '*', the other may be specified as a duration by adding a '+' prefix character. For example, ``1:00:01:00 1:00:06:00'', ``1:00:01:00 +5:00'', and ``+5:00 1:00:06:00'' imply an identical edit range.
The optional direction argument specifies the playback direction: FWD is forward, BWD is backward, F/B is forward followed by backward, B/F is backward followed by forward. The default direction is forward (FWD).
The optional passes argument specifies how many passes through the clip are made. The default is 1 pass. Specify passes as 0 to repeat indefinitely (use the STOP command to terminate playout).
If passes is specified as -1, the unit is cued in free-range mode (for media devices that support free-range cueing). In free-range mode, the in point is used only as the initial location but does not define the lower limit of playback. The lower limit is defined by the vtr.media.clip.limit.start control, if set, or the start of the clip if the clip limit control is not set.
In free-range mode, the upper limit of playback is defined by the specified out-point. If the out-point is not set, the upper limit is defined by the vtr.media.clip.limit.end control, if set, or the end of the clip if the clip limit control is not set.
The optional tc-track argument specifies the time code track from which the edit points in and out are selected: CLIP is the control track, VITC is the vitc track, LTC is the ltc track. If not specified, the default time code track will be used.
If the command succeeds, the response code is 200.
If out is specified, the clip is cued with that out-point, meaning recording will terminate at the specified frame. If out is missing or specified as '*', recording will continue until the unit is stopped. If out is specified, in must also be specified.
If either in or out is specified and not '*', the other may be specified as a duration by adding a '+' prefix character. For example ``1:00:01:00 1:00:06:00'', ``1:00:01:00 +5:00'', and ``+5:00 1:00:06:00'' imply an identical edit range.
If the command succeeds, the response code is 200.
If the command succeeds, the response code is 200.
The clip must be loaded for input (IN) or input/output (BOTH).
If the command succeeds, the response code is 200.
If the command succeeds, the response code is 200.
The clip must be loaded for input (IN) or input/output (BOTH).
If the command succeeds, the response code is 200.
The clip must be loaded for input (IN) or input/output (BOTH).
If the command succeeds, the response code is 200.
The clip must be loaded for input (IN) or input/output (BOTH).
If the command succeeds, the response code is 200.
The clip must be loaded for input (IN) or input/output (BOTH).
If the command succeeds, the response code is 200.
The possible values for control-name-pattern are device-dependent are described elsewhere. If the pattern contains wildcards, the values of all controls that match the specified pattern will be returned.
If successful, response code is 201, and one response line is returned for each matching control in the following format:
control-name ``control-value''
For example:
UADD MFCODEC_6 * EXCL * 202 OK U1 GET U1 MED *gop* 201 OK vtr.media.video.input.compression.gop_on_scene_change "true" vtr.media.video.input.compression.gop_size "1" vtr.media.video.input.compression.gop_structure "I"
The load-options indicate special handling for the clip when loading it. Zero or more options may be specified. Possible values are:
CRTE Create the clip if it does not exist.
NOEX Fail if the clip exists.
EPHM Create an ephemeral clip (automatically deleted when the clip is unloaded).
If successful, the response code is 202 and a single response line is returned in the following format:
format size resident-size start end in out rate
clip identifies the clip name.
format identifies the clip format (mpeg2, dvcpro, vframe, etc).
size identifies clip content size in bytes.
resident-size identifies the cache-resident clip content size in bytes
start states the clip timecode of the first time.
end states the clip timecode of the last frame.
in identifies the clip current mark-in timecode.
out identifies the clip current mark-out timecode.
rate identifies the clip frame rate (in frames/sec). 525-line drop-frame timing is specified in its approximate form, 29.97 (525 non-drop-frame is 30). Drop-frame and non-drop-frame translation is not performed irrespective of FRAT setting. 625-line is represented as 25 frames per second.
If the unit is playing, the video output will be a still frame at the paused clip location.
If the command succeeds, the response code is 200.
Some media ports must be explicitly cued before starting playback. For those devices, PLAY cannot be used to resume playback after a STOP command is issued. The unit must be re-cued.
If the command succeeds, the response code is 200.
Some media ports must be explicitly cued before record commences. For those devices, REC cannot resume recording after a STOP command is issued; the unit must be re-cued.
If the command succeeds, the response code is 200.
If the command succeeds, the response code is 200.
If the command succeeds, the response code is 200.
If the command succeeds, the response code is 200.
If the command succeeds, the response code is 200.
For each control, a name and a value must be provided. At least one control name/value pair must be specified. If the control value contains any spaces or tabs, the value must be enclosed in double quotes.
The possible values for control-name and control-value are device-dependent and are described elsewhere.
If the command succeeds, the response code is 200.
For example:
UADD MFCODEC_6 * EXCL * 202 OK U1 GET U1 MED *gop* 201 OK vtr.media.video.input.compression.gop_on_scene_change "true" vtr.media.video.input.compression.gop_size "1" vtr.media.video.input.compression.gop_structure "I"
SET U1 MED vtr.media.video.input.compression.gop_on_scene_change
false
200 OK
GET U1 MED vtr.media.video.input.compression.gop_on_scene_change 201 OK vtr.media.video.input.compression.gop_on_scene_change "false"
Positive speeds play forward. Negative speeds play backward. The actual shuttle speeds available are device-dependent.
If the command succeeds, the response code is 200.
Some media ports require that the unit already be in a playback state when STEP is issued.
If the command succeeds, the response code is 200.
STON is supported by only some media ports.
If the command succeeds, the response code is 200.
For some media ports, playback or recording cannot be resumed until the unit is re-cued with a CUE or CUER command, respectively.
If the command succeeds, the response code is 200.
If the command is successful, response code 200 is returned.
For example:
UCLS U1 200 OK
If the command is successful, the response code 202 is returned followed by a data line:
code ``description''
where:
code identifies the last error code.
description identifies the error code text.
If the command succeeds, the response code is 200.
For example:
UCLS U1 200 OK UOPN U1 510 Unable to open unit UERR 403 Unit not open
If the command succeeds, the response code is 200.
The response code is 202 and single response line is returned in the following format:
owner port-name port-mode port-physical-name
where:
owner identifies the MVCP session name responsible for unit creation.
port-name identifies the media port name controlled by the unit.
port-mode identifies the input/output mode supported by the unit. The possible values are IN, OUT, and BOTH.
port-physical-name identifies the media port physical name controlled by the unit.
If the command succeeds, the response code is 200.
The response code is 202 and a single response line is returned in the following format:
clip-loc vitc ltc UTC-time UST-time rate
where:
clip-loc states the clip location, which corresponds to an approximate CTL (control track) timecode.
vitc states the frame VITC (vertical interval timecode).
ltc states the frame LTC (longitudinal timecode).
UTC-time states the unit UTC time 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 states the UST (unadjusted system time) time at the specified location. This time can be used to account for application or network latency in time reporting.
rate states the timecode rate (in frames/sec) corresponding to the specified clip location. 525-line drop-frame timing is specified in its approximate form, 29.97 (525 non-drop-frame is 30). 625-line is represented as 25 frames per second.
If successful, the response code is 200.
If successful, the response code is 202, and a single response line is returned in the following format:
clip status function location speed rate command-id
clip identifies the loaded clip name (``*'' if no clip is loaded).
status states the unit's current function status (BUSY - OP IN-PROGRESS, RUN - RUNNING, DONE - COMPLETE, ERR - ERROR).
function identifies the current function: IDLE, LOAD, UNLD (Unload), CUE, CUER (Cue for record), PLAY, STEP, SHTL (Shuttle), REC (Record), PAUS (Pause), STON (StandbyOn), STOP, FF (Fast Forward), REW (Rewind).
location identifies the current clip location in hours:minutes:seconds:frames format. In drop-frame mode, a period (.) replaces the last colon (:).
speed specifies the current playback speed (1000 = normal 1x speed).
rate specifies the frame rate (in frames/sec) corresponding to the unit location. 525-line drop-frame timing is specified in its approximate form, 29.97 (525 non-drop-frame is 30). command-id identifies the unit's MVCP command in-process. 625-line is represented as 25 frames per second.
Once the USYN command has been used to set the default synchronization mode, all unit commands which do not specify a sync mode will use this default.
For the possible values of sync-mode, see SYNCHRONIZATION below. Both units must be opened by the current MVCP session.
If wait-id is not specified, the unit waits for the command at the end of the target unit's command queue when the UUWT starts execution in the unit (not when the UUWT is issued to the unit).
The target command id can be obtained by using the /CID qualifier on the target unit command.
For the possible values of sync-mode, see SYNCHRONIZATION below.
By default, when a command is issued to a unit, the unit's command queue is immediately flushed of any commands which are waiting to be executed by the unit, and the command preempts the previous command that was issued to the unit, even if that command has not completed execution.
Also by default, the MVCP session returns a response to the client as soon as the command queues for the unit. The generated reply in response to a command means that the command was successfully queued, not that the command completed successfully or started execution.
The async (ASYN) mode implies the MVCP session receives a reply when the command queues, but immediate command initiation is not guaranteed, and may be deferred.
Sync-init (SYNI) mode delays response until the unit reaches command initialization state. This does not mean that the unit has initiated command execution, but that the command may block on a shared resource (such as the media port), and will wait for the resource to become available before continuing.
Sync-run (SYNR) mode delays response until the unit reaches the command initiated state. This means that the unit contemporaneously processes the command. For instance, the running state for a PLAY command means that video playout is currently active.
Sync-complete (SYNC) mode delays response until the unit reaches a finished, terminal state. This means that the unit ceases further processing. If the command is CUE, the finished state is achieved when the unit fully cues the clip and is ready to playout. If the command is PLAY, the complete state is achieved reached when playback finishes.
If no error occurs in the unit before the desired sync state is reached, the response code is 200 (or 201, or 202, as appropriate). If an error occurs before the unit reaches the desired state, an error response code returns.
The default command synchronization mode for a unit may be changed using the USYN command. Or, the default may be overridden on a individual command basis by prepending a forward slash (/) and the sync mode to the unit command. For example, the command ``PLAY U5'' uses the default sync mode, while the command ``/SYNC PLAY U5'' specifies that the command response should not be sent until the PLAY command completes execution.
The ``previous'' command may be issued with a qualifier that defers execution of the ``next'' command until the ``previous'' command reaches a specified status. The ``next'' command may be issued with a qualifier that defers its execution until the ``previous'' command has reached a certain status.
The preemption modes available for the ``previous'' command are NNO (no deferral), NINI (defer next until Init), NRUN (defer next until Running), NCMP (defer next until Complete).
The preemption modes available for the ``next'' command are PNO (no deferral), PINI (defer until previous Init), PRUN (defer until previous Running), PCMP (defer until previous Complete). POVR may also be used to override the defer-next preemption mode of the ``previous'' command.
NOTE: The IMM and SEQ qualifiers have been superceded by the new preemption qualifiers, but are still supported for compatibility. IMM corresponds to PNO and SEQ corresponds to PCMP.
The default command sequencing is flush/no-defer-next/no-defer-previous, meaning that when an MVCP command is issued, the unit command queue is flushed and the command preempts whatever command is currently being executed by the unit.
The default command sequencing mode for a unit may be changed using the USYN command. Or, the default may be overridden on a individual command basis by prepending a forward slash (/) and the sequencing mode to the unit command. For example, the command ``PLAY U5'' uses the default sequencing mode, while the command ``/APP PLAY U5'' specifies that the command should be appended to the unit's command queue.
The default preemption and queuing modes are overridden individually. For example, ``/APP /PCMP PLAY U5'' places the PLAY command at the end of the command queue and the command does not begin executing until the previous command has completed.
Three common sequencing combinations can be abbreviated:
/SEQA is equivalent to /APP /PCMP.
/IMMP is equivalent to /PRE /PNO.
/IMMF is equivalent to /FLSH /PNO.
The timecode form, HH:MM:SS:FF may be used to specify the time relative to midnight local time calculated using current frame rate (which is initially set according to the system control vtr.main.timing_standard and can be set with FRAT). For instance, 14:14:00:00 specifies that the command should start at exactly 2:14pm local time.
The ISO 8601 date/time form, yyyymmddThhmmss.ssssssZ, may be used to specify the command time.
Finally, the time-of-day form, SEC.USEC, may be used to specify the time using a more traditional UNIX timebase. SEC is the number of seconds since the standard Epoch, Jan 1, 1970. USEC is microseconds.
Example:
LOAD U1 a/COMM OUT
/SEQA CUE U1
/SEQA @17:31:00:02 PLAY U1
NOTE: If the system is receiving house timecode (via Little Red), command timing will be based on the incoming time; otherwise, the system time will be used.
The format of the response header line is a three-digit response code followed by an informational string. Some examples:
200 OK
410 Invalid clip time
500 Server error
The response codes are divided into the following categories.
2XX Successful command execution
4XX Command format or setup error
5XX Command execution error
The 2XX success codes include:
200 OK (Success with no additional data)
201 OK (Success with N data lines followed by a blank line)
202 OK (Success with one data line)
Numeric codes for error return values may be overloaded with distinct error text messages. The 4XX format error codes include:
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 Invalid load flag(s)
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
439 Sync modifier not supported for this command
440 Invalid frame-rate
441 Invalid target command id
442 Invalid count
443 Invalid unload flag
444 Channel name missing
445 Channel opened on different port (<portname>)
446 Channel not open
447 Channel name missing
448 Too many arguments
449 Clip not open
450 Clip name missing
451 Clip already open
452 Format name missing
453 Source clip name missing
454 Invalid track mask
455 Invalid clip source update mode
456 Invalid clip destination update mode
457 User name missing
458 Password missing
459 Already logged in as <username>
460 Must provide USERname first
461 Must login with USERname and PASSword
462 Subsystem name missing
463 Invalid time channel
The 5XX execution error codes include:
500 General error (message varies)
510 General error (message varies)
511 General error (message varies)
530 Login incorrect