Chapter 11. Completing Common Tasks Using MVCP Commands

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:

Manual Access to Video Server Toolkit

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
Connected to server.
Escape character is `^]'.

100 VTR Ready

Concluding a Session

To exit the telnet session, type the following command:


Creating and Deleting a Unit

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:


The UADD command returns the name of the unit, unitName, for example:

202 OK

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.

Deleting a Unit

Units can be deleted using the following command:

UCLS unitName

Multiple Connections to a Unit

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.

Loading, Creating, and Unloading a Clip

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.

Finding the Name of a Clip

If you do not know the name of a clip, you can list all of the clips by issuing the clip list command:


Setting Edit Points

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.

Cueing Decks to Play or Record

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

Optional Arguments

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

Sequencing Commands

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

Playing a Prerecorded Clip

To play a clip, use the following procedure:

  1. Open a TCP/IP connection to a host machine running VST.

    If successful, VST responds:

    100 VTR Ready

  2. Create a unit, which is a virtual videotape deck:


    For an explanation of the UADD options, see “UADD *owner* *port* *mode* *port-physical-name*”.

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

  4. Cue the clip for playback:

    CUE unitName

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

Setting and Listing Configuration Values

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:

GET unitName MED*

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.

Listing Video and Deck Control Ports

To display the configuration of video and deck control ports, use the port list command:


Identifying the Audio Ports to Use

To identify which audio port to use by a given DIVO unit, use the SET command for a unit:

SET <unit> MED RAD1.AESOut

Alternately, you can configure a unit in /usr/vtr/config/device-defaults/*. For example, in DIVO_1 you would enter: RAD1.AESIn RAD1.AESOut

Configuring Audio Recording

To record audio using VST, you must set the following controls:

  • Bits in audio sampling, 24 by default—

  • Sampling rate, 48,000 by default—

  • Audio port used—

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

Configuring Video Recording Compression

To record video using VST, you must set the compression type using

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

Recording a Clip

To record a clip, use the following procedure:

  1. Open a TCP/IP connection to a host machine running VST.

    If successful, VST responds:

    100 VTR Ready

  2. Create a unit, which is a virtual videotape deck:


    For an explanation of the UADD options, see “UADD *media-port-name* *storage-port-name* *port-sharing-mode* [ *owner-info* ]”.

  3. Configure VST for audio and video recording, as described in “Configuring Audio Recording” and “Configuring Video Recording Compression”.

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

  5. Cue the clip for recording:

    CUER unitName

  6. Record onto the clip:

    REC unitName 

Editing Clips

You can edit clips on two levels of granularity:

  • Clip

  • Frame

Editing Clips

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

Editing Frames

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.

Displaying Your Logo

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: image user <name of image>

Image files go in /usr/vtr/data/images.

Playing Clips from a Playlist

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.

  1. Create a unit on the media port.

    UADD port
    202 OK

  2. Create a second unit on the same media port.

    UADD port
    202 OK

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

  4. Cue U1 with a mode that will return when the command is placed in the command queue.

    /SEQA CUE U1
    200 OK

  5. Play U1 with a synchronization mode where a response will be returned only when the unit has started executing the command.

    200 OK

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

  7. Cue U2 with a queued command.

    /SEQA CUE U2
    200 OK

  8. Play U2 as with U1 above.

    200 OK

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

  10. Cue U1 with a queued command.

    /SEQA CUE U1
    200 OK

  11. Play U1 as above.

    200 OK

Monitoring Unit State

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


Record Unit State (frames)

Play Unit State (frames)










MPEG-2 Vela

Device supports only play.


(development only)



Monitoring the System

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


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 * *

Statistics on Statistics

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:


If the command is successful, a single line is returned in the following format:

values samples min max sum mean stddev


  • 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*]]”.

Error Reporting

VST reports three types of errors:

  • MVCP command syntax errors

  • Controller errors

  • Unit Errors

MVCP Command Syntax Errors

All MVCP commands return error responses for syntax violations, for example, entering a letter instead of a number.

Controller Errors

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:


This command returns an error code and a short description.

Unit Errors

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

This command returns an error code and a short description.