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:

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.

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.

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.

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.

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.

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.

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: