VMD

From MultimediaWiki
Jump to navigation Jump to search
This page is about the VMD format used in Sierra computer games. See the Internet Wave page for information about a web reference format with the extension VMD.

This page is based on the document 'Description of the Sierra Video and Music Data (VMD) Format' by Mike Melanson and Vladimir "VAG" Gneushev at http://multimedia.cx/vmd-format.txt.

VMD is the file extension of a multimedia file format used in a number of Sierra CD-ROM computer games. The extension stands for Video and Music Data. The format is most notable for its use in Sierra's beloved 7-CD classic, Phantasmagoria, and is also used in other multimedia-heavy Sierra titles. Newer revisions were also used in Coktail Vision's ADI/Addy series of edutainment games.

File Format

All multi-byte numbers are stored in little-endian format.

A VMD file starts with the following 816- (0x330-)byte header:

 bytes 0-1      length of header, not including this length field; this
                length should be 0x32E (814)
 bytes 2-3      placeholder for VMD handle and some kind of VMD version
 bytes 4-5      VMD video codec version
 bytes 6-7      number of blocks in table of contents
 bytes 8-9      top corner coordinate of video frame
 bytes 10-11    left corner coordinate of video frame
 bytes 12-13    width of video frame
 bytes 14-15    height of video frame
 bytes 16-17    flags
 bytes 18-19    frames per block
 bytes 20-23    absolute file offset of multimedia data
 bytes 24-27    unknown (Urban Runner samples contain "iv32" there)
 bytes 28-795   256 RGB palette entries, 3 bytes/entry in R-G-B order
 bytes 796-799  recommended size (bytes) of data frame load buffer
 bytes 800-803  recommended size (bytes) of unpack buffer for video decoding
 bytes 804-805  audio sample rate
 bytes 806-807  audio frame length/sample resolution
 bytes 808-809  number of sound buffers
 bytes 810-811  audio flags
 bytes 812-815  absolute file offset of table of contents

Note that the RGB color components are 6-bit VGA palette components which means that they range from 0..63. The components need to be scaled if they are to be used in rendering typical RGB images where the components are 8 bits.

The newer VMD version may have additional two fields in the header:

 bytes 816-817  external audio codec ID
 bytes 818-819  audio codec frame size in samples

Even newer VMD version removes palette from the header thus shrinking down header size to 52 (or 0x34) bytes. The order of the other fields remains the same.

A VMD file has a table of contents describing all of the file's block and frame information. The absolute file offset of the table of contents is given in the file header and usually points to the end of the file. The table of contents contains 2 parts: The block offset table and the frame information table. Blocks and frames in VMD are different concepts. A frame contains audio or video. A block contains both a video frame and an audio frame. The block offset table consists of a series of 6-byte records. Each record has the following format:

 bytes 0-1      unknown
 bytes 2-5      absolute file offset of block

The number of entries in this table is specified by bytes 6-7 in the file header. After the block offset table is the frame information table. The frame information table consists of a series of 16-byte records with the following format:

 byte 0         frame data type
   1 = audio frame
   2 = video frame
 byte 1         unknown
 bytes 2-5      frame data length
 The meaning of the frame's remaining data depends on the frame type.
 if this is an audio frame:
   byte 6       audio flags (100 or 0x64 in case of external audio codec)
   bytes 7-15   unknown (in case of external audio codec bytes 7-10 are frame data length repeated again)
 if this is a video frame:
   bytes 6-7    left coordinate of video frame
   bytes 8-9    top coordinate of video frame
   bytes 10-11  right coordinate of video frame
   bytes 12-13  bottom coordinate of video frame
   byte 14      unknown
   byte 15      bit 1 (byte[15] & 0x02) indicates a new palette

Generally, a frame information record needs to be made available to the audio or video decoder units of a VMD decoding application as the information is relevant to the decoding process.

Video Format

The VMD video coding method uses the Lempel-Ziv (LZ77) algorithm, run length encoding (RLE), and interframe differencing to compress 8-bit data which can be either paletted, 16-bit RGB or 24-bit RGB. Known flavours (bytes 4-5 of the header) are:

  • 1 - old paletted frame
  • 5 - 24-bit video
  • 7 - compressed with Indeo 3
  • 13 - 16-bit video

VMD video embodies both intraframes (a.k.a. keyframes) and interframes. Intraframes update the entire frame. Interframes only update portions of the frame that have changed from the previous frame. The first video frame of a VMD file is implicitly intracoded (the first frame has to paint the entire viewing area). The successive frames are all intercoded.

