Chapter 3
Video Server Utilities

The Video Server utilities perform special operations on content files in the Oracle Media Data Store (MDS) or a host file system. These utilities include:

vsmpegchk	Verifies the integrity of MPEG2 content files.
vstag	Generates tag files for content files.
vstagpatch	Modifies tag files.
vstagprint	Prints tag files.
vswrap	Converts binary files to a format for transmission to a set-top box and tags them.

General Information

The following information applies to video server utilities.

Oracle Media Data Store Files

Refer to Chapter 1, Working With Oracle Media Data Store Files for the following information:

• The MDS_CWD Environment Variable
• Files and Filenaming in this Guide
• System-Wide Options

Rate Control

Rate control is the ability to play video at different speeds and in different directions, to seek in either direction, to scan in either direction, or to pause and resume playback of video files.

Note

Currently, the Oracle Video Server does not allow the prohibition of any rate control operations, except pause, scan forward, and scan backward, even if these prohibitions have been specified.

vsmpegchk

This utility verifies the integrity of a content file wrapped in a MPEG2 transport wrap, and returns a message indicating whether the file is valid or corrupted.

Note

This utilitiy is not used in a corporate LAN environment.

Syntax

vsmpegchk [-s] filename [filename ...]

where:

-s

shows the type and quantity of each packet type in the file.

filename

is a file to be verified. You may specify multiple files.

Usage Notes

This utility is used only with content wrapped in MPEG 2 transport. Verify that you are using MPEG 2 encoded content prior to using vsmpegchk.

Example

This example verifies the integrity of the files goodmen.mpg2 and ghost.mpg2 in the volume movies:

% vsmpegchk /mds/movies/goodmen.mpg2 /mds/movies/ghost.mpg2
goodmen.mpg2: ok

ghost.mpg2: error at position 188: 23 45 31

This returned message shows that:

• goodmen.mpg2 is valid
• ghost.mpg2 has invalid MPEG2 data at address 188 and the data there is 23, 45, and 31.

vstag

This utility generates a tag file for a video content file. You must create a tag file for all corresponding video content files for the server to play them.

Note

vstag requires that the full MDS path of the output file be explicitly stated, or that the MDS_CWD environment variable be set to the appropriate MDS volume.

Syntax

vstag [-a] [-p integer ] [ -e integer ] [ -f {i|n} ]

[ -s integer ] [ -d description ]

[ -D {p | s | k | K | n | N | f | F} ] [ -E output-file-extension ]

[ -n slave specification][ -r integer ] [ -S service-name ] [ files ... ]

The files argument is interpreted in one of these ways:

vstag [options] input-filename output-filename

vstag -E extension [options] input-filename1 [input-filename2 ...]

where:

input-filename

specifies the content file(s) to be tagged. These files must be one of the following formats:

• MPEG 1 system stream
• MPEG 1 elementary streams wrapped in MPEG 2 transport

output-filename

specifies the output tag file name when the -E option is not used. (Refer to the -E option to see how output filenames are formed in that case.)

-a

appends the generated tag information as a new member to the existing output tag file specified by the output file. Use -a only if you are using multi-stream rate control.

Note

The -a option is not currently supported.

-d

writes a descriptive comment into the tag file. You can read this comment later with the vstagprint utility or change it with the vstagpatch utility. If you are tagging a group of files, vstag writes this comment into every tag file.

-D

generates a tag file that does not allow the specified rate control operations. Rate control is the ability to play video at different speeds and in different directions, to seek in either direction, to scan in either direction, or to pause and resume playback of the video file. The rate control operations are:

p

pause video.

s

stop video.

k

seek forward (blind fast forward).

K

seek backward (blind reverse).

n

scan forward (visual fast forward).

N

scan backward (visual reverse).

f

play forward a frame at a time.

F

play backward a frame at a time.

When specifying the above options, list the options as a string after the -D as shown below. This example prevents a client from moving backward in a file.

% vstag -D NKF /mds/video/spleen.mpg /mds/video/spleen.mpi

Note

Currently, the Oracle Video Server does not allow the prohibition of any rate control operations, except pause, scan forward, and scan backward, even if these prohibitions have been specified.

-e

specifies the decimal byte position of the input file at which to stop tagging. If you omit -e, vstag stops at the end of the file.

-E

specifies an extension for a group of output tag files. Do not specify the period (.) as part of the extension. For example, if you used:

% vstag -E mpi /mds/mpg/rutabaga.mpg

the resulting tag file would be stored in /mds/mpg/rutabaga.mpi.

-f

tells vstag the types of frames to find and tag.

i

tags MPEG I-frames. You should use this flag whenever you generate a tag file unless you are generating a null tag file. This is the default parameter.

n

