An audio object will not play or record until it has been activated. Activating the object will result in an attempt to access the device hardware, which on some platforms may lead to failure if another process has permanently locked the audio device. The resources and any device locks obtained by this action can be released with a call to Deactivate().

An inactive audio object can operate in a limited fashion but is without access to the audio hardware.

Deactivating an audio object will switch off the mixer, clear the output buffer and return any allocated device resources back to the host system. The audio object will remain in a suspended state until it is reactivated.

Audio samples can be loaded into an Audio object for playback via the AddSample() or AddStream() methods. For small samples under 512k we recommend AddSample(), while anything larger should be supported through AddStream().

When adding a sample, it is essential to select the correct bit format for the sample data. While it is important to differentiate between simple attributes such as 8 or 16 bit data, mono or stereo format, you should also be aware of whether or not the data is little or big endian, and if the sample data consists of signed or unsigned values. Because of the possible variations there are a number of sample formats, as illustrated in the following table:

By default, all samples are assumed to be in little endian format, as supported by Intel CPU's. If the data is in big endian format, logical-or the SampleFormat value with SFM::F_BIG_ENDIAN.

It is also possible to supply loop information with the sample data. This is achieved by configuring the AudioLoop structure:

The types that can be specified in the LoopMode field are:

The Loop1Type and Loop2Type fields alter the style of the loop. These can be set to the following:

Error Codes

Use AddStream to load large sound samples to an Audio object, allowing it to play those samples on the client machine without over-provisioning available resources. For small samples under 256k consider using AddSample() instead.

The data source used for a stream will need to be provided by a client provided Callback function. The prototype is LONG callback(LONG SampleHandle, LONG Offset, UBYTE *Buffer, LONG BufferSize).

The Offset reflects the retrieval point of the decoded data and is measured in bytes. The Buffer and BufferSize reflect the target for the decoded data. The function must return the total number of bytes that were written to the Buffer. If an error occurs, return zero.

When creating a new stream, pay attention to the audio format that is being used for the sample data. It is important to differentiate between 8-bit, 16-bit, mono and stereo, but also be aware of whether or not the data is little or big endian, and if the sample data consists of signed or unsigned values. Because of the possible variations there are a number of sample formats, as illustrated in the following table:

By default, all samples are assumed to be in little endian format, as supported by Intel CPU's. If the data is in big endian format, logical-or the SampleFormat value with the flag SFM::F_BIG_ENDIAN.

It is also possible to supply loop information with the stream. The Audio class supports a number of different looping formats via the AudioLoop structure:

There are three types of loop modes that can be specified in the LoopMode field:

The Loop1Type and Loop2Type fields normally determine the style of the loop, however only unidirectional looping is currently supported for streams. For that reason, set the type variables to either LTYPE::NIL or LTYPE::UNIDIRECTIONAL.

Error Codes

This method will beep the PC audio speaker, if available. It is possible to request the specific Pitch, Duration and Volume for the sound although not all platforms may support the parameters. In some cases the beep may be converted to a standard warning sound by the host.

Error Codes

Use CloseChannels to destroy a group of channels that have previously been allocated through the OpenChannels() method. Any audio commands buffered against the channels will be cleared instantly. Any audio data that has already been mixed into the output buffer can continue to play for 1 - 2 seconds. If this is an issue then the volume should be muted at the same time.

Error Codes

Use the OpenChannels method to open audio channels for sample playback. Channels are allocated in sets with a size range between 1 and 64. Channel sets make it easier to segregate playback between users of the same audio object.

The resulting handle returned from this method is an integer consisting of two parts. The upper word uniquely identifies the channel set that has been provided to you, while the lower word is used to refer to specific channel numbers. If referring to a specific channel is required for a function, use the formula Channel = Handle | ChannelNo.

To destroy allocated channels, use the CloseChannels() method.

Error Codes

Remove an allocated sample by calling the RemoveSample method. Removed samples are permanently deleted from the audio server and it is not possible to reallocate the sample against the same Handle value.

Sample handles can be reused by the API after being removed. Clearing references to stale sample handles on the client side is recommended.

Error Codes

This function will update the byte length of a streaming Sample. Although it is possible to manually stop a stream at any point, setting the length is a preferable means to stop playback as it ensures complete accuracy when a sample's output is buffered.

Setting a Length of -1 indicates that the stream should be played indefinitely.

Error Codes

To change volume and mixer levels, use the SetVolume method. It is possible to make adjustments to any of the available mixers and for different channels per mixer - for instance you may set different volumes for left and right speakers. Support is also provided for special options such as muting.

To set the volume for a mixer, use its index or set its name (to change the master volume, use a name of Master).

A target Channel such as the left 0 or right 1 speaker can be specified. Set the Channel to -1 if all channels should be the same value.

The new mixer value is set in the Volume field.

Optional flags may be set as follows:

Error Codes