Supports a machine's audio hardware and provides a client-server audio management service.

The Audio class provides a comprehensive audio service that works across multiple platforms and follows a client-server design model. It serves as the foundation for all audio operations in the Parasol framework, managing hardware resources, sample mixing, and output buffering.

The Audio class supports 8/16/32 bit output in stereo or mono configurations, with advanced features including oversampling for enhanced quality, intelligent streaming for large samples, multiple simultaneous audio channels, and command sequencing for precise timing control. The internal floating-point mixer ensures high-quality audio processing regardless of the target hardware bit depth.

For straightforward audio playback requirements, we recommend using the Sound class interface, which provides a simplified API whilst utilising the Audio class internally. Direct use of the Audio class is appropriate for applications requiring precise mixer control, multiple simultaneous samples, or custom audio processing workflows.

Note: Support for audio recording is not currently available in this implementation.

Structure

The Audio class consists of the following fields:

Access

Name

Type

Comment

BitDepth INT The bit depth affects the overall quality of audio input and output.

This field manages the bit depth for audio mixing and output. Valid bit depths are 8, 16 and 24, with 16 being the recommended value for CD quality playback.

Device STRING The name of the audio device used by this audio object.

A host platform may have multiple audio devices installed, but a given audio object can represent only one device at a time. A new audio object will always represent the default device initially. Choose a different device by setting the Device field to a valid alternative.

The default device can always be referenced with a name of default.

Flags ADF Special audio flags can be set here.

The audio class supports a number of special flags that affect internal behaviour. The following table illustrates the publicly available flags:

Name	Description
ADF::AUTO_SAVE	Save configuration information on exit.
ADF::FILTER_HIGH	Enable a high level of output filtering to minimise distortion.
ADF::FILTER_LOW	Enable a low level of output filtering to minimise distortion.
ADF::OVER_SAMPLING	Enables oversampling for higher quality audio at the cost of slower mixing.
ADF::STEREO	Enable stereo output (set by default if the platform supports stereo). If not set, output is in mono.
ADF::SYSTEM_WIDE	Mixer changes should be applied system-wide.
ADF::VOL_RAMPING	Enable volume ramping for softer playback when a sample is played multiple times (enabled by default).

InputRate INT Determines the frequency to use when recording audio data.

The InputRate determines the frequency to use when recording audio data from a Line-In connection or microphone. In most cases, this value should be set to 44100 for CD quality audio.

The InputRate can only be set prior to initialisation, further attempts to set the field will be ignored. On some platforms, it may not be possible to set an InputRate that is different to the OutputRate. In such a case, the value of the InputRate shall be ignored.

MasterVolume DOUBLE The master volume to use for audio playback.

The MasterVolume field controls the amount of volume applied to all of the audio channels. Volume is expressed as a value between 0 and 1.0.

MixerLag DOUBLE Returns the lag time of the internal mixer, measured in seconds.

This field will return the worst-case value for latency imposed by the internal audio mixer. The value is measured in seconds and will differ between platforms and user configurations.

Mute INT Mutes all audio output.

Audio output can be muted at any time by setting this value to true. To restart audio output after muting, set the field to false. Muting does not disable the audio system, which is achieved by calling Deactivate().

OutputRate INT Determines the frequency to use for the output of audio data.

The OutputRate determines the frequency of the audio data that will be output to the audio speakers. In most cases, this value should be set to 44100 for CD quality audio.

The OutputRate can only be set prior to initialisation, further attempts to set the field will be ignored.

PeriodSize INT Defines the byte size of each period allocated to the internal audio buffer.

The PeriodSize field determines the granularity of audio buffer management, affecting system responsiveness, processing efficiency, and overall audio quality. This setting works in conjunction with the Periods field to define the complete buffering architecture.

Minimum: 1024 bytes (1KB) - Enables very low latency but requires high-performance processing.
Maximum: 16384 bytes (16KB) - Provides maximum buffering and processing time per period.
Recommended: 2048 bytes (2KB) - Optimal balance for most applications and hardware configurations.

Period latency (in seconds) = PeriodSize ÷ (SampleRate × Channels × BytesPerSample)

For example, with a 2048-byte period at 44100Hz stereo 16-bit Latency = 2048 ÷ (44100 × 2 × 2) = 11.6ms per period

The combination of PeriodSize and Periods creates a multi-stage buffering system where audio data flows through sequential periods, providing time for processing whilst maintaining continuous playback.

Application Guidelines

Real-time applications: Use smaller periods (1-2KB) with fewer periods for minimal latency.
General applications: Use medium periods (2-4KB) with 4 periods for reliable performance.
Background audio: Use larger periods (8-16KB) with more periods for maximum efficiency.

Periods INT Defines the number of periods that make up the internal audio buffer.

The Periods field controls the segmentation of the internal audio buffer, directly affecting latency, performance, and audio continuity. This setting is particularly relevant for ALSA-based systems where period-based buffering is fundamental to audio driver operation.

The total audio buffer is divided into discrete periods, each representing a contiguous block of audio data. The audio system processes data period by period, allowing for predictable latency characteristics and efficient interrupt handling.

Minimum: 2 periods (provides double-buffering for basic audio continuity)
Maximum: 16 periods (enables extensive buffering for demanding applications)
Recommended: 4 periods (balances latency and reliability for most use cases)

Fewer periods reduce overall system latency but increase the risk of audio dropouts if processing cannot keep pace with audio consumption. More periods provide greater buffering security at the cost of increased latency.

Quality INT Determines the quality of the audio mixing.

The Quality field controls the precision and filtering applied during audio mixing operations. This setting automatically configures multiple internal processing parameters to balance audio fidelity against computational overhead.

The value range spans from 0 (minimal processing) to 100 (maximum fidelity), with recommended settings between 70-80 for most applications. This range provides an optimal balance between audio clarity and system performance.

Setting the Quality value automatically adjusts the following processing flags:

Quality 0-9: Minimal processing, no filtering or oversampling applied.
Quality 10-32: Enables ADF::FILTER_LOW for basic output filtering.
Quality 33-65: Activates ADF::FILTER_HIGH for enhanced frequency response.
Quality 66-100: Implements ADF::OVER_SAMPLING and ADF::FILTER_HIGH for maximum fidelity.

Stereo INT Set to true for stereo output and false for mono output.

Actions

The following actions are currently supported:

Activate

Enables access to the audio hardware and initialises the mixer.

ERR acActivate(*Object)

An audio object must be activated before it can play audio samples. The activation process involves several critical steps: hardware resource acquisition, mixer buffer allocation, and platform-specific driver initialisation.

Activation attempts to gain exclusive or shared access to the audio hardware device. On some platforms, this may fail if another process has obtained an exclusive lock on the audio device. The specific behaviour depends on the underlying audio system (ALSA on Linux, DirectSound on Windows).

If activation fails, the audio object remains in an inactive state but retains its configuration. Common failure causes include hardware device unavailability, insufficient system resources, or driver compatibility issues.

All resources and device locks obtained during activation can be released through Deactivate(). An inactive audio object can perform configuration operations but cannot process audio samples.

Error Codes

Okay	Hardware activation completed successfully.
Failed	Hardware device unavailable or driver initialisation failed.
AllocMemory	Failed to allocate internal mixing buffers.

Deactivate

Disables the audio mixer and returns device resources to the system.

ERR acDeactivate(*Object)

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.

SaveSettings

Saves the current audio settings.

SaveToObject

Saves the current audio settings to another object.

ERR acSaveToObject(*Object, OBJECTID Dest, CLASSID ClassID)

Parameter	Description
Dest	Refers to an object that will receive the encoded data.
ClassID	Can refer to a sub-class that should be used when encoding the data.

Methods

The following methods are currently supported:

AddSample Adds a new sample to an audio object for channel-based playback.

ERR snd::AddSample(OBJECTPTR Object, FUNCTION OnStop, SFM SampleFormat, APTR Data, INT DataSize, struct AudioLoop * Loop, INT LoopSize, INT * Result)

Parameter	Description
OnStop	This optional callback function will be called when the stream stops playing.
SampleFormat	Indicates the format of the sample data that you are adding.
Data	Points to the address of the sample data.
DataSize	Size of the sample data, in bytes.
Loop	Optional sample loop information.
LoopSize	Must be set to `sizeof(AudioLoop)` if `Loop` is defined.
Result	The resulting sample handle will be returned in this parameter.

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:

Name	Description
SFM::F_BIG_ENDIAN	Combine this flag with any audio format to declare it as big endian.
SFM::S16_BIT_MONO	16-bit mono signed sample.
SFM::S16_BIT_STEREO	16-bit stereo signed sample.
SFM::U8_BIT_MONO	8-bit mono unsigned sample.
SFM::U8_BIT_STEREO	8-bit stereo unsigned sample.

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:

Field	Type	Description
LoopMode	LOOP	Loop mode (single, double)
Loop1Type	LTYPE	First loop type (unidirectional, bidirectional)
Loop2Type	LTYPE	Second loop type (unidirectional, bidirectional)
Loop1Start	INT	Start of the first loop
Loop1End	INT	End of the first loop
Loop2Start	INT	Start of the second loop
Loop2End	INT	End of the second loop

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

Name	Description
LOOP::AMIGA	Single loop: Amiga style.
LOOP::AMIGA_NONE	Amiga loop: Do nothing.
LOOP::DOUBLE	Double loop: When the note is released, playing shifts to the second loop.
LOOP::SINGLE	Single loop: Releasing will end the note.
LOOP::SINGLE_RELEASE	Single loop: Sample data after the loop will be played when the note is released.

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

Name	Description
LTYPE::BIDIRECTIONAL	The sample will play in reverse whenever it hits the end marker, then forwards when it hits the start marker.
LTYPE::UNIDIRECTIONAL	The sample playback position returns to the byte position specified in the Loop1Start field.

Error Codes

Okay	Sample successfully added to the audio system.
Args	Invalid argument values provided.
AllocMemory	Failed to allocate enough memory to hold the sample data.
NullArgs	Required parameters are null or missing.

AddStream Adds a new sample-stream to an Audio object for channel-based playback.

ERR snd::AddStream(OBJECTPTR Object, FUNCTION Callback, FUNCTION OnStop, SFM SampleFormat, INT SampleLength, INT PlayOffset, struct AudioLoop * Loop, INT LoopSize, INT * Result)

Parameter	Description
Callback	This callback function must be able to return raw audio data for streaming.
OnStop	This optional callback function will be called when the stream stops playing.
SampleFormat	Indicates the format of the sample data that you are adding.
SampleLength	Total byte-length of the sample data that is being streamed. May be set to zero if the length is infinite or unknown.
PlayOffset	Offset the playing position by this byte index.
Loop	Refers to sample loop information, or `NULL` if no loop is required.
LoopSize	Must be set to `sizeof(AudioLoop)`.
Result	The resulting sample handle will be returned in this parameter.

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 INT callback(INT SampleHandle, INT Offset, UINT8 *Buffer, INT 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:

Name	Description
SFM::F_BIG_ENDIAN	Combine this flag with any audio format to declare it as big endian.
SFM::S16_BIT_MONO	16-bit mono signed sample.
SFM::S16_BIT_STEREO	16-bit stereo signed sample.
SFM::U8_BIT_MONO	8-bit mono unsigned sample.
SFM::U8_BIT_STEREO	8-bit stereo unsigned sample.

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:

Field	Type	Description
LoopMode	LOOP	Loop mode (single, double)
Loop1Type	LTYPE	First loop type (unidirectional, bidirectional)
Loop2Type	LTYPE	Second loop type (unidirectional, bidirectional)
Loop1Start	INT	Start of the first loop
Loop1End	INT	End of the first loop
Loop2Start	INT	Start of the second loop
Loop2End	INT	End of the second loop

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

Name	Description
LOOP::AMIGA	Single loop: Amiga style.
LOOP::AMIGA_NONE	Amiga loop: Do nothing.
LOOP::DOUBLE	Double loop: When the note is released, playing shifts to the second loop.
LOOP::SINGLE	Single loop: Releasing will end the note.
LOOP::SINGLE_RELEASE	Single loop: Sample data after the loop will be played when the note is released.

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

Okay	Stream successfully configured and added to the audio system.
Args	Invalid argument values provided.
AllocMemory	Failed to allocate the stream buffer.
NullArgs	Required parameters are null or missing.

Beep Generates system alert tones through the platform's audio notification system.

ERR snd::Beep(OBJECTPTR Object, INT Pitch, INT Duration, INT Volume)

Parameter	Description
Pitch	The pitch of the beep in HZ.
Duration	The duration of the beep in milliseconds.
Volume	The volume of the beep, from 0 to 100.

Use Beep to emit a tone from the platform's audio notification system, typically through the PC speaker or other system-level audio devices. This method is useful for generating simple alert sounds or notifications without requiring a full audio sample or stream.

Error Codes

Okay	Operation successful.
NoSupport	PC speaker support is not available.
NullArgs	Function call missing argument value(s)

CloseChannels Frees audio channels that have been allocated for sample playback.

ERR snd::CloseChannels(OBJECTPTR Object, INT Handle)

Parameter	Description
Handle	Must refer to a channel handle returned from the OpenChannels() method.

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

Okay	Operation successful.
Args	Invalid arguments passed to function.
NullArgs	Function call missing argument value(s)

OpenChannels Allocates audio channels that can be used for sample playback.

ERR snd::OpenChannels(OBJECTPTR Object, INT Total, INT * Result)

Parameter	Description
Total	Total of channels to allocate.
Result	The resulting channel handle is returned in this parameter.

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

Okay	Operation successful.
OutOfRange	The amount of requested channels or commands is outside of acceptable range.
AllocMemory	Memory for the audio channels could not be allocated.
NullArgs	Function call missing argument value(s)

RemoveSample Removes a sample from the global sample list and deallocates its resources.

ERR snd::RemoveSample(OBJECTPTR Object, INT Handle)

Parameter	Description
Handle	The handle of the sample that requires removal.

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

Okay	Operation successful.
OutOfRange	The provided sample handle is not within the valid range.
NullArgs	Function call missing argument value(s)

SetSampleLength Sets the byte length of a streaming sample.

ERR snd::SetSampleLength(OBJECTPTR Object, INT Sample, INT64 Length)

Parameter	Description
Sample	A sample handle from AddStream().
Length	Byte length of the sample stream.

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

Okay	Operation successful.
Failed	Sample is not a stream.
Args	Invalid arguments passed to function.
NullArgs	Function call missing argument value(s)

SetVolume Sets the volume for input and output mixers.

ERR snd::SetVolume(OBJECTPTR Object, INT Index, CSTRING Name, SVF Flags, INT Channel, DOUBLE Volume)

Parameter	Description
Index	The index of the mixer that you want to set.
Name	If the correct index number is unknown, the name of the mixer may be set here.
Flags	Optional flags.
Channel	A specific channel to modify (e.g. `0` for left, `1` for right). If `-1`, all channels are affected.
Volume	The volume to set for the mixer, from 0 to 1.0. If `-1`, the current volume values are retained.

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:

Name	Description
SVF::CAPTURE	Set input, not output.
SVF::MUTE	Mute the audio for this channel.
SVF::UNMUTE	Unmute the audio for this channel.

Error Codes

Okay	The new volume was applied successfully.
Args	Invalid arguments passed to function.
OutOfRange	The `Volume` or `Index` is out of the acceptable range.
NullArgs	Function call missing argument value(s)

ADF Type

Optional flags for the Audio object.

Name	Description
ADF::AUTO_SAVE	Save configuration information on exit.
ADF::FILTER_HIGH	Enable a high level of output filtering to minimise distortion.
ADF::FILTER_LOW	Enable a low level of output filtering to minimise distortion.
ADF::OVER_SAMPLING	Enables oversampling for higher quality audio at the cost of slower mixing.
ADF::STEREO	Enable stereo output (set by default if the platform supports stereo). If not set, output is in mono.
ADF::SYSTEM_WIDE	Mixer changes should be applied system-wide.
ADF::VOL_RAMPING	Enable volume ramping for softer playback when a sample is played multiple times (enabled by default).

LOOP Type

Loop modes for the AudioLoop structure.

Name	Description
LOOP::AMIGA	Single loop: Amiga style.
LOOP::AMIGA_NONE	Amiga loop: Do nothing.
LOOP::DOUBLE	Double loop: When the note is released, playing shifts to the second loop.
LOOP::SINGLE	Single loop: Releasing will end the note.
LOOP::SINGLE_RELEASE	Single loop: Sample data after the loop will be played when the note is released.

LTYPE Type

Loop types for the AudioLoop structure.

Name	Description
LTYPE::BIDIRECTIONAL	The sample will play in reverse whenever it hits the end marker, then forwards when it hits the start marker.
LTYPE::UNIDIRECTIONAL	The sample playback position returns to the byte position specified in the Loop1Start field.

SFM Type

These audio bit formats are supported by AddSample and AddStream.

Name	Description
SFM::F_BIG_ENDIAN	Combine this flag with any audio format to declare it as big endian.
SFM::S16_BIT_MONO	16-bit mono signed sample.
SFM::S16_BIT_STEREO	16-bit stereo signed sample.
SFM::U8_BIT_MONO	8-bit mono unsigned sample.
SFM::U8_BIT_STEREO	8-bit stereo unsigned sample.

SVF Type

Flags for the SetVolume() method.

Name	Description
SVF::CAPTURE	Set input, not output.
SVF::MUTE	Mute the audio for this channel.
SVF::UNMUTE	Unmute the audio for this channel.

AudioLoop Structure

Loop settings for the AddSample() method.

Field	Type	Description
LoopMode	LOOP	Loop mode (single, double)
Loop1Type	LTYPE	First loop type (unidirectional, bidirectional)
Loop2Type	LTYPE	Second loop type (unidirectional, bidirectional)
Loop1Start	INT	Start of the first loop
Loop1End	INT	End of the first loop
Loop2Start	INT	Start of the second loop
Loop2End	INT	End of the second loop

Audio Class

Structure

Application Guidelines

Actions

Methods

ADF Type

LOOP Type

LTYPE Type

SFM Type

SVF Type

AudioLoop Structure