generates a null, or empty, tag file. You may wish to generate a null tag file if you do not have the time to generate an actual tag file.

Note

Do not use rate control with a null tag file.

-n

runs parallel tagging processes in the configuration specified. This is implementation specific. Generally, this applies to MPP server systems. To use parallel tagging you must set the environment variable OMS_BIN to the path of vstag.

Note

Do not use -n to specify parallel tagging in a corporate LAN environment.

-p

runs parallel tagging proceses. The number of parallel processes created is specified with the integer argument of the option. Each process tags a part of the input file. To use parallel tagging you must set the environment variable OMS_BIN to the path of vstag.

If you omit both -p and -n, vstag runs in only one process.

If you use specify -p 0, vstag allocates an optimum number of processes, usually one per processor.

This example runs four parallel taggers, and tags all of the files in the volume movies that have the file extension .mpg into corresponding .mpi files.

% setenv OMS_BIN $ORACLE_HOME/bin
	
% vstag -p 4 -E mpi "/mds/movies/*.mpg"

	

-r

specifies the presentation rate at which the input file is encoded. Regular forward is represented by 1000, regular reverse by -1000, double speed forward by 2000, half speed forward by 500, etc. The default is 1000 and the minimums are 2 and -2. Only use -r if you are generating a tag file member for multi-stream rate control.

Note

Do not use the -r option unless so directed by Oracle.

-s

specifies the decimal byte position of the input file at which to begin tagging. If you omit -s, vstag starts at the beginning of the file.

-S

specifies a prefix for the names with which the tagger slaves processes register with the Oracle Media Net name server. The default is "Tag".

Examples

Example 1

This example generates a tag file for each of the specified MPEG files:

% vstag -E mpi /mds/movies/oracle1.mpg /mds/movies/oracle2.mpg

Example 2

This example tags all of the files in the volume movies that have the file extension .mpg into corresponding .mpi files.

% vstag -E mpi "/mds/movies/*.mpg"

Example 3

This example takes the input file fugitive.mpg and produces the output tag file fugitive.mpi without the ability to scan forward:

% vstag -D k -d "The Fugitive-no seeking" /mds/sample/fugitive.mpg \

/mds/sample/fast_fugitive.mpi

Example 4

This example produces a tag file using the -d option, which writes "The Fugitive" in the comment field. You can use the comment files to identify or record special information about a content file:

% vstag -d "The Fugitive" /mds/sample/fugitive.mpg \

/mds/sample/fugitive.mpi

vstagpatch

The vstagpatch utility is used to fill in information in the tag file in case the vstag utility, for whatever reason, skipped some of the detail.

vstagpatch can be used to change the following tag file properties:

• its associated MPEG content file
• descriptive comment
• bit rate
• restricted rate control operations

Syntax

vstagpatch [-c] [-s] [-p] [ -a integer ] [ -A integer ] [ -b integer ] 

      [ -d "text" ] [ -D { 0 | p | s | k | K | n | N | f | F} ]

      [ -e integer ] [ -E integer ] [ -f compression-fmt] [ -F integer ]

      [ -l integer ] [ -L integer ] [ -m integer ]

      [ -M integer ] [ -n filename ] [ -N integer ]

      [ -r integer ] [ -t transport-fmt] 

      input-filename

where:

input-filename

is the tag file to be modified.

-b

bit rate with which the associated MPEG content file is to be played. This value is expressed in bits per second.

Note

Changing the bit rate in the tag file does not change the encoding rate of the associated MPEG file, it simply replaces incorrect bit rate information.

-c

certifies that tags are valid, but does not check against the content
file itself. If -s is specified, -c is deactivated.

-d

adds a descriptive comment to the tag file. If the tag file already contains a comment, vstagpatch overwrites it.

-D

modifies the tag file so that it does not allow the specified rate control operations:

0

(zero) turns off all rate control prohibitions.

p

pause video.

s

stop video.

k

seek forward (blind fast forward).

K

seek backward (blind reverse).

n

scan forward (visual fast forward).

N

scan backward (visual reverse).

f

play forward a frame at a time.

F

play backward a frame at a time.

Note

These rate control prohibitions, with the exception of pause, scan forward, and scan backward, are not currently supported.

-M

duration in milliseconds of the associated content file.

-n

associated MPEG content file. If you use -n, you must give the full MDS path of the content file.

-p

prints the entire tag file in the format used by the vstagprint utility.

-s

if you specify -p, vstagpatch prints the header of the tag file without the entire contents.

Caution

The following options are currently not supported-do not use them unless so directed by Oracle.

-f

compression format.

-m

specifies the member of the tag file to be modified if you are using
multi-stream rate control.

-t

transport format.

-r

presentation rate of the associated content file. Regular forward is represented by 1000, regular reverse by -1000, double speed forward by 2000, half speed forward by 500, etc.

