Sound handling

m4nfo enables usage of sounds in three different ways:

• Definition of binary included sound samples,
• Definition of properties for new sound effects,
• Callbacks for handling sound effects.

Definition of binary included sound samples

When defining binary included custom sound samples, the newly defined sounds will be assigned sound-IDs numbered consecutively, starting from 73 (0x49). Sound-IDs 0 .. 72 are representing TTD's original sounds.

Function	Description
defsnd(<String>, <String>)	Define a binary sound file
refsnd(<String>)	Return sound-ID of previously defined sound
soundtable({defsnd()})	Define a table of sound IDs

defsnd(<String>, <String>)

This function defines a new sound sample by linking the sample's file name (second parameter) with a freely named label (first parameter). The label is used to access a particular sample from the various sound effect functions, and it is internally linked with a sound-ID above 73.

Sound sample files must be in WAV format, 8-bit mono, PCM encoding. There are two allowed frequencies: 11025 Hz and 22050 Hz. Due to some limitations of TTD's GRF format, the file size cannot exceed 64 kB.

refsnd(<String>)

This function refers to a previously defined new sound sample by means of a callback return value when in CB_SOUND. For an application example, see soundevent().

soundtable({defsnd()})

This function defines a set of sounds. It is simply a 'wrapper' for all newly defined sound samples, and there may be only one soundtable() in a newGRF file.

soundtable(
	defsnd(SND_SVT137, svt137.wav)
	defsnd(SND_V140, v140.wav)
	defsnd(SND_VT08, vt08k.wav)
	defsnd(SND_VT08TUN, vt08l.wav)
	defsnd(SND_VT95, vt95.wav)
	defsnd(SND_VT11, vt11.wav)
	defsnd(SND_V100, v100.wav)
)

Definition of properties for new sound effects

These functions allow adjustment of properties for already defined sounds (see above).

Function	Description
volume([0 .. 128])	relative volume
priority(<Byte>)	priority
override([0 .. 72])	override old sound

volume([0 .. 128])

This function defines the volume of the sound effect relatively to the main volume. The maximum value is "128" (0dB), the minimum is "0" (-24dB). If unset, the volume defaults to 80h.

priority(<Byte>)

This value is only meaningful in TTDPatch's DOS version, where there are limited mixing channels. The lower this byte is, the higher the priority of the sound is. If a sound needs to be played when all mixing channels are busy, the mixer will stop one of the lower priority sounds. Less important sounds should have this byte higher. If unset, priority defaults to "0".

override([0 .. 72])

Overrides the given old sound (i.e., sound-IDs 0 .. 72) with the current one. This also changes the sound effect to use the relative volume and priority associated with the current one.

definesound(<String>,<block>)

This function sets the properties of a specified sound as explained above (volume, priority, overrride). Its parameters are the sound's label, and a block of property-defining functions, where the relative position of the property functions is irrelevant.

definesound(SND_VT95,
	volume(100)  // 0 .. 80h
	priority(0)  // highest
	override(23) // override given old sound
)  

Callbacks for handling sound effects

There are two types of callbacks for handling sound effects, one is for handling sound effects for vehicles and bridges (CB_SOUND), and the other is for handling ambient sound effects.

Sound callback for vehicles

Callback CB_SOUND is documented with the appropriate vehicles, e.g. for trains. The m4nfo tutorial has a complete example of sound for trains.

Ambient sound callback

This callback is a generic callback used for playing ambient sound effects.

Its return value is a sound effect number. Values 0 .. 72 are TTD's built-in sound effects, values beyond that refer to custom sounds defined as above.

To decide whether to play a sound, and what sound to play, function ambientsound() is used.

Please note that this feature has not been implemented into m4nfo at the time being.