This chapter is a grab bag of common tasks you routinely perform using MVCP commands. Each task is discussed in a tutorial fashion to introduce you to the way MVCP works. Once you master the basic tasks presented in this chapter, you can proceed to the other features offered by MVCP commands.
The tasks presented in this chapter are not sequential, but modular. There is a flow to the MVCP commands as presented; however, one command does not necessarily build on the one presented previous to it.
After completing a number of these tasks you will gain a feeling for the MVCP commands. Appendix A describes all of the MVCP commands.
 | Note: For an explanation of MVCP commands, see the mvcp man page. |
This chapter discusses the following tasks:
Video Server Toolkit (VST) applications routinely open a TCP/IP connection to a host running VST on the MVCP port, normally 5250. The application sends MVCP commands to control VST.
The port value is set in the file /usr/vtr/config/control-in.conf. For example, to set the port to 5250, use the following line in the file:
mvcp tcp 5250 |
| Note: Do not change the port value from 5250 unless it is absolutely necessary. |
You can, however, manually control VST by opening a telnet connection to a host running VST and then issuing MVCP commands to control it. For example:
152% telnet server 5250 Trying 130.62.156.178... Connected to server. Escape character is `^]'. 100 VTR Ready |
A unit is a virtual VTR. It can play and record video and audio just like a VTR.
Units can be created using the following command:
UADD DIVO_0 * SHAR |
The UADD command returns the name of the unit, unitName, for example:
UADD DIVO_0 * SHAR 202 OK U1 |
U1, in this case, controls the DIVO_0 video board, which includes both an input video port and an output video port.
For an explanation of the UADD options, see page 138. For more information about deleting a unit, see page 166.
Once a unit has been created, it can be controlled by a number of MVCP connections by opening it:
UOPN unitName |
When multiple MVCP connections are made to one unit, the unit is not deleted until all of the connections have deleted it.
 | Warning: Opening a unit owned by a Sony, Louth, or Odetics port using MVCP commands (for example, UOPN) causes unpredictable behavior. |
To load and unload a clip into a unit, use the following commands, respectively:
LOAD unitName clipName OUT CRTE UNLD unitName |
unitName is the name of the unit on which the clip is loaded.
The OUT option means that the clip, clipName, can only be played, not recorded onto. Other valid values include IN, which means the clip will be recorded onto, and BOTH, which means the clip can be played or recorded onto.
CRTE creates the clip. Without a CRTE argument, the clip does not exist in the system.
If you do not know the name of a clip, you can list all of the clips by issuing the clip list command:
CLS |
The IN and OUT edit points specify where the source video is to begin and end playing, and where the beginning and ending recording points are on the record deck, usually VST.
When a clip is played, by default the edit IN point is used as the starting point for PLAY.
To set edit points, use the CEDP command:
CEDP clipName inPoint outPoint |
| Note: The media outside of the in and out points is not actually erased; its just not played. |
You can play and record on units without cueing them. There is, however, a good chance that the beginning of the playing or recording will not be clean: the frame count might be off by several frames or the audio might be garbled.
You can avoid these problems by cueing the units for playing or recording.
To cue a clip for playback, enter:
CUE unitName |
To ca clip for recording, enter:
CUER unitName |
The following optional CUE and CUER arguments specify the segment of media to play, the direction of play and how many times the segment is played:
CUE unitName <in-point> <out-point> <direction> <number-of-passes> |
Values for direction include FWD (forward), BWK (backward), F/B (play forward and then play backwards), and B/F (play backward and then play forward).
You can sequence more than one command to execute on a unit by using the append-sequential specification:
/APP /SEQ command unitName |
This command specifies that the command, command, is appended (/APP) to the current list of commands queued for the unit, unitName, and the command will be executed after the previous command in the list completes (/SEQ). The alternative to waiting for completion is to preempt the previous command on the list using the flag, /IMM.
You can also:
Prepend a command in the list of commands by using /PRE instead of /APP.
Delete the command list and replace it with a command using /FLS (flush) instead of /APP.
For more information about command sequencing, see “Command Sequencing”.
To play a clip, use the following procedure:
Open a TCP/IP connection to a host machine running VST.
If successful, VST responds:
100 VTR Ready
Create a unit, which is a virtual videotape deck:
UADD DIVO_0 * SHAR
For an explanation of the UADD options, see “UADD *owner* *port* *mode* *port-physical-name*”.
Load the clip:
LOAD unitName clipName OUT
unitName is the name of the unit on which the clip is loaded.
The OUT option means that the clip, clipName, can only be played, not recorded onto.
Cue the clip for playback:
CUE unitName
Play the clip:
PLAY unitName speed
speed is the speed of the playback, for example, 1000 is normal play, -1000 is normal reverse play.
You can also play the clip in other modes, such as:
FF—fast forward.
JOG—advance or reverse one frame at a time.
SHTL—(shuttle) is a variable speed fast forward or fast reverse.
For more information about the arguments for each of these commands, see “Unit Commands”.
VST configuration variables are called controls. The two major categories of controls are:
Device-specific—for which you use the SET and GET commands to specify and retrieve the control values for individual units.
System-wide—for which you use the SSET and SGET commands to specify and retrieve the control values for global, system values, for example, the log level.
There are two subsets of device-specific controls:
Storage—for reading digital data off a disk or writing the data to a disk.
Media—for communicating with the video port.
To set or get the configuration variables for a specific unit, you have to select the subset of controls you want to set by using STOR (storage) or MED (media). For example:
SET unitName MED vtr.media.video.input.compression.type DVCPRO GET unitName MED vtr.media.video.output.* |
These commands set the video compression type to DVCPRO, and return all of the video output controls for the specified unit.
To list all of the storage controls, use the asterisk (*) wildcard: GET unitName STOR *
For more information about the SET command, see page 165. For more information about the SSET command, see page 150
For more information about the GET command, see page 162. For more information about the SGET command, see page 150.
To display the configuration of video and deck control ports, use the port list command:
PLS |
To identify which audio port to use by a given DIVO unit, use the SET command for a unit:
SET <unit> MED vtr.media.audio.input.port RAD1.AESIn SET <unit> MED vtr.media.audio.output.port RAD1.AESOut |
Alternately, you can configure a unit in /usr/vtr/config/device-defaults/*. For example, in DIVO_1 you would enter:
vtr.media.audio.input.port RAD1.AESIn vtr.media.audio.output.port RAD1.AESOut |
To record audio using VST, you must set the following controls:
Bits in audio sampling, 24 by default—vtr.media.audio.input.sample.width
Sampling rate, 48,000 by default—vtr.media.audio.input.rate
Audio port used—vtr.media.audio.input.port
The audio port can either be VideoIn, if the audio is embedded in the video signal, or the name of an audio port, for example, AnalogIn or AESIn.
For information about setting control values, see “Setting and Listing Configuration Values”.
To record video using VST, you must set the compression type using vtr.media.video.input.compression.type.
Valid values include JPEG, for O2, or, for machines using DIVO boards:
none—for uncompressed.
rice—for lossless entropy-coding.
DVCPRO— for high-quality DCT-based compression
For information about setting control values, see “Setting and Listing Configuration Values”.
There are other commands that you might set according to your media format. For a list of those settings, see “Workflow to Generate a Single 4:2:2:4 Clip”.
To record a clip, use the following procedure:
Open a TCP/IP connection to a host machine running VST.
If successful, VST responds:
100 VTR Ready
Create a unit, which is a virtual videotape deck:
UADD DIVO_0 * SHAR
For an explanation of the UADD options, see “UADD *media-port-name* *storage-port-name* *port-sharing-mode* [ *owner-info* ]”.
Configure VST for audio and video recording, as described in “Configuring Audio Recording” and “Configuring Video Recording Compression”.
Load the clip:
LOAD unitName clipName BOTH CRTE
unitName is the name of the unit on which the clip is loaded.
The BOTH option means that the clip, clipName, can be played or recorded onto. The CRTE option means that the clip should be created if it does not exist.
Cue the clip for recording:
CUER unitName
Record onto the clip:
REC unitName
You can edit clips on two levels of granularity:
Clip
Frame
The following MVCP commands provide basic editing functionality for a clip already loaded in a unit:
CEDP—sets in and out edit points.
CEDIT InPoint OutPoint
CRM—removes a clip.
CRM clipName
CCP—copies a clip.
CCP clipName newClipName
CMV—renames a clip.
CMV clipName newClipName
CLN—creates a new clip that shares its contents with an existing clip.
CLN clipName newClipName
When using CLN, changing one clip also changes the renamed clip because of their link.
For more information about setting in and out editing points, see “Setting Edit Points”.
The following MVCP commands manipulate the frames within a clip that is already loaded in a unit:
FRM—remove a frame. In film, the equivalent is cutting out frames of film and splicing the two parts of the film back together.
FRM unitName inFrame outFrame
FCLR—changes (clears) a frame to black but does not remove it.
FCLR unitName inFrame outFrame
FNEW—inserts a black frame into the clip.
FNEW unitName inFrame outFrame
FOVR—moves frames from one part of a clip and overwrites frames in another part of the clip.
FOVR unitName sourceIn sourceOut destIn
FINS—moves frames from one part of a clip and inserts them in another part of the clip.
FINS unitName sourceIn sourceOut destIn
| Note: Frame editing is not supported on all clip formats. Currently, only vframe clips can be frame-edited. |
You can use the MVCP SET command with the following controls to display your company logo, or any image, when the video port is not playing a clip:
vtr.media.output.idle_mode image vtr.media.video.output.image.type user vtr.media.video.output.image.name <name of image> |
Image files go in /usr/vtr/data/images.
The commands to execute a playlist can be performed over a single MVCP control connection. Some control implementations may find it easier to use a unique MVCP control connection for each unit. The commands and the order in which they are sent is identical in either case.
Create a unit on the media port.
UADD port 202 OK U1
Create a second unit on the same media port.
UADD port 202 OK U2
Load the first clip into U1.
LOAD U1 clip1 OUT 202 OK clip1 movie/dif/dvcpro 108969984 108969984 00:00:00.00 00:00:30.08 * * 29.97 19990415T004204.435814Z CL
Cue U1 with a mode that will return when the command is placed in the command queue.
/SEQA CUE U1 200 OK
Play U1 with a synchronization mode where a response will be returned only when the unit has started executing the command.
/SEQA /SYNR PLAY U1 200 OK
Load next clip into U2.
LOAD U2 clip2 OUT 202 OK clip2 movie/dif/dvcpro 108969984 108969984 00:00:00.00 00:00:30.08 * * 29.97 19990415T004130.833005Z CL
Cue U2 with a queued command.
/SEQA CUE U2 200 OK
Play U2 as with U1 above.
/SEQA /SYNR PLAY U2 200 OK
Load next clip into U1.
LOAD U1 clip3 OUT 202 OK clip3 movie/dif/dvcpro 108969984 108969984 00:00:00.00 00:00:30.08 * * 29.97 19990415T004148.636950Z CL
Cue U1 with a queued command.
/SEQA CUE U1 200 OK
Play U1 as above.
/SEQA /SYNR PLAY U1 200 OK
When executing a play list, it is common to also desire display of the state of the list execution. Using MVCP this can be accomplished via polling, but a more efficient solution is to utilize unit monitoring. Unit monitoring provides asynchronous events describing the change in state of a unit, such a execution state, loaded clips, or timecode location. Details of unit monitoring can be found in the MVCP documentation for the MON command. Typically a separate MVCP connection will be initiated for monitoring.
In the example play list algorithm above, a unit monitor could be started after the units are created to trace unit execution. This would allow a control application to trace which clip was being played and the timecode location of the unit in the clip. Note that the information provided by unit monitoring describes the unit state and locations. The actual video frame timecode leaving the server port will be some fixed number of frames behind that time due to codec delays. This delay is format dependent and can be found in the table below. The table shows the difference between the time reported by the unit and the actual video frame at the server port at a that time. For instance, with DVCPRO on record the unit status reports 3 frames behind the frame on the input of the server, and on play the unit status reports 7 frames ahead of the frame on the server output port.
Table 11-1. Time Reported by the Unit and the Actual Video Frame
Format | Record Unit State (frames) | Play Unit State (frames) |
|---|---|---|
Uncompressed | -2 | +2 |
RICE | -2 | +2 |
DVCPRO | -3 | +7 |
MPEG-2 Vela | Device supports only play. | 21 |
O2 M-JPEG | 2 | 2 |
VST provides the following ways to monitor the system:
Status of units
Continuous monitoring of a unit
Listing statistics
Error reporting
The following sections explain each of these reports in further detail:
You can display the status of one unit or all units using the following commands, respectively:
USTA unitName ULS |
For continuous monitoring of a unit, you use the MON command:
MON [unitName] [/ eventType] |
If you omit a unit name, all of the units are monitored.
You can receive notification when any of the following events occurs on a unit in the clip cache, as appropriate:
UADD—unit added
URM—unit removed
UCHG—unit state changed
UCTL—unit control changed
UERR—unit error
CADD—clip added
CRM—clip removed
CEDP—edit points changed
CCHG—clip media changed
CMV—clip moved
CCHP—clip protection changed
You can add one or more of these event types to the MON command after the slash (/) that separates the unit names from the event types.
If event types are not specified, notification of UCHG, URM, and UCTL events are returned. If a unit name is not specified, notification of each UADD event is returned.
MON prevents an MVCP connection from processing any further commands. To stop monitoring, you must either close the MVCP connection or issue another command on the connection at which time monitoring is terminated.
For more information about the MON command, see page 138.
You can return statistics values for one or all components in a system using the list statistics command:
STLS [componentName [statisticsType]] |
componentName is the name of the component you want statistics about. If omitted, statistics for all components are returned.
statisticsType is the type of statistics you want returned. If omitted, all statistics for the specified component are returned.
If successful, the STLS command returns a line of the following form:
componentName statisticsType statisticsValue...
To see the list of available statistics, type
STLS * * |
You can return statistical values about a component's or all component's statistics using the following command:
STST [componentName [statisticsType]] |
For example, the following command calculates all the statistics for components that contain “DIVO” in their names:
STST *DIVO* |
If the command is successful, a single 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.
For more information about STST, see “STST [*component-pattern* [*statistic-pattern*]]”.
VST reports three types of errors:
MVCP command syntax errors
Controller errors
Unit Errors
All MVCP commands return error responses for syntax violations, for example, entering a letter instead of a number.
All controller and non-unit errors, such as errors in renaming or deleting a clip, return a generic notification that something failed. To receive more specific information about the most recent global error that occurred for a specific controller, use the ERR command:
ERR |
This command returns an error code and a short description.
Unit errors are errors in the execution of unit commands, such as PLAY, REC, and FF. When looking at the status of a unit, you might find it in the error state, as described in “Status”. In that case, you might like to get more information about the error.
To return unit errors, use the UERR command:
UERR unitName |