The frame record for a video frame specifies the frame coordinates of the rectangular region that will be updated. For example, if the file header specifies that the video is 200 pixels wide and 100 pixels high, the left, top, right, and bottom coordinates of the rectangular update region will be 0, 0, 199, and 99, respectively, if the entire frame is to be updated. A subsequent interframe may choose to leave much of the previous frame unchanged and only update the block from (100, 10) -> (150, 40). In this case, the coordinates 100, 10, 150, and 40 would be encoded in the frame record. Depending on VMD version (bytes 2-3 of the header) frame offsets and dimensions may be stored either as bytes (versions 0-1) or as pixels (version 2).

The initial palette for decoding VMD video is transported in the main VMD file header. If bit 1 of frame record byte 15 (byte[15] & 0x02) is set to 1, the compressed video data chunk begins with a new palette. The palette data is transported as 770 bytes. The first byte contains the first palette index to modify. The second byte contains the number of palette entries to change. The remaining 768 bytes are 256 R-G-B palette triplets. Again, these are stored as 6-bit VGA DAC values and should be scaled accordingly.

The compressed video data begins with a byte describing how the data is encoded. The byte specifies the following information:

 bit 7      specifies that data chunk is LZ compressed
 bits 6-0   specifies 1 of 3 rendering methods

If bit 7 is 1, the data chunk must be passed through the LZ decoder before progressing to the rendering phase. If bit 7 is 0, the data chunk is passed directly to the rendering phase.

The VMD LZ decoding algorithm takes the compressed video buffer (after the coding method byte described above) as input and outputs a buffer of decoded bytes. The output buffer must be as large as indicated in bytes 800-803 of the main VMD header. The VMD LZ decoding algorithm operates as follows:

 allocate a circular queue of 4096 (0x1000) bytes and initialize all
   elements to 0x20; note that the queue is addressed with a 12-bit
   number
 initialize variable dataleft as the first 4 numbers in the block
 if the next 4 bytes are (0x34 0x12 0x78 0x56)
   advance stream over the 4 marker bytes
   initialize queue position (qpos) to 0x111
   initialize special chain length (speclen) to 18
 else
   initialize qpos to 0xFEE
   initialize speclen to nothing (any value above 18 will suffice in
     this example)
 proceed to main decode loop...
 while there is more data left (dataleft > 0)
   tag = the next byte in the stream
   if (tag is 0xFF) and (dataleft > 8)
     take the next 8 bytes from the stream and place them in both the
       output buffer and the circular queue
     subtract 8 from dataleft
   else
     foreach bit in tag byte, reading from right -> left
       if (bit is 1)
         take the next byte from the stream and place it in both the
           output buffer and the circular queue
         decrement dataleft
       else
         move a chain of bytes from the circular queue to the output
         get the length and beginning offset of the chain from the next
           2 bytes in the stream:
           byte 0: bits 7-0: lower 8 bits of beginning offset
           byte 1: bits 7-4: upper 4 bits of beginning offset
                   bits 3-0: length of chain, minus 3
         thus, add 3 to the length to obtain the actual length
         if (length is equal to speclen)
           length is 18 (max ordinary speclen value) + next byte in
             stream
           copy the byte chain from the circular queue to the output;
             in the process, add the chain back into the queue
           subtract length from dataleft

There are 3 rendering methods that a frame can use to paint the raw or LZ-decoded data (referred to as the video data buffer) onto the final output frame.

Method 1 iterates through each line in the output frame, as indicated by the dimensions specified in the frame information record. For each line:

 offset = 0
 repeat
   length = next byte in video data buffer
   if (bit 7 of length byte is 1)
     mask off bit 7 of length and add 1 (length = (length & 0x7F) + 1)
     copy length bytes from the video data buffer to the output frame
     advance offset by length
   else
     increment length
     copy length bytes from the same position in the previous frame to
       the current frame
 while (offset < frame width)

Method 2 simply copies the entire video data buffer onto the output frame. This is the simplest rendering method, but be sure to take into account the frame's specific decoding dimensions as specified in the frame record.

Method 3 operates just like method 1 except for one small change. When bit 7 of the length byte is 1 and the length byte has been masked and incremented, the next byte in the video data buffer is examined. If the byte is not 0xFF, perform the same copy as in method 1. If the byte is 0xFF, apply a RLE decoding algorithm to unpack the data from the video data buffer into the output frame. The RLE unpacking algorithm operates as follows:

 if the length is odd, copy the next byte from the video data buffer to
   the output frame and decrement length
 divide length by 2
 while (length > 0)
   fetch the next byte from the video data buffer
   if the top bit of the byte is 1 (byte & 0x80)
     drop the top bit of the byte and shift left by 1:
       byte = (byte & 0x7F) << 1
     copy (byte) bytes from video data buffer to output frame
   else
     foreach count in byte
       copy the next 2 bytes from video data buffer to output frame; in
         other words, bytes A and B from the video data buffer will be
         repeated n times: ABABABAB...

Audio Format

8-bits audio stored as a raw PCM samples, all 16-bits sound are 2:1 DPCM-encoded. First, you need to ensure VMD contains any sound by checking bit 12 (& 0x1000) of the file header' flags. Non-zero bit indicates file has sound. Fields audio_sample_rate and audio_frame_length contains playback rate and size of single (compressed) sound block respectively. Negative audio frame length used to indicate 16-bits sound data, in this case you need to invert this field to get the actual block length. Audio flags field keeps other important flags: bit 15 (& 0x8000) indicates old-style stereo-sound, while bit 9 (& 0x200) - new stereo sound format (introduced in Shivers 2 game). These formats a little different in the meaning of several fields (one format stores just deltas and another one stores initial sample values in the beginning of every block), making original playback core is not backward compatible - Shivers 2 can not play old videos properly. Optimal way is check bit 15 first and if it's zero, additionally check bit 9 to determinate number of channels. The main difference between old and new formats - old vmds treat audio frame length field as the number of samples for both channels, but new version - only as number of samples for single channel (i.e. you need to multiply it by 2 for stereo sound). There is also IMA ADPCM compression signalled by bit 4 (& 0x10) with block data in the following format: 16-bit initial samples for one or two channels, 8-bit step indices and the rest is ADPCM data decoded high nibble first. In case of new VMD format with an external audio codec payloads are decoded with some codec from Lernout&Hauspie StreamTalk family:

  • type 3 --- 15 kbps @ 8kHz
  • type 4 --- 50 kbps @ 22kHz
  • type 5 --- 25 kbps @ 11kHz
  • type 6 --- CELP codec 4.8 kbps @ 8kHz

Most of these codecs are variable bitrate audio codecs based on MPEG Audio Layer II but without a header and with fixed bit allocation class.

When you encounter frame information record of type 1, proceed to audio decoding. First, analyse frame's audio_flags byte. It may be eiter:

  • 1 - normal sound block

Decompress single audio block and continue to next frame

  • 2 - multiple sound and silence blocks

Get next 4 bytes of the frame's data. This is a sound mask bits. Starting from bit 0, each non-zero bit indicates silence block. Zero means normal audio block. Thus, iterate number_of_sound_buffer times to fill chain of sound and/or silence blocks.

  • 3 - single silence block

Fill whole block with silence.

The decompression scheme is quite trivial. As stated above, it has been used only if file contains 16-bits audio. First, you need to get one or two (depends on number of the channels) initial samples. For mono and new-stereo sound each initial sample is the first word(s) of audio stream data. Old-style stereo sound has no static samples, instead, they are initialized to zero at the beginning of the playback and carried between successive frames. This may cause some difficulties with random seeking over such kind of files. Using these samples, perform decoding of the rest of chunk' bytes using this formula:

if code & 0x80  sample = sample - Table[code & 0x7F]
else            sample = sample + Table[code & 0x7F]

Where code is the bytes of packed data. Interleave left-right samples decoding for stereo sound.

The delta table is:

   0,    8,   16,   32,   48,   64,   80,   96,  112,  128,  144,  160,  176,  192,  208,  224
 240,  256,  272,  288,  304,  320,  336,  352,  368,  384,  400,  416,  432,  448,  464,  480
 496,  512,  520,  528,  536,  544,  552,  560,  568,  576,  584,  592,  600,  608,  616,  624
 632,  640,  648,  656,  664,  672,  680,  688,  696,  704,  712,  720,  728,  736,  744,  752
 760,  768,  776,  784,  792,  800,  808,  816,  824,  832,  840,  848,  856,  864,  872,  880
 888,  896,  904,  912,  920,  928,  936,  944,  952,  960,  968,  976,  984,  992, 1000, 1008
1016, 1024, 1088, 1152, 1216, 1280, 1344, 1408, 1472, 1536, 1600, 1664, 1728, 1792, 1856, 1920
1984, 2048, 2304, 2560, 2816, 3072, 3328, 3584, 3840, 4096, 5120, 6144, 7168, 8192,12288,16384

Games Using VMD

These are some of the Sierra computer games that are known to use the VMD file format: