Add CPAL audio backend with multiple waveforms, feature flag, and fixes

Previous: SPKRD was a FreeBSD-only HTTP speaker server that played
melodies only via /dev/speaker. The core components (HTTP API, retry
logic, server structure) were stable, but audio synthesis was limited to
single backend with step-discontinuity clicks at note boundaries.

Changed: Refactored to support multiple audio backends. Extracted the
original /dev/speaker handler to src/freebsd_speaker.rs. Added a new
CPAL audio backend (src/cpal_backend.rs) with five waveforms (Square,
SquareBandlimited, Sine, Triangle, Sawtooth) plus a new PC Speaker
mode with biquad frequency response simulation. Ported FreeBSD spkr.c's
MML melody interpreter to Rust (src/mml.rs), now used across all
backends. Put the CPAL backend behind a Cargo feature flag (on by
default, can be disabled on FreeBSD). Fixed a concurrency bug where
cancelling an HTTP client didn't prevent overlapping melodies; the lock
now follows the blocking task instead of the async parent. Fixed square
waveform to reset phase per tone, matching FreeBSD kernel behavior.
Updated CLI to support --output, --waveform, --volume, --sample-rate,
and cpal-specific flags. Updated README with Backends section, MML
reference, feature documentation, and waveform descriptions.

See: changelog/20260502-cpal-backend-iteration.md,
     changelog/20260503-cpal-cancellation-bug.md,
     changelog/20260503-pcspeaker-frequency-response.md,
     changelog/20260503-square-phase-reset.md

Author: knz

Cargo.lock

@@ -18,6 +18,11 @@ daemonize = "0.5"
 log = "0.4"
 env_logger = "0.10"
 syslog = "6.0"
+cpal = { version = "0.16", optional = true }
+
+[features]
+default = ["cpal"]
+cpal = ["dep:cpal"]
 
 [dev-dependencies]
 reqwest = "0.11"

Cargo.toml

@@ -1,15 +1,35 @@
-# SPKRD - FreeBSD Speaker Network Server
+# SPKRD - Speaker Network Server
 
-A network server that provides HTTP access to FreeBSD's `/dev/speaker` device for remote melody playback.
+A network server that exposes a melody-playback endpoint over HTTP. On
+FreeBSD it can drive the kernel `/dev/speaker` device directly; on any
+other host (Linux, macOS, Windows) it can synthesise the same melodies
+through the system audio output via [CPAL].
+
+[CPAL]: https://github.com/RustAudio/cpal
 
 ## Overview
 
-SPKRD exposes FreeBSD's built-in speaker device over HTTP, allowing you to play melodies remotely from any system that can make HTTP requests. The server handles device concurrency automatically with configurable retry logic.
+SPKRD accepts FreeBSD-style melody strings over HTTP and plays them
+back through one of two backends:
+
+- **`freebsd-speaker`** — writes the melody to the kernel
+  `/dev/speaker` character device. The kernel driver does the
+  synthesis on the PC speaker hardware.
+- **`cpal`** — parses the melody in user space (a faithful Rust port
+  of the FreeBSD `spkr.c` interpreter) and renders it to audio via
+  CPAL using a configurable waveform (square / band-limited square /
+  sine / triangle / sawtooth).
+
+In `--output=auto` (the default) the server probes the configured
+device path and uses `freebsd-speaker` if it exists, falling back to
+`cpal` otherwise. Both backends share the same HTTP surface, retry
+logic, validation, and one-melody-at-a-time semantics.
 
 ## Features
 
 - **HTTP API** - Simple PUT endpoint for melody playback
-- **Device Retry Logic** - Automatically retries when device is busy (1s intervals, configurable timeout)
+- **Two backends** - FreeBSD `/dev/speaker` or cross-platform CPAL audio output
+- **Device Retry Logic** - Automatically retries when busy (1s intervals, configurable timeout)
 - **Input Validation** - Melody length limits and UTF-8 validation
 - **Configurable Device Path** - Use custom device paths for testing or alternative devices
 - **Daemon Support** - Run as background daemon with PID file management
@@ -40,12 +60,14 @@ Example: `"t120l4 c d e f g a b o5c"`
 
 - Rust 1.70+ (for server)
 - Go 1.19+ (for Go client example)
-- FreeBSD system with `/dev/speaker` device
+- FreeBSD with `/dev/speaker` for the `freebsd-speaker` backend; any
+  CPAL-supported host (Linux/ALSA, macOS/CoreAudio, Windows/WASAPI,
+  JACK, …) for the `cpal` backend
 
 ### Building
 
 ```bash
-# Clone and build the server
+# Clone and build the server with the default features (includes CPAL)
 git clone <repository-url>
 cd spkrd
 cargo build --release
@@ -56,6 +78,26 @@ cargo build --release  # Rust client
 go build client.go      # Go client
 ```
 
+### Build features
+
+The `cpal` Cargo feature controls whether the user-space audio
+synthesis backend is compiled in. It is **enabled by default**.
+
+```bash
+# Default build: both backends available
+cargo build --release
+
+# FreeBSD: typically you only want the kernel backend. Disabling
+# the `cpal` feature removes the cpal dependency and shrinks the
+# binary; --output=cpal and the related --waveform/--volume/
+# --sample-rate/--cpal-host/--cpal-device flags become unavailable.
+cargo build --release --no-default-features
+```
+
+When built without the `cpal` feature, `--output=auto` will fail at
+startup if the configured device path does not exist (rather than
+silently falling back to a non-existent CPAL backend).
+
 ### System-Wide Installation
 
 For production deployment as a system service on FreeBSD:
@@ -89,12 +131,42 @@ spkrd_flags="--port 1111 --device /dev/speaker --retry-timeout 30"
 
 **Available configuration flags:**
 - `--port <port>` - Server port (default: 1111)
-- `--device <path>` - Speaker device path (default: /dev/speaker)  
+- `--device <path>` - Speaker device path (default: /dev/speaker)
+- `--output <mode>` - Output backend: `auto`, `freebsd-speaker`, or `cpal` (default: auto; `cpal` only available when built with the `cpal` feature)
 - `--retry-timeout <secs>` - Device retry timeout (default: 30)
 - `--daemon` - Run as background daemon (automatically added by rc.d)
 - `--pidfile <path>` - PID file path (default: /var/run/spkrd.pid)
 - `--debug/-d` - Enable debug logging including client request details
 
+**CPAL-only flags (only present when built with the `cpal` feature):**
+- `--waveform <wf>` - `pc-speaker` (default), `square-bandlimited` (sounds nice), `square`, `sine`, `triangle`, or `sawtooth`
+- `--volume <v>` - Output volume in `[0.0, 1.0]` (default: 0.25)
+- `--sample-rate <hz>` - Override the device's default sample rate
+- `--cpal-host <name>` - CPAL host backend (e.g. ALSA, JACK, CoreAudio); defaults to the platform default
+- `--cpal-device <name>` - Output device name; defaults to the host's default output
+
+The `pc-speaker` waveform is a faithful simulation of a modern
+piezoelectric PC speaker: note frequencies are quantised to what the
+Intel 8254 PIT can actually produce (`1,193,182 Hz / divisor`, integer
+divisor), a square wave at that frequency is processed through a 3-stage
+biquad chain (high-pass / midrange peak / low-pass) tuned to a small
+piezo disc, and the output is soft-clipped via `tanh` to mimic driver
+saturation. The square-wave phase is reset at every note (mirroring the
+PIT counter reset the FreeBSD kernel performs in `timer_spkr_setfreq`),
+so consecutive notes — even at the same pitch — get the mechanical
+"plink" articulation a real piezo produces. Filter state is preserved
+across notes and rests, so the speaker rings out naturally on note-off
+rather than cutting silently.
+
+The `square` waveform is the kernel-faithful raw output: phase is reset
+at every note (matching the PIT counter reset) and no envelope is
+applied, so consecutive notes have hard amplitude-step boundary clicks
+that match what FreeBSD's unfiltered `/dev/speaker` output sounds like
+through a modern DAC. If you want click-suppressed alternatives, the
+remaining software waveforms (`square-bandlimited`, `sine`, `triangle`,
+`sawtooth`) keep phase continuity across notes and apply a 5 ms
+attack/release envelope to fade in/out each note.
+
 **Example configurations:**
 
 ```bash
@@ -205,10 +277,18 @@ Jan 29 10:30:17 hostname spkrd[1234]: Request from 192.168.1.100 completed succe
 - `--port` - Server port (default: 1111)
 - `--retry-timeout` - Device retry timeout in seconds (default: 30)
 - `--device` - Path to speaker device (default: /dev/speaker)
+- `--output` - Output backend: `auto` (default), `freebsd-speaker`, or `cpal` (the `cpal` value is available only when built with the `cpal` feature)
 - `--daemon` - Run as background daemon
 - `--pidfile` - Path to PID file (default: /var/run/spkrd.pid)
 - `--debug/-d` - Enable debug logging including client request details
 
+When built with the `cpal` feature, the following additional flags are
+available (and are otherwise hidden):
+
+- `--waveform`, `--volume`, `--sample-rate`, `--cpal-host`,
+  `--cpal-device` — see the configuration-flags section above for
+  details.
+
 ### API Usage
 
 #### Play a Melody
@@ -338,7 +418,7 @@ cat /tmp/test-speaker
 
 This project is licensed under the BSD 2-Clause License. See the [LICENSE](LICENSE) file for details.
 
-Copyright (c) 2025, Raphael Poss
+Copyright (c) 2025-2026, Raphael Poss
 
 ## Contributing
 

README.md

@@ -0,0 +1,131 @@
+# CPAL backend iteration
+
+## Task Specification
+
+The user wants to iterate on the recently added local-melody-playback
+feature. The relevant staged changes (not yet committed) are:
+
+- `src/mml.rs` (new): Rust port of FreeBSD `spkr.c`'s MML
+  interpreter. Produces `Event::Tone { freq_hz, centisecs }` /
+  `Event::Rest { centisecs }` sequences from a melody string.
+- `src/cpal_backend.rs` (new): synthesises an MML melody to PCM via
+  one of several waveforms (Square, SquareBandlimited, Sine,
+  Triangle, Sawtooth) and plays it through CPAL. Uses an async mutex
+  to enforce one-melody-at-a-time and reuses the
+  retry-on-busy/timeout convention. Wraps the blocking CPAL stream in
+  `spawn_blocking`.
+- `src/freebsd_speaker.rs` (new file but old behaviour): the original
+  `/dev/speaker` writer extracted out of the previous `speaker.rs`.
+- `src/lib.rs`: exposes the new modules.
+- `src/main.rs`: adds `--output` (auto/freebsd-speaker/cpal),
+  `--waveform`, `--volume`, `--sample-rate`, `--cpal-host`,
+  `--cpal-device`. `auto` falls back to CPAL when the device path is
+  missing. Warns about flags that don't apply to the resolved
+  backend.
+- `src/server.rs`: dispatches between backends through a `Backend`
+  enum.
+- `src/error.rs`: adds `CpalError(String)`.
+- `Cargo.toml`: adds the `cpal = "0.16"` dependency.
+- `tests/integration_tests.rs`: updated to use the new
+  `Backend::FreebsdSpeaker` shape.
+
+The user has not yet specified the direction of the iteration. Open
+clarifying questions are recorded below, awaiting answers before any
+implementation plan is drafted.
+
+## Iteration scope (user-specified)
+
+Three concrete deliverables for this round:
+
+1. Add a history-attribution header to `src/mml.rs` pointing at the
+   original FreeBSD `spkr.c` (sources are in `src/fbsd-speaker/`).
+2. Put the CPAL backend behind a Cargo feature flag. The feature is
+   on by default, but can be disabled at build time. Document this
+   in README and recommend disabling on FreeBSD targets (where the
+   real /dev/speaker is available).
+3. Since the project is no longer FreeBSD-only, add a short
+   description of the MML melody input language to README so users
+   not familiar with the FreeBSD speaker driver can use it.
+
+## Decisions
+
+- Cargo feature is named `cpal`; default-on. `dep:cpal` makes the
+  optional dep purely a feature gate (no implicit feature with the
+  same name as the dep).
+- Asymmetric gating: only `cpal_backend` and the cpal dependency are
+  feature-gated. `freebsd_speaker` is always compiled — it has no
+  platform-specific deps, so the savings of gating it would be
+  negligible.
+- `auto` resolution when `cpal` is disabled: if the device path is
+  missing, fail at startup with a clear message (rather than
+  resolving to `freebsd-speaker` and erroring per-request, which
+  would be noisier and harder to diagnose).
+- `--output=cpal` and the cpal-only flags are hidden from `--help`
+  when the feature is disabled (via `#[cfg(feature = "cpal")]` on
+  each `#[arg]` field and on the enum variant). The `--output` help
+  text also varies based on the feature.
+- README change scope: kept narrow. The MML "Quick Melody Syntax
+  Reference" already exists, so we only updated the project
+  framing (no longer FreeBSD-only), added the Backends paragraph,
+  and a Build features section documenting the feature flag and
+  recommending `--no-default-features` on FreeBSD targets.
+- Attribution in `mml.rs`: short two-paragraph note crediting the
+  `spkr.c` lineage (Raymond v1.4 1993, Chernov FreeBSD port),
+  with a license-compatibility note (BSD-2-Clause both sides).
+
+## Files Modified
+
+- `Cargo.toml`: `cpal` becomes optional; new `[features]` table with
+  `default = ["cpal"]` and `cpal = ["dep:cpal"]`.
+- `src/lib.rs`: gate `pub mod cpal_backend;` behind the feature;
+  refresh header comment.
+- `src/error.rs`: gate `CpalError(String)` variant + Display arm.
+- `src/server.rs`: gate `CpalBackend` import, `Backend::Cpal`
+  variant, dispatch arm, error-mapping arm, and the now-conditional
+  `Arc` import.
+- `src/main.rs`: gate the CPAL imports, `WaveformArg`, the
+  `OutputMode::Cpal` variant, the five cpal-only CLI flags, the
+  cpal arms in `resolve_output`/`warn_unused_flags`/`build_backend`,
+  the `Arc` import, and the `warn` import. New const `OUTPUT_HELP`
+  switches the `--output` help text based on feature state. New
+  startup check that fails loudly if `--output=auto` is used with
+  no device and the cpal feature is off.
+- `src/mml.rs`: replaced top-of-file comment with attribution +
+  license note. Behaviour unchanged.
+- `README.md`: retitled (no longer FreeBSD-only); added Backends
+  paragraph; added Build features section documenting the `cpal`
+  feature and the FreeBSD recommendation; expanded the flag lists
+  with `--output` plus the cpal-only flags as a clearly-marked
+  conditional group.
+
+Not modified:
+- `src/cpal_backend.rs`, `src/freebsd_speaker.rs`,
+  `src/qemu_pcspeaker.md`, `src/fbsd-speaker/spkr.c`,
+  `tests/integration_tests.rs`, `API.md`.
+
+## Verification
+
+- `cargo build` (default features) → clean.
+- `cargo build --no-default-features` → clean (no warnings).
+- `cargo test` (default features) → 14 tests pass (10 mml unit + 4
+  integration).
+- `cargo test --no-default-features` → 14 tests pass.
+- `./spkrd --help` shows the cpal flags; `./spkrd --help` (no
+  default features) hides them and the `--output` possible values
+  list contains only `auto, freebsd-speaker`.
+
+## Current Status
+
+Done. Awaiting the user's call on whether to commit.
+
+## High-Level Decisions
+
+(none yet)
+
+## Files Modified
+
+(none yet — changelog only)
+
+## Current Status
+
+Awaiting user clarification on which direction to take.

changelog/20260502-cpal-backend-iteration.md

@@ -0,0 +1,87 @@
+# CPAL backend cancellation bug — concurrent melodies overlapping
+
+## Task Specification
+
+The user reported that the CPAL backend does not enforce mutual
+exclusion between melodies in the way the FreeBSD `/dev/speaker`
+driver does: when the first HTTP client is interrupted (Ctrl-C
+before its melody finishes), a second client's melody plays in
+parallel with the first instead of waiting.
+
+## Root cause
+
+In the original `play_melody`, the lock was a
+`tokio::sync::Mutex<()>` and the `MutexGuard` was held by the async
+parent future across the `spawn_blocking(...).await`. When the
+client disconnects, axum drops the parent future, which drops the
+guard and releases the lock. But `spawn_blocking` cannot be aborted
+by tokio — the blocking task continues running, owns its own
+`Arc<CpalBackend>` clone, and keeps the live `cpal::Stream` playing
+in CPAL's audio thread. The next request sees the lock free,
+acquires it, builds a *second* `cpal::Stream`, and PulseAudio /
+PipeWire mixes both streams — audible overlap.
+
+Verified via per-event eprintln instrumentation (timestamps showed
+the lock-released event firing before the audio actually stopped
+when the parent was cancelled).
+
+## Decisions
+
+- Fix matches FreeBSD's `spkr.c` behaviour. There the per-tone
+  `tsleep` is invoked with `PCATCH`, so a signal interrupts the
+  in-progress melody and releases the `sx_xlock` mid-string. We
+  reproduce this with an abort flag observed by the audio callback.
+- Lock-follows-the-work: the `play_lock` is now acquired *inside*
+  the `spawn_blocking` task. The lock's lifetime is tied to the
+  blocking task's lifetime, not to the parent future's. If the
+  parent future is dropped, the blocking task continues holding the
+  lock until it finishes naturally (or is cut short by the abort
+  flag), at which point the lock is released and the next request
+  can proceed. This eliminates any window where the parent has
+  released the lock but the audio thread is still playing.
+- Cancellation is propagated via `Arc<AtomicBool>`: an
+  `AbortOnDrop` guard in the async parent sets the flag in its
+  `Drop` impl. The cpal callback observes the flag once per
+  invocation; when set it writes zeros to the output and signals
+  `done`, ending the wait in `run_stream`.
+- `play_lock` switches from `tokio::sync::Mutex<()>` to
+  `std::sync::Mutex<()>` because the lock is now held entirely
+  inside synchronous (blocking) code. Holding a tokio mutex across
+  blocking work is the wrong tool for the job.
+- Cancellation does not surface as an HTTP error: by definition the
+  client has already disconnected, so the response body is
+  irrelevant. The blocking task may complete with `Ok(retries)` or
+  with `SpeakerError::Timeout` if the lock was never acquired
+  within retry_timeout.
+
+## Files Modified
+
+- `src/cpal_backend.rs`:
+  - `play_lock` type: `AsyncMutex<()>` → `std::sync::Mutex<()>`.
+  - `play_melody`: render the buffer in the async parent
+    (synthesis is CPU-only, no need to spawn_blocking it); move
+    the retry-poll lock acquisition into the blocking task; install
+    an `AbortOnDrop` guard in the async parent.
+  - New `AbortOnDrop` struct.
+  - `run_stream` (and `play_buffer`): now take an
+    `Arc<AtomicBool>` abort flag, wire it into the callback. The
+    callback writes silence and signals `done` when the flag is
+    set. The 50 ms tail sleep is skipped on abort to keep
+    cancellation snappy.
+
+## Verification
+
+- `cargo build` (default features) → clean.
+- `cargo build --no-default-features` → clean.
+- `cargo test` and `cargo test --no-default-features` → green.
+- Manual reproduction of the user's scenario: long melody on
+  client 1, Ctrl-C client 1, immediate request from client 2 →
+  should hear client 2 alone (with at most a small audio-system
+  tail bleed, separate issue).
+
+## Current Status
+
+Done. Manual reproduction of the original scenario (long melody on
+client 1, Ctrl-C, immediate request from client 2) is left to the
+user since this requires real audio output that the development
+environment can't validate without disturbing other audio.