-N

number of tags in the tag file or member.

-a

audio program identifier (PID).

-A

audio stream.

-e

video program identifier (PID).

-E

video stream.

-l

length in bytes of associated content file.

-F

first presentation time stamp.

-L

last presentation time stamp.

Usage Notes

When you play a content file, the stream service uses the tag file to play the content file appropriately. The tag file provides the content file's name (including its path), bit rate, and other information.

If you move or rename a content file, you must update the tag file with the new path and name using the vstagpatch utility with the -n option.

You can use the vstagprint utility to review the information contained in the tag file.

Note that vstagpatch modifies the input file and does not accept an output file specification. If you want to modify a tag file and give it a new name, you must explicitly copy it with mdscopy before using vstagpatch.

Examples

Example 1

In this example, quizshow.mpi is the tag file for quizshow.mpg. This example uses the mdscopy utility to copy these files from one MDS volume to another and then uses vstagpatch to associate the new tag file with the new content file:

% mdscopy /mds/newrel/quizshow.mpg /mds/redford/quizshow.mpg

% mdscopy /mds/newrel/quizshow.mpi /mds/redford/quizshow.mpi

% vstagpatch -n "/mds/redford/quizshow.mpg" /mds/redford/quizshow.mpi

Example 2

This example modifies the tag file bladrunr.mpi, adding a comment and changing the bit rate to 2.048 Mbps:

% vstagpatch -d "Blade Runner Directors Cut" -b 2048000 \

/mds/rscott/bladrunr.mpi

vstagprint

This utility displays the contents of a tag file from either an MDS file or a file on a host computer.

Syntax

vstagprint [-c] [-s] input-file

where:

input -filename

specifies the file to be printed.

-c

certifies that tags are valid, but does not check against the content
file itself. If -s is specified -c is deactivated.

-s

prints only the header of the tag file without the entire contents.

Usage Notes

The output looks this:

%  vstagprint  /mds/bvs23/tromance.mpi



Tag  file  version:  3.6

Current  code  is  version  3.6,  back-compatible  to  version  3.4  

magic=aabbccdd  (should  be  aabbccdd)

file  describes  content  for:

1  member  files:

All  rate  control  operations  are  allowed  on  this  file  

#  1.  format=MPEG  2  Transport        transport=MPEG  2  Transport        flags=1

file="/mds/bvs23/tromance.m2t"  Size  =  1367205936  

creation  time  of  content:  Apr  12  13:04:21  

bitrate=1536029  bits/second

elapsed  length=7120729  milliseconds

presentation  rate=1000

frames/sec(*  1000)=23976

5695  tags  in  tag  file.

audio  PID/stream  =  0/0  video  PID/stream  =  33/224  

width:  352,  height:  240,  pel  aspect  ratio  (*  10000):  10950  

Tags  for  member  file  #1:

          1:1,  pos=  5315,      PTS-  16262    [002f0005a20b0000000000000000]

          2:1,  pos=  231383,  PTS-  128875  [0b8b0034808d0000000a00000000]  

          3:1,  pos=  471340,  PTS-  241487  [0c14003f39930000000c00010000]  

          4:1,  pos=  711650,  PTS-  354100  [0c420055891d0000000f00010000]  

          5:1,  pos=  951971,  PTS-  466712  [0c7b00570b960000001100020000]  



[etc.]

The output header tells you:

• the tag format version of the tag file and the versions accepted by the Oracle Video Server. Different versions of the Oracle Video Server may expect different tag format versions, so after you upgrade the Oracle Video Server, this information tells whether you must regenerate your tag file. In this example, both the tag file format and the Oracle Video Server tag format are version 3.6, so you need not regenerate.
• whether the input file you specified is a valid tag file. If the magic value does not match the text following it, either the input file is not a tag file or the input file is corrupted. In this example, the magic value "aabbccdd" matches the text following, so tromance.mpi is a valid tag file.
• the video file described is an MPEG 2 system stream, therefore, the format is MPEG 2 with no transport wrap.
• the name and size of the MPEG content file to which the tag file points. In this example, the tag file is based on the content file
  /mds/bvs23/tromance.m2t which is 1,367,205,936 bytes in length.
• the bit rate of the associated MPEG content file. In this example, the bit rate of tromance.m2t is 1,536,029 bps.

Note

The flags statement can be ignored.

Each numbered line of output following the header describes a single tag point and has these fields:

Table 3-1: Tag points

integer1:integer2	tag number and the internal code for the type of the frame tagged.
pos	byte position in the MPEG content file where the tagged frame begins.
PTS or SCR	Presentation Time Stamp describing when the tagged frame appears as the video is playing.
[ ]	contains the information necessary to reposition the video to this tag point as it is playing.

