Smush

From MultimediaWiki
Revision as of 19:06, 28 March 2006 by Cyril (talk | contribs)
Jump to navigation Jump to search

This page attempts to document the LucasArts Smush codec, FOURCC "SANM". Note that at this stage the document is quite incomplete as the codec is still being reversed. Most information regarding codecs here is speculative, at best. Structural information is quite correct unless otherwise noted.

Samples

Samples from various games are located at http://www.mplayerhq.hu/MPlayer/samples/game-formats/la-san/. Keep in mind that these files may not all be encoded with the same version of Smush. We hope to describe the codec's usage in each game as we find out more information.

Use in Grim Fandango

SANM is used in Grim Fandango for cut-scenes and in-game animations. The actual SNM movie files are stored inside LAB archive files (which are quite easy to extract, there are many tools) and gzippe'd. You must use a tool like *nix's "gunzip" to decompress the SNM files after extracting the SNM files out of the LAB files. A decompressed Smush file has the "SANM" FOURCC as the first four bytes.

Organization

This section deals with the structural properties of Smush movies. In other words, we describe the various headers used.

Preamble

The movie begins with a basic 8-byte section that looks like this:

0x00|"SANM" FOURCC        |4 bytes big endian
0x04|Movie size (in bytes)|4 bytes big endian

Video Header

This header immediately follows the preamble. It describes the movie's video properties.

0x000|"SHDR" FOURCC             |4 bytes big endian
0x004|Header size (in bytes)    |4 bytes big endian
0x008|Version                   |2 bytes little endian
0x00A|# of frames               |4 bytes little endian
0x00E|Padding?                  |2 bytes
0x010|Width                     |2 bytes little endian
0x012|Height                    |2 bytes little endian
0x014|Padding?                  |2 bytes
0x016|Frame delay (microseconds)|4 bytes little endian
0x01A|Color palette?            |1024 bytes
0x41A|Padding?                  |16 bytes

Audio/Keyframe Header

Smush supports variable-size keyframes. An example of this usage can be seen in the Full Throttle highway chase scenes, where different images are composited into the streaming video depending on the player's actions.

Curiously enough, this header includes both audio and keyframe information.

0x00|"FLHD" FOURCC         |4 bytes big endian
0x04|Header size (in bytes)|4 bytes big endian

Followed by any number of keyframe dimension chunks, which should match the number of keyframes in the movie. Dimension chunks in this header specify the dimensions of corresponding keyframes in the stream, in the order they're encountered. This information has not been rigorously verified, though.

0x00|"Bl16" FOURCC         |4 bytes big endian
0x04|Header size (in bytes)|4 bytes big endian
0x08|Padding?              |2 bytes
0x0A|Width                 |2 bytes little endian
0x0C|Height                |2 bytes little endian
0x0E|Padding?              |2 bytes

Followed by exactly one audio info chunk.

0x00|"Wave" FOURCC         |4 bytes big endian
0x04|Header size (in bytes)|4 bytes big endian
0x08|Frequency (Hz)        |4 bytes little endian
0x0C|# of channels         |4 bytes little endian
0x10|See notes             |4 bytes

Notes

  • For some movies, the "Wave" chunk contains an extra 4-byte field at its end, the purpose of which is unknown.
  • Movies without audio do not contain an audio info chunk.
  • The order in which Wave/Bl16 chunks are organized in the FLHD header is unspecified and is known to vary between movies.

Annotation

Movies may contain an optional plaintext annotation. In Grim Fandango, the only such movies are in-game animations. Keep in mind that the string itself may not always be as large as the advertised annotation size. In that case, the remaining space is padded with zeros until the advertised length is reached.

0x00|"ANNO" FOURCC             |4 bytes big endian
0x04|Annotation size (in bytes)|4 bytes big endian
0x08|Null-terminated string    |(Annotation size) bytes

Frame

This header is used as a container for a video frame and/or an audio frame, stored in an arbitrary order. In itself, it's just a FOURCC and a size.

0x00|"FRME" FOURCC        |4 bytes big endian
0x04|Chunk size (in bytes)|4 bytes big endian

Audio

Please see the appropriate section in VIMA for an audio frame's header/codec details. Note that as far as we know right now, this codec is specific to Grim Fandango Smush files.

Video

This chunk stores a potentially encoded video frame, as well as various opcodes and other stuff that's used to decode it. More details downstairs.

0x000|"Bl16" FOURCC            |4 bytes big endian
0x004|Chunk size (in bytes)    |4 bytes big endian
0x008|Unknown                  |8 bytes
0x010|Width                    |4 bytes little endian
0x014|Height                   |4 bytes little endian
0x018|Sequence #               |2 bytes little endian
0x01A|Subcodec ID              |1 byte
0x01B|Diff buffer rotate code  |1 byte
0x020|See notes                |8 bytes
0x028|Background colour        |2 bytes little endian
0x02C|Bomp data size?, in bytes|4 bytes little endian
0x030|Codebook?                |Each entry is 2 bytes little endian?
0x238|Encoded data start       |...
Notes
  • The field at 0x020 is only mentioned because there's evidence of the original decoder reading it.

(More coming soon, as soon as I dig the info out of my notes.)