FunCom ISS

• Extensions: iss
• Company: FunCom Oslo A/S
• Samples: http://samples.mplayerhq.hu/game-formats/funcom-iss/

ISS files are audio files with IMA ADPCM audio used in some games from a company named FunCom Oslo A/S, including The Longest Journey.

Credit

The information on this page was originally based on one of the many format documents written up by Valery V. Anisimovsky, available on http://wotsit.org/ and many other sites across the internet.

Byte Order

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

ISS Audio Files

The music, sfx and speech in The Longest Journey are stored in .ISS files which can either occur as standalone files or stored in XARC archives. The ISS file has some kind of a textual header -- the header fields are just decimal string representations of corresponding field values, separated by spaces. To obtain the parameters of an ISS file, a program needs to parse this textual header while being mindful of issues related to parsing freeform text (like buffer overflows).

The following fields should be present in the textual header

• ID -- ID string, which is "IMA_ADPCM_Sound".
• BlockSize -- the block size for the audio stream in the file (see below). The music (stereo) files usually set this value to 2048; the speech/sfx (mono) files usually set this value to 512. These values may vary, though.
• FileID -- the string ID of the given file. It seems to be the internal name for the file (which usually matches the file title for standalone files).
• OutSize -- total number of audio samples in the file. May be used for song length (in seconds) calculation. (audio samples or audio frames? --Multimedia Mike 20:53, 2 April 2008 (EDT))
• Stereo -- this seems to be boolean stereo flag: if this is non-zero, the audio stream in the file is stereo (music), otherwise it's mono (sfx, speech).
• Unknown1 -- the unknown field. All ISS files in The Longest Journey have this field set to 1.
• RateDivisor -- the value which determines sample rate for the file: the sample rate is equal to (44100 / RateDivisor). E.g., a RateDivisor of 2 indicates that the audio data should be played back at 22050 Hz.
• Unknown2 -- the unknown field. All ISS files in The Longest Journey have this value set to 0.
• Version -- version ID string. All files in The Longest Journey have this set to "1.000". Note that this field may, in principle, vary.
• Size -- the size of the audio stream in the file. The total filesize is the sum of the header size plus this value.

ISS IMA ADPCM

After the header, the ISS file contains IMA ADPCM-compressed sound data. The stream is divided into the blocks of BlockSize bytes. Each block in a mono stream begins with a header that contains the initial values for IMA ADPCM decompression:

 UI16:  initial sample
 UI16:  initial index

In a stereo stream, each chunk begins with such headers, one for the left channel and one for the right:

 UI16:  left channel initial sample
 UI16:  left channel initial index
 UI16:  right channel initial sample
 UI16:  right channel initial index

During the decompression four LONG variables must be maintained for stereo stream: lIndexLeft, lIndexRight, lCurSampleLeft, lCurSampleRight and two -- for mono stream: lIndex, lCurSample. At the beginning of each block you must initialize lCurSampleLeft/Right and lIndexLeft/Right variables to the values from ISSBlockHeader. Note that both LONG and SHORT here are signed (so initialize LONG variables by the SHORT initial values with sign extention).

Here's the code which decompresses one byte of IMA ADPCM compressed stereo stream. Other bytes are processed in the same way.

BYTE Input; // current byte of compressed data
BYTE Code;
LONG Delta;

Code=HINIBBLE(Input); // get HIGHER 4-bit nibble

Delta=StepTable[lIndexLeft]>>3;
if (Code & 4)
  Delta+=StepTable[lIndexLeft];
if (Code & 2)
  Delta+=StepTable[lIndexLeft]>>1;
if (Code & 1)
  Delta+=StepTable[lIndexLeft]>>2;
if (Code & 8) // sign bit
  lCurSampleLeft-=Delta;
else
  lCurSampleLeft+=Delta;

// clip sample
if (lCurSampleLeft>32767)
  lCurSampleLeft=32767;
else if (lCurSampleLeft<-32768)
  lCurSampleLeft=-32768;

lIndexLeft+=IndexAdjust[Code]; // adjust index

// clip index
if (lIndexLeft<0)
  lIndexLeft=0;
else if (lIndexLeft>88)
  lIndexLeft=88;

Code=LONIBBLE(Input); // get LOWER 4-bit nibble

Delta=StepTable[lIndexRight]>>3;
if (Code & 4)
  Delta+=StepTable[lIndexRight];
if (Code & 2)
  Delta+=StepTable[lIndexRight]>>1;
if (Code & 1)
  Delta+=StepTable[lIndexRight]>>2;
if (Code & 8) // sign bit
  lCurSampleRight-=Delta;
else
  lCurSampleRight+=Delta;

// clip sample
if (lCurSampleRight>32767)
  lCurSampleRight=32767;
else if (lCurSampleRight<-32768)
  lCurSampleRight=-32768;

lIndexRight+=IndexAdjust[Code]; // adjust index

// clip index
if (lIndexRight<0)
  lIndexRight=0;
else if (lIndexRight>88)
  lIndexRight=88;

// Now we've got lCurSampleLeft and lCurSampleRight which form one stereo
// sample and all is set for the next input byte...
Output((SHORT)lCurSampleLeft,(SHORT)lCurSampleRight); // send the sample to output

HINIBBLE and LONIBBLE are higher and lower 4-bit nibbles:

#define HINIBBLE(byte) ((byte) >> 4)
#define LONIBBLE(byte) ((byte) & 0x0F)

Note that depending on your compiler you may need to use additional nibble separation in these defines, e.g. (((byte) >> 4) & 0x0F).

StepTable and IndexAdjust are the tables given in the next section of this document.

Output() is just a placeholder for any action you would like to perform for decompressed sample value.

Of course, this decompression routine may be greatly optimized.

As to mono sound, it's just analoguous:

Code=LONIBBLE(Input); // get LOWER 4-bit nibble

Delta=StepTable[lIndex]>>3;
if (Code & 4)
  Delta+=StepTable[lIndex];
if (Code & 2)
  Delta+=StepTable[lIndex]>>1;
if (Code & 1)
  Delta+=StepTable[lIndex]>>2;
if (Code & 8) // sign bit
  lCurSample-=Delta;
else
  lCurSample+=Delta;

// clip sample
if (lCurSample>32767)
  lCurSample=32767;
else if (lCurSample<-32768)
  lCurSample=-32768;

lIndex+=IndexAdjust[Code]; // adjust index

// clip index
if (lIndex<0)
  lIndex=0;
else if (lIndex>88)
  lIndex=88;

Output((SHORT)lCurSample); // send the sample to output

Code=HINIBBLE(Input); // get HIGHER 4-bit nibble
// ...just the same as above for higher nibble

Note that LOWER nibble is processed first for mono sound while for stereo sound HIGHER nibble corresponds to LEFT channel.

IMA ADPCM Tables

LONG IndexAdjust[]=
{
   -1,
   -1,
   -1,
   -1,
    2,
    4,
    6,
    8,
   -1,
   -1,
   -1,
   -1,
    2,
    4,
    6,
    8
};

LONG StepTable[]=
{
   7,	   8,	  9,	 10,	11,    12,     13,    14,    16,
   17,    19,	  21,	 23,	25,    28,     31,    34,    37,
   41,    45,	  50,	 55,	60,    66,     73,    80,    88,
   97,    107,   118,	 130,	143,   157,    173,   190,   209,
   230,   253,   279,	 307,	337,   371,    408,   449,   494,
   544,   598,   658,	 724,	796,   876,    963,   1060,  1166,
   1282,  1411,  1552,  1707,	1878,  2066,   2272,  2499,  2749,
   3024,  3327,  3660,  4026,	4428,  4871,   5358,  5894,  6484,
   7132,  7845,  8630,  9493,	10442, 11487,  12635, 13899, 15289,
   16818, 18500, 20350, 22385, 24623, 27086,  29794, 32767
};

ISS Audio Files in XARC Archives

When stored in .XARC resources, ISS audio files are stored "as is", without compression or encryption. That means if you want to play/extract ISS file from the XARC resource you just need to search for (szID) id-string ("IMA_ADPCM_Sound") and read ISS header starting at the beginning position of found id-string. This will give you starting point of the file and the size of the file will be the sum of header size (its size may vary!) and (dwSize).

PC Games Using FunCom ISS

The Longest Journey