Example

This example prints the header of the tag file fugitive_t1.mpi:

% vstagprint -s /mds/bvs23/fugitive_t1.mpi 



Tag file version: 3.6

Current code is version 3.6, back-compatible to version 3.4 

magic=aabbccdd (should be aabbccdd)

file describes content for:

1 member files:

All rate control operations are allowed on this file 

# 1. format=MPEG 2 Transport        transport=MPEG 2 Transport        flags=1

file="/mds/holly/fugitive_t1.m2t" Size = 1499818128 

creation time of content: Apr 9 11:13:51 

bitrate=1536029 bits/second

elapsed length=7811405 milliseconds

presentation rate=1000

frames/sec(* 1000)=23976

6245 tags in tag file.

audio PID/stream = 0/0 video PID/stream = 33/224 

width: 352, height: 240, pel aspect ratio (* 10000): 10950 

vswrap

This utility converts a binary file into a format suitable to be sent to a set-top box and generates a tag file for it.

Note

This utility is not used in a corporate LAN environment.

Syntax

vswrap [ -p { boot | blob } ] [ -t { gen | m2t | raw } ]  

[-s integer] [-n integer] [-e integer] [-b integer]

[-S integer] [-B integer] [-m integer] [-r integer]

/host/path/input-file /mds/volume/output-file /mds/volume/tag-file

where:

-p

specifies the protocol of the output file:

boot

produces an output file in boot protocol. Use this option to convert boot images.

blob

produces an output file in BLOB protocol. Use this option to convert BLOBs.

The default is boot.

-t

specifies the format of the output file:

gen

generic framing, used by certain clients.

m2t

MPEG-2 framing, used for other set-top boxes.

raw

produces an unframed output file. Do not use this option in this release.

The default is m2t.

-s

specifies how many MPEG null packets vswrap puts before the first message in the output file. The minimum is 0 and there is no maximum. The default is 3.

-n

specifies how many MPEG null packets vswrap puts between each message in the output file. The minimum and default are 0. There is no maximum.

-e

specifies how many MPEG null packets vswrap puts after the last message in the output file. The minimum and default are 0. There is no maximum.

The -s, -n, and -e switches put MPEG-2 null packets in the output file to allow the set-top box to receive the boot image or blob properly. Appropriate values for these switches vary greatly for different types of set-top boxes.

-b

specifies the size in bytes of the boot protocol or Oracle Media Net messages. The utility divides the file into messages of this size and stores them in the output file. The minimum is 1 and there is no maximum. For BLOBs the default is 7148 bytes. For boot images the default is the size of the boot image input file which means vswrap stores the entire boot image in a single message.

Note

Using the default values is highly recommended.

Use this switch only to convert boot images, not BLOBs.

-B

specifies a hexadecimal MPEG2 program identifier (PID) for the boot size messages. The default is 0x11.

-S

specifies a hexadecimal MPEG2 PID for the boot data messages. The default is 0x11.

-m

specifies a hexadecimal MPEG2 PID for the Oracle Media Net BLOB messages. The default is 0x10.

-r

specifies how many data messages appear between each size message in the output file. The default is infinite, which means there is only one size message followed by all the data messages that make up the input file.

input-file

specifies the name of the input binary file.

output-file

specifies the name of the output file to be created, suitable to be sent to a set-top box. If the output file already exists, vswrap overwrites it.

tag-file

specifies the name of the tag file for the output file. To receive a boot image or a BLOB, an application must request it by referring to its tag file, so you must create a tag file when converting a binary file to be stored in the MDS.

Although the tag, input, and output files can be either in the MDS or in the host file system, it is typical to create a tag file and output file in the MDS from an input file in the host file system.

Examples

Example 1

This example converts the boot image nomo_os9 in the host file system into the file newboot.bi in the MDS:

vswrap -p boot -t m2t -s 450 -n 450 -e 10 \

/host$OMS_HOME/omo/admin/nomo_os9 /mds/bootimages/newboot.bi \

/mds/bootimages/newboot.tag

The new file is formatted with MPEG-2 framing with 450 null packets between each boot protocol message, 450 null packets before the first boot protocol message, and 10 null packets after the last boot protocol message. This example also creates the tag file newboot.tag in the MDS volume bootimages.

Example 2

This example converts the BLOB file omsBlob1 in the host file system into the file omsBlob1 in the MDS:

vswrap -p blob -t m2t \

/host$ORACLE_HOME/bin/omsBlob1 /mds/bin/omsBlob1 \

/mds/bin/omsBlob1.tag

The new file is formatted with MPEG-2 framing with the default message size of 7148 bytes, three nulls before the first message, and no nulls between messages or after the last message. This example also creates the tag file omsBlob1.tag in the MDS volume bin.

---