==============================
- INFOCOM SOUND FILE FORMATS -
==============================

Author: Stefan Jokisch (jokisch@ls7.informatik.uni-dortmund.de)

Last updated: 8-FEB-95

Sound effects are included in "The Lurking Horror" (Amiga) and
"Sherlock" (Amiga & Mac). A special opcode called sound_effect is
used to play the sounds which are stored on the disk:

        sound_effect number command volume routine

"number" is the number of the sound (1 is a high beep sound, 2 is
a low beep sound, > 2 are sample files). "command" is what to do:
1 = load sound, 2 = play sound, 3 = stop sound, 4 = drop sound
(ie. free memory). In practice, command 1 is never used, so the
interpreter has to care about loading the sounds. "volume" is the
volume to play the sound at, ranging from 1 to 8 (reportedly, -1
meaning a default volume). In Z-code 5, the upper byte of "volume"
contains the #repeats to play (-1 meaning infinite repetition).
"routine" points to a function that must be called after the sound
was played.

1) Sound format on the Amiga
----------------------------

All sound related files are stored in a directory called "Sound".
There are three different file types: NAM files, DAT files and MID
files. First of all, the NAM file that belongs to, say, effect #13
is called "s13.nam". It uses the following format:

        +------+------+--------------------------+
        | pos  | size | contents                 |
        +======+======+==========================+
        |   0  |   2  | (always $0100)           | prefix (?)
        +------+------+--------------------------+
        |   2  |   ?  | name of DAT file         | body
        |      |   2  | (always $0000)           |
        |      |   ?  | name of MID file         |
        |      |   2  | (always $0000)           |
        +------+------+--------------------------+

A DAT file can have any arbitrary name; some are called *.dat, some
are called *.bin and some have no extension at all. The DAT file
starts with a word which contains the size of the following data in
bytes (ie. the file length minus two). Next comes the header of 8
bytes. The sample data follows right behind the header.

        +------+------+--------------------------+
        | pos  | size | contents                 |
        +======+======+==========================+
        |   0  |   2  | length of following data | prefix
        +------+------+--------------------------+
        |   2  |   1  | repeats to play          | header
        |   3  |   1  | base note                |
        |   4  |   2  | sample frequency         |
        |   6  |   2  | *** unused ***           |
        |   8  |   2  | sample data length       |
        +------+------+--------------------------+
        |  10  |   ?  | 8-bit signed mono data   | sample data
        +------+------+--------------------------+

"repeats to play" may be 0 causing infinite repetition (in Z-code
5, the #repeats to play is usually given by the third argument of
sound_effect). "base note" is hard to explain: For instance, if
you had sample data of an instrument playing the note "c", then
this should be indicated by "base note" (the formula at the end
of this section tells you what to do with this value).

MID files are usually called *.mid. Like DAT files, they start with
a prefix which contains the size of the following data in bytes.
Next comes a sequence of MIDI-like commands:

        +------+------+--------------------------+
        | pos  | size | contents                 |
        +======+======+==========================+
        |   0  |   2  | length of following data | prefix
        +------+------+--------------------------+
        |   2  |   ?  | sequence of commands     | body
        +------+------+--------------------------+

It seems to be acceptable to ignore all commands except the first
one which is always note_on ($90). The two arguments of note_on
occupy two bytes: "note" and "velocity". The latter argument may
be ignored, whereas the first argument is required to calculate
the correct frequency. The formula to determine the frequency is
pow (2, ("note" - "base note") / 12) * "sample frequency" / 4.

2) Sound format on the Mac
--------------------------

All sound related files are stored in a directory called "Sound".
The files are quite similar to the Amiga version, although a few
differences exist. To begin with, there are only DAT and MID files.

If the interpreter has to play effect #13, then it is supposed to
look for a MID file called "M13". The name of the DAT file can be
found at the end of the MID file:

        +------+------+--------------------------+
        | pos  | size | contents                 |
        +======+======+==========================+
        |   0  |   2  | length of sequence of c. | prefix
        +------+------+--------------------------+
        |   2  |   ?  | sequence of commands     | body
        +------+------+--------------------------+
        |      |   ?  | name of DAT file         | appendix
        +------+------+--------------------------+

If there is no MID file, then the interpreter should load a DAT
file called "S13" and play it at its normal "sample frequency".
The DAT files use the same format as Amiga DAT files, except that
the sample data is unsigned instead of signed.

        +------+------+--------------------------+
        | pos  | size | contents                 |
        +======+======+==========================+
        |   0  |   2  | length of following data | prefix
        +------+------+--------------------------+
        |   2  |   1  | repeats to play          | header
        |   3  |   1  | base note                |
        |   4  |   2  | sample frequency         |
        |   6  |   2  | *** unused ***           |
        |   8  |   2  | sample data length       |
        +------+------+--------------------------+
        |  10  |   ?  | 8-bit unsigned mono data | sample data
        +------+------+--------------------------+

A final note: Infocom's sound format seems to be slightly overdone.
At time of writing, it is planned to make the sounds available at
the if-archive at ftp.gmd.de. Both The Lurking Horror and Sherlock
sounds will be converted to unsigned DAT format; no MID files will
be used.

