FunCom ISS - Revision history

StefanG: Not missing in FFmpeg anymore

2009-01-21T10:06:35Z

Not missing in FFmpeg anymore

← Older revision		Revision as of 03:06, 21 January 2009
Line 61:		Line 61:
	[[Category:IMA ADPCM Audio Codecs]]		[[Category:IMA ADPCM Audio Codecs]]
	[[Category:Game Formats]]		[[Category:Game Formats]]
	~~[[Category:Formats missing in FFmpeg]]~~

Multimedia Mike: IMA ADPCM tables don't need to be here; don't need special "games using..." section if there is only one known game; add to IMA ADPCM category; more general edits

2008-04-03T01:01:21Z

IMA ADPCM tables don't need to be here; don't need special "games using..." section if there is only one known game; add to IMA ADPCM category; more general edits

@@ Line 11: / Line 11: @@
 All multi-byte numbers are stored in little endian format.
-== ISS Audio Files ==
+== ISS File Format ==
 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).
@@ Line 51: / Line 51: @@
      byte0 byte1 byte2 byte3 ...
      L0 R0 L1 R1 L2 R2 L3 R3 ...
 == ISS Audio Files in XARC Archives ==
-When stored in .XARC resources, ISS audio files are stored "as is", without
+When stored in .XARC resources, ISS audio files are stored "as is", without compression or encryption. That means if you want to play/extract an ISS file from the XARC resource you just need to search for ''ID'' id-string ("IMA_ADPCM_Sound") and read the ISS header starting at the beginning position of the ID string. This will give you starting point of the file and the size
-compression or encryption. That means if you want to play/extract ISS
+of the file will be the sum of header size (its size may vary) and ''dwSize''.
 [[Category:Audio Codecs]]
 [[Category:ADPCM Audio Codecs]]
 [[Category:Game Formats]]
 [[Category:Formats missing in FFmpeg]]

Multimedia Mike: /* ISS IMA ADPCM */ explain what is unique about this IMA encoding method and remove the entire algorithm description, linking to the internal wiki description instead

2008-04-03T00:58:19Z

ISS IMA ADPCM: explain what is unique about this IMA encoding method and remove the entire algorithm description, linking to the internal wiki description instead

Show changes

Multimedia Mike: general edits; removed parsing pseudocode; removed all type warts

2008-04-03T00:53:42Z

general edits; removed parsing pseudocode; removed all type warts

@@ Line 1: / Line 1: @@
-* Extensions: .ISS, .XARC
+* Extensions: iss
-* Company: Funcom Oslo A/S
+* Company: FunCom Oslo A/S
 * Samples: http://samples.mplayerhq.hu/game-formats/funcom-iss/
 == Credit ==
@@ Line 8: / Line 9: @@
 == Byte Order ==
-All numbers are stored in little endian format.
+All multi-byte numbers are stored in little endian format.
 == ISS Audio Files ==
-The music, sfx and speech in The Longest Journey are .ISS files, either
+The following fields should be present in the textual header
-''szVersion'' -- version ID string, all files in The Longest Journey have this
+* ''ID'' -- ID string, which is "IMA_ADPCM_Sound".
-set to "1.000". Note that this field may, in principle, vary.
+* ''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.
-''dwSize'' -- the size of the audio stream in the file. The total filesize is
+== ISS IMA ADPCM ==
-The resolution is NOT specified in the header, so the default value (16-bit)
+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:
-After the ISSHeader IMA ADPCM compressed sound data comes. The stream is
+  UI16:  initial sample
-devided into the blocks each being (''dwBlockSize'') long. Each block begins
+  UI16:  initial index
- struct ISSBlockHeader
+In a stereo stream, each chunk begins with such headers, one for the left channel and one for the right:
-For mono audio stream there's only one such header, while for stereo stream
+  UI16:  left channel initial sample
-there're two consecutive headers -- for left and right channels. Right after
+  UI16:  left channel initial index
-the block header (or two of them for stereo stream) comes IMA ADPCM compressed
+  UI16:  right channel initial sample
-audio data. You may find IMA ADPCM decompression scheme description further
+  UI16:  right channel initial index
 During the decompression four LONG variables must be maintained for stereo

Multimedia Mike: link to samples

2008-04-02T22:25:20Z

link to samples

← Older revision		Revision as of 15:25, 2 April 2008
Line 1:		Line 1:
	*Extensions: .ISS, .XARC		* Extensions: .ISS, .XARC
	*Company: [[Funcom Oslo A/S]]		* Company: Funcom Oslo A/S
			* Samples: http://samples.mplayerhq.hu/game-formats/funcom-iss/

DonDiego: Add to formats missing in FFmpeg category.

2007-04-13T21:19:10Z

Add to formats missing in FFmpeg category.

← Older revision		Revision as of 14:19, 13 April 2007
Line 1:		Line 1:
	*Extensions: .ISS, .XARC		*Extensions: .ISS, .XARC
	*Company:[[Funcom Oslo A/S]]		*Company: [[Funcom Oslo A/S]]


Line 272:		Line 272:
	[[Category:ADPCM Audio Codecs]]		[[Category:ADPCM Audio Codecs]]
	[[Category:Game Formats]]		[[Category:Game Formats]]
			[[Category:Formats missing in FFmpeg]]

Dashcloud: Adding Funcom ISS format

2006-08-16T15:32:16Z

Adding Funcom ISS format

New page

*Extensions: .ISS, .XARC
*Company:[[Funcom Oslo A/S]]

== 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 numbers are stored in little endian format.
== ISS Audio Files ==

The music, sfx and speech in The Longest Journey are .ISS files, either
stand-alone or stored in XARC archives.
The ISS file has some kind of a textual header -- the header fields are just
decimal string representations of correspondent fields values, separated
by spaces. So, to get the parameters of an ISS file, you should parse its
textual header, using the function like this one:

// read the file (f) into string (szValue) until the space character is
// encountered (taking into account the string size (dwSize) and EOF)
void ReadUntilSpace(FILE* f, char *szValue, DWORD dwSize)
{
char ch;
DWORD i=0;

while ((!feof(f)) && (i<dwSize-1))
{
fread(&ch,1,1,f);
if (ch==' ') // space character (0x20)
break;
szValue[i++]=ch;
}

szValue[i]=0;
}

Of course, it's not the most optimal means to parse ISS header. Anyway,
once you've got the way to obtain the textual fields of ISS header, you'll
see the following structure of that header (all numbers are decimal!):
''szID'' ''dwBlockSize'' ''szFileID'' ''dwOutSize'' ''dwStereo'' ''dwUnknown1''
''dwRateDevider'' ''dwUnknown2'' ''szVersion'' ''dwSize''

''szID'' -- ID string, which is "IMA_ADPCM_Sound".

''dwBlockSize'' -- the block size for the audio stream in the file (see below).
The music (stereo) files has this value set to 2048 and the speech/sfx (mono)
files has this set to 512. Though, those values may vary.

''szFileID'' -- the string ID of the given file. It seems to be the internal
name for the file (which coincides with the file title for stand-alone files).

''dwOutSize'' -- number of samples in the file. May be used for song length
(in seconds) calculation.

''dwStereo'' -- this seems to be boolean stereo flag: if this is not zero, the
audio stream in the file is stereo (music), otherwise it's mono (sfx, speech).

''dwUnknown1'' -- the unknown field. All ISS files in The Longest Journey have
this field set to 1.

''dwRateDevider'' -- the value which determines sample rate for the file: the
sample rate is equal to (44100/dwRateDevider).

''dwUnknown2'' -- the unknown field. All ISS files in The Longest Journey have
this value set to 0.

''szVersion'' -- version ID string, all files in The Longest Journey have this
set to "1.000". Note that this field may, in principle, vary.

''dwSize'' -- the size of the audio stream in the file. The total filesize is
the sum of the header size and this value.

The resolution is NOT specified in the header, so the default value (16-bit)
should be used.

After the ISSHeader IMA ADPCM compressed sound data comes. The stream is
devided into the blocks each being (''dwBlockSize'') long. Each block begins
with the small header, containing initial values for IMA ADPCM decompression:

struct ISSBlockHeader
{
SHORT iSample;
SHORT iIndex;
};

For mono audio stream there's only one such header, while for stereo stream
there're two consecutive headers -- for left and right channels. Right after
the block header (or two of them for stereo stream) comes IMA ADPCM compressed
audio data. You may find IMA ADPCM decompression scheme description further
in this document.

== IMA ADPCM Decompression Algorithm ==

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==
[http://www.mobygames.com/game/windows/longest-journey The Longest Journey]

[[Category:Audio Codecs]]
[[Category:ADPCM Audio Codecs]]
[[Category:Game Formats]]