Comprehensive audio processing and playback system with professional-grade mixing capabilities.

The Audio module provides a robust, cross-platform audio infrastructure that manages the complete audio pipeline from sample loading through to hardware output. The module's architecture supports both high-level convenience interfaces and low-level professional audio control, making it suitable for applications ranging from simple media playback to sophisticated audio production environments.

The module implements a client-server design pattern with two complementary class interfaces:

• Audio: Low-level hardware interface providing precise control over audio mixing, buffering, and output configuration. Designed for applications requiring professional audio capabilities including real-time processing, multi-channel mixing, and advanced streaming architectures
• Sound: High-level sample playback interface optimised for simplicity and performance. Automatically manages resource allocation, format conversion, and hardware abstraction whilst providing intelligent streaming decisions

The internal mixer is a floating-point engine that processes all audio internally at 32-bit precision regardless of output bit depth. The mixer supports features that include:

• Oversampling with interpolation for enhanced quality and reduced aliasing
• Real-time volume ramping to eliminate audio artefacts during playback transitions
• Multi-stage filtering with configurable low-pass and high-pass characteristics
• Sample-accurate playback positioning with sub-sample interpolation
• Bidirectional and unidirectional looping with precision loop point handling

Platform-Specific Optimisations

Audio implementation is optimised for each supported platform to maximise performance and minimise latency:

• Linux (ALSA Integration): Utilises ALSA's period-based buffering with configurable period counts and sizes. All samples are processed through the unified mixer with support for system-wide volume control and hardware mixer integration
• Windows (DirectSound Integration): Implements dual-path audio where simple playback can bypass the internal mixer for reduced latency, whilst complex operations utilise the full mixing pipeline. Automatic fallback ensures compatibility across Windows audio driver variations
• Cross-Platform Consistency: API behaviour remains consistent across platforms, with platform-specific optimisations operating transparently to applications

Streaming and Memory Management

The module implements streaming technology that automatically adapts to sample characteristics and system resources:

• Smart streaming decisions based on sample size, available memory, and playback requirements
• Configurable streaming thresholds with support for forced streaming or memory-resident operation
• Rolling buffer architecture for large samples with automatic buffer management
• Loop-aware streaming that maintains loop points during streaming operations

Usage Guidelines

For optimal results, choose the appropriate interface based on application requirements:

• Sound Class (Recommended for Most Applications): Provides immediate audio playback with automatic resource management, format detection, and intelligent streaming. Ideal for media players, games, and general-purpose audio applications
• Audio Class (Advanced Applications): Offers complete control over the audio pipeline including custom mixer configurations, real-time effects processing, and professional-grade timing control. Required for audio workstations, synthesisers, and applications with demanding audio requirements

Technical Specifications

• Internal processing: 32-bit floating-point precision
• Output formats: 8, 16, 24, and 32-bit with automatic conversion
• Sample rates: Up to 44.1 kHz (hardware dependent)
• Channel configurations: Mono and stereo with automatic format adaptation
• Latency: Platform-optimised with configurable buffering for real-time applications

Functions

MixContinue | MixEndSequence | MixFrequency | MixMute | MixPan | MixPlay | MixRate | MixSample | MixStartSequence | MixStop | MixStopLoop | MixVolume

Structures

AudioLoop

Classes

Audio | Sound

Constants

ADF | CHF | CHS | LOOP | LTYPE | NOTE | SDF | SFM | STREAM | SVF | VCF

MixContinue()

Continue playing a stopped channel.

This function will continue playback on a channel that has previously been stopped.

Error Codes

MixEndSequence()

Ends the buffering of mix commands.

Use this function to end a buffered command sequence that was started by MixStartSequence().

Error Codes

MixFrequency()

Sets a channel's playback rate.

Use this function to set the playback rate of a mixer channel.

Error Codes

MixMute()

Mutes the audio of a channel.

Use this function to mute the audio of a mixer channel.

Error Codes

MixPan()

Sets a channel's panning value.

Use this function to set a mixer channel's panning value. Accepted values are between -1.0 (left) and 1.0 (right).

Error Codes

MixPlay()

Commences channel playback at a set frequency.

This function will start playback of the sound sample associated with the target mixer channel. If the channel is already in playback mode, it will be stopped to facilitate the new playback request.

Error Codes

MixRate()

Sets a new update rate for a channel.

This function will set a new update rate for all channels, measured in milliseconds. The default update rate is 125, which is equivalent to 5000Hz.

Error Codes

MixSample()

Associate a sound sample with a mixer channel.

This function will associate a sound sample with the channel identified by Handle. The client should follow this by setting configuration details (e.g. volume and pan values).

The referenced Sample must have been added to the audio server via the Audio⇒AddSample() or Audio⇒AddStream() methods.

Error Codes

MixStartSequence()

Initiates buffering of mix commands.

Use this function to initiate the buffering of mix commands, up until a call to MixEndSequence() is made. The buffering of mix commands makes it possible to create batches of commands that are executed at timed intervals as determined by MixRate().

Command Buffering Architecture

When command buffering is activated, the mixer transitions to a batch processing mode with several key characteristics:

• Deferred Execution: All mixer operations (MixPlay(), MixVolume(), MixPan(), MixFrequency(), etc.) are queued rather than executed immediately
• Atomic Batch Processing: Queued commands are processed synchronously during the next mixer update cycle, ensuring sample-accurate timing coordination
• Thread-Safe Queueing: Commands can be safely queued from multiple threads without explicit synchronisation requirements
• Overflow Protection: Command buffers include overflow detection to prevent memory exhaustion during extended buffering periods

This feature can be used to implement complex sound mixes and digital music players.

Advanced Usage Patterns

1. Sequence Initiation: Call MixStartSequence() to begin command buffering for the target channel or channel set
2. Command Queuing: Issue multiple mixer commands (volume, pan, play, frequency adjustments, etc.) which are automatically queued
3. Sequence Completion: Call MixEndSequence() to mark the end of the command batch and schedule execution
4. Automatic Execution: Commands execute atomically at the next mixer update interval determined by MixRate()

Error Codes

MixStop()

Stops all playback on a channel.

This function will stop a channel that is currently playing.

Error Codes

MixStopLoop()

Cancels any playback loop configured for a channel.

This function will cancel the loop that is associated with the channel identified by Handle if in playback mode. The existing loop configuration will remain intact if playback is restarted.

Error Codes

MixVolume()

Changes the volume of a channel.

This function will change the volume of the mixer channel identified by Handle. Valid values are from 0 (silent) to 1.0 (maximum).

Error Codes

ADF Type

Optional flags for the Audio object.

CHF Type

Optional flags for the AudioChannel structure.

CHS Type

Channel status types for the AudioChannel structure.

LOOP Type

Loop modes for the AudioLoop structure.

LTYPE Type

Loop types for the AudioLoop structure.

NOTE Type

Definitions for the Note field. An 'S' indicates a sharp note.

SDF Type

Sound flags

SFM Type

These audio bit formats are supported by AddSample and AddStream.

STREAM Type

Streaming options

SVF Type

Flags for the SetVolume() method.

VCF Type

Volume control flags

AudioLoop Structure

Loop settings for the AddSample() method.