Ecasound Sample Rate Mismatches in Chainsetups

Ecasound processes multitrack audio under a unified processing engine, which means that every chain within an active chainsetup must adhere to a single global sample rate. When inputs, outputs, or individual chains contain conflicting sample rates, Ecasound does not run independent, asynchronous clock domains across those chains. Instead, it resolves mismatches through global format negotiation, integration with underlying sound architectures, integrated resampling algorithms, or by reporting configuration errors.

The Global Clock Rule in Ecasound

An Ecasound chainsetup strictly operates on a single master sample rate. When a chainsetup is initialized, Ecasound establishes its engine parameters—specifically sample format, channel count, and sample rate—either derived from an explicit global format argument (-f), negotiated from the primary audio device, or inherited from the first defined audio input.

Because every processing chain in a chainsetup executes concurrently within the same processing loop, audio buffers must contain the exact same number of samples per unit of time across all chains. Ecasound cannot process one chain at 44.1 kHz and another chain at 96 kHz simultaneously inside the same internal mixing graph.

File Input Handling and Automatic Resampling

When reading from audio files (such as WAV, FLAC, or AIFF) that possess a sample rate different from the chainsetup's designated rate, Ecasound's behavior depends on the audio file library it was compiled with:

• Libsamplerate / Sndfile Support: If Ecasound is compiled with support for libsamplerate (Secret Rabbit Code) or utilizes modern libsndfile routines, it can automatically convert the input stream's sampling rate to match the chainsetup's target rate during decoding.
• Format Specification Enforcement: If an input file has a differing rate and automatic conversion is not triggered, Ecasound will either throw an audio format mismatch error during the setup configuration phase or force the engine into the file's native rate, potentially breaking compatibility with other defined inputs.

Real-Time Devices: ALSA, JACK, and OSS

Real-time audio backends introduce hard constraints when dealing with rate discrepancies across chains:

• JACK Audio Connection Kit: JACK operates at a single server-wide sample rate. If an Ecasound chainsetup uses JACK inputs or outputs (-i:jack, -o:jack), the chainsetup must strictly match the running JACK server's sample rate. Ecasound cannot negotiate differing rates across chains connected to JACK; rate conversion must occur outside Ecasound via client bridges (such as zita-j2a or jack-matchmaker).
• ALSA Devices: If multiple chains route to or from different physical ALSA hardware devices (-i:alsa,hw:X,Y) that do not support the same native sampling frequency, direct hardware access fails. To resolve this mismatch, routing through ALSA’s plughw layer (-i:alsa,plughw:X,Y) delegates the rate conversion to ALSA's internal rate converter plugin before reaching Ecasound's processing chains.

Manual Sample Rate Conversion Operators

For precise control over quality and resource usage, Ecasound includes native rate conversion operators that can be inserted into individual chains.

• The -er and -erc Operators: Users can insert the resample effect directly into a chain's processing pipeline. The -erc:rate,quality operator resamples audio to the specified target rate using varying conversion algorithms (ranging from linear interpolation to high-quality sinc interpolation).
• Loop Devices (loop): When combining sources that cannot natively reconcile rates within a single pass, chains can be decoupled using internal loop devices (-i:loop,1 and -o:loop,1). While the loop mechanism transfers audio between chains, both chains still execute at the chainsetup's master clock rate, requiring any manual rate adjustments to take place prior to pushing audio into the loop.

Behavior with Raw Audio Streams

When using raw, headerless audio streams (-i:stdin, raw audio files, or pipes), Ecasound has no metadata to detect a mismatch. If a raw stream recorded at 48 kHz is fed into a chain configured for 44.1 kHz, Ecasound will process the samples at the chainsetup's rate without resampling. This results in pitch alteration and speed distortion (the audio plays back slower or faster) rather than a software error.

Summary of Resolution Methods

To maintain stability across chains with mismatched rates:

1. Define a Master Format: Explicitly state the target rate using the global -f flag (e.g., -f:s16_le,2,48000) so the engine establishes a definitive processing standard.
2. Use Software Device Plugins: Use ALSA's plughw or software wrappers to standardize hardware rates before they reach Ecasound.
3. Pre-convert Sources: Use offline tools like sox to resample disparate audio files prior to assembling the chainsetup, ensuring minimal CPU overhead and optimal synchronization.