squishyball-rs

Squishyball-rs is a modern Rust port of the original Squishyball, a command-line utility created by Christopher "Monty" Montgomery for double-blind audio testing (A/B, A/B/X, X/X/Y) and casual sample comparison.

---

Project Context

The original C implementation performs sample-accurate alignment, channel reconciliation, and real-time crossfading. However, the legacy codebase presents maintenance challenges:

• Audio Drivers: The original relies on libao or legacy ALSA. Modern systems (PipeWire, WASAPI, CoreAudio) require modern abstractions to ensure consistent latency and buffer performance.
• Terminal Interface: The legacy mincurses.c implementation is difficult to maintain and lacks support for modern terminal features like dynamic resizing and unicode.
• Memory Management: Manual buffer allocation for varying bit-depths and sample formats (16-bit, 24-bit, float) increases the risk of memory errors.

---

Key Improvements

• Universal Audio Decoding: Powered by symphonia, the tool supports WAV, FLAC, Ogg Vorbis, Opus, MP3, and AAC without external system dependencies.
• Master-Grade Crossfading & Normalization: Glitch-free transitions and seamless sample switching are managed using configurable crossfade envelopes paired with automated peak/RMS normalization. This eliminates loudness bias (ensuring files mastered at different levels don't unfairly skew human perception during blind comparisons).
• Thread Safety: Real-time safety via lock-free atomic sample swapping and dedicated audio/UI threads.
• Statistical Analysis: Real-time binomial distribution calculations provide immediate confidence scores ($p$-values) during testing, complete with an end-of-test summary screen.
• Hardware Routing & Headless Support: Advanced audio device selection (--device, --list-devices) for dedicated DACs/interfaces, alongside fallback support and environment overrides (SQUISHYBALL_NO_AUDIO=1) for headless or CI environments.

---

Prerequisites

On Linux systems, compiling the audio backend (cpal) requires the ALSA development libraries:

sudo apt install libasound2-dev

---

Building the Project

Ensure Rust and Cargo are installed.

# Clone the repository
cd squishyball-rs

# Compile the binary
cargo build --release

The resulting binary will be located in target/release/squishyball-rs.

---

Testing & CI

To run the full test suite including application state, statistics, audio DSP, and normalization checks:

cargo test

To run tests in a headless environment or CI pipeline without audio hardware:

SQUISHYBALL_NO_AUDIO=1 cargo test

---

Usage

squishyball-rs [OPTIONS] fileA [fileB [fileN...]]

Options

• -t, --test-mode <MODE>: Set test mode (0: A/B, 1: A/B/X, 2: X/X/Y, 3: Casual).
• -d, --device <NAME>: Specify a target audio output device name.
• --list-devices: List available audio output devices and exit.
• -h, --help: Display usage summary.

---

Keyboard Controls

• a, b, x: Switch between samples (mode dependent).
• 1, 2, 3...: Select sample (X/X/Y or casual modes).
• <space>: Pause/Resume.
• <backspace>: Reset playback.
• q or Esc: Exit.