Voice 5: fluxer-audio clips and chimes (#66) #118

Manually merged
charles merged 0 commits from voice-5-audio-clips-chimes into voice 2026-11-11 21:03:42 +00:00
Owner

What this adds

fluxer-audio can now play short sounds into the mixer (Voice spec §6 "Clips", §5.2 "Chimes").

  • clip: clip::decode(bytes, content_type) -> Result<Clip, ClipError> decodes mp3, ogg/vorbis, m4a/aac and wav with symphonia 0.6 into 48 kHz stereo. Files over 20 MiB are refused before decoding and decoding stops once a sound passes 30 s. The content type is only a hint. A decoder panic on server data is caught and becomes ClipError::Malformed. ClipCache::new(32) is an LRU keyed by string.
  • chime: Chime::{UserJoin, UserLeave, Mute, Unmute, Deafen, Undeafen, VoiceDisconnect, ViewerJoin, ViewerLeave, IncomingCall}, with the ten mp3 files copied unchanged from the fork's fluxer_app/src/media/sounds/ into assets/sounds/ (AGPL-3.0-or-later note in the crate README). Each is decoded once, outside the LRU.
  • engine: AudioEngine::play_clip(key, bytes: Option<Bytes>, gain, tag) -> Result<Duration, ClipError>, play_chime(Chime, gain), stop_clips(), and EngineEvent::ClipFinished { tag }. Decoding runs on the caller's thread; the worker feeds each clip to the mixer 10 ms at a time as its own source, so clips, chimes and voices overlap and share the soft clipper.

How it was tested

crates/fluxer-audio/tests/clips.rs, all on NullHost:

  • the five tests the plan names: decodes_mp3_ogg_m4a_wav_fixtures_to_48k_stereo (duration, pitch, level, both channels; also with no, parameterised and wrong content types), rejects_overlong_clip (31 s, over 20 MiB, non-audio, truncated, header-only), cache_evicts_least_recently_used_at_33, play_clip_mixes_into_output_and_reports_finished (mixed with a remote voice, level and audible duration checked, replay from cache, NotCached), every_chime_asset_decodes;
  • five more for behaviour the plan leaves open: a clip shorter than the mixer's prefill still plays and finishes, stop_clips, replaying a tag, no output device, chimes report no ClipFinished.

The fixtures in tests/fixtures/ are 0.5 s 440 Hz tones generated with ffmpeg. FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci passes locally (clippy, cargo deny, all tests).

Deviations from the plan, and decisions it leaves open

  • Outside the Files list: mixer.rs gains SourceId::Chime(u64) (chimes have no caller tag, so they cannot share Clip(tag)) and Mixer::forget (drops a finished clip's gain, which remove keeps on purpose for participants). .gitattributes marks *.mp3 *.ogg *.m4a *.wav as binary. bytes becomes a dependency of fluxer-audio because the interface takes Bytes; it was already a workspace dependency.
  • play_chime returns Result<Duration, ClipError>; the plan gives no return type.
  • AudioEngine::has_clip(key) is an addition, so the runtime can check the cache without playing.
  • ClipFinished is also sent for clips cut by stop_clips, and at once when no output device can be opened, so a caller waiting on a tag always gets its event. Replaying a tag that is still playing replaces the clip and reports once.
  • stop_clips does not stop chimes, so the disconnect chime survives the soundboard being stopped.
  • With bytes given for a key that is already cached, the cached clip is used and the bytes are ignored.
  • symphonia is built without its ID3 metadata features; an mp3 with ID3v2 and ID3v1 tags was checked by hand and decodes.
  • Chime::IncomingCall plays one 4.5 s ring; repeating it is left to the caller (Voice 22).
  • ogg/opus is not decoded (symphonia has no Opus decoder); the plan names ogg/vorbis only.

Stacked on: voice-4-audio-devices-mixer

Closes #66

🤖 Generated with Claude Code

## What this adds `fluxer-audio` can now play short sounds into the mixer (Voice spec §6 "Clips", §5.2 "Chimes"). - **`clip`**: `clip::decode(bytes, content_type) -> Result<Clip, ClipError>` decodes mp3, ogg/vorbis, m4a/aac and wav with `symphonia` 0.6 into 48 kHz stereo. Files over 20 MiB are refused before decoding and decoding stops once a sound passes 30 s. The content type is only a hint. A decoder panic on server data is caught and becomes `ClipError::Malformed`. `ClipCache::new(32)` is an LRU keyed by string. - **`chime`**: `Chime::{UserJoin, UserLeave, Mute, Unmute, Deafen, Undeafen, VoiceDisconnect, ViewerJoin, ViewerLeave, IncomingCall}`, with the ten mp3 files copied unchanged from the fork's `fluxer_app/src/media/sounds/` into `assets/sounds/` (AGPL-3.0-or-later note in the crate README). Each is decoded once, outside the LRU. - **`engine`**: `AudioEngine::play_clip(key, bytes: Option<Bytes>, gain, tag) -> Result<Duration, ClipError>`, `play_chime(Chime, gain)`, `stop_clips()`, and `EngineEvent::ClipFinished { tag }`. Decoding runs on the caller's thread; the worker feeds each clip to the mixer 10 ms at a time as its own source, so clips, chimes and voices overlap and share the soft clipper. ## How it was tested `crates/fluxer-audio/tests/clips.rs`, all on `NullHost`: - the five tests the plan names: `decodes_mp3_ogg_m4a_wav_fixtures_to_48k_stereo` (duration, pitch, level, both channels; also with no, parameterised and wrong content types), `rejects_overlong_clip` (31 s, over 20 MiB, non-audio, truncated, header-only), `cache_evicts_least_recently_used_at_33`, `play_clip_mixes_into_output_and_reports_finished` (mixed with a remote voice, level and audible duration checked, replay from cache, `NotCached`), `every_chime_asset_decodes`; - five more for behaviour the plan leaves open: a clip shorter than the mixer's prefill still plays and finishes, `stop_clips`, replaying a tag, no output device, chimes report no `ClipFinished`. The fixtures in `tests/fixtures/` are 0.5 s 440 Hz tones generated with ffmpeg. `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` passes locally (clippy, cargo deny, all tests). ## Deviations from the plan, and decisions it leaves open - **Outside the Files list:** `mixer.rs` gains `SourceId::Chime(u64)` (chimes have no caller tag, so they cannot share `Clip(tag)`) and `Mixer::forget` (drops a finished clip's gain, which `remove` keeps on purpose for participants). `.gitattributes` marks `*.mp3 *.ogg *.m4a *.wav` as binary. `bytes` becomes a dependency of `fluxer-audio` because the interface takes `Bytes`; it was already a workspace dependency. - `play_chime` returns `Result<Duration, ClipError>`; the plan gives no return type. - `AudioEngine::has_clip(key)` is an addition, so the runtime can check the cache without playing. - `ClipFinished` is also sent for clips cut by `stop_clips`, and at once when no output device can be opened, so a caller waiting on a tag always gets its event. Replaying a tag that is still playing replaces the clip and reports once. - `stop_clips` does not stop chimes, so the disconnect chime survives the soundboard being stopped. - With bytes given for a key that is already cached, the cached clip is used and the bytes are ignored. - `symphonia` is built without its ID3 metadata features; an mp3 with ID3v2 and ID3v1 tags was checked by hand and decodes. - `Chime::IncomingCall` plays one 4.5 s ring; repeating it is left to the caller (Voice 22). - ogg/opus is not decoded (symphonia has no Opus decoder); the plan names ogg/vorbis only. Stacked on: voice-4-audio-devices-mixer Closes #66 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(audio): device hosts, capture and playback mixer
Some checks failed
ci / Linux (x86_64) (push) Successful in 7m31s
ci / Windows (x64) (push) Successful in 8m39s
ci / Linux (x86_64) (pull_request) Successful in 7m25s
ci / Windows (x64) (pull_request) Has been cancelled
0743d38035
Refs #65

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Merge remote-tracking branch 'origin/voice' into voice/4-audio-devices-mixer
All checks were successful
ci / Linux (x86_64) (push) Successful in 8m2s
ci / Linux (x86_64) (pull_request) Successful in 7m39s
ci / Windows (x64) (push) Successful in 8m29s
ci / Windows (x64) (pull_request) Successful in 8m45s
8843c4cd42
feat(audio): clip decoding, cache and chimes
Some checks failed
ci / Linux (x86_64) (push) Has been cancelled
ci / Windows (x64) (push) Has been cancelled
e0757c69fd
Refs #66

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Author
Owner

Independent review: Voice 5 (audio clips and chimes), commit e0757c6

Verdict: changes requested (1 blocking, 4 minor). Local FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci on the review worktree: all steps passed. Remote runners not checked.

Blocking

B1. A sound file with an unusual sample rate hangs or aborts the client (clip.rs, decode_inner). The file's sample rate goes straight into Resampler::new(rate, 48_000, 2). The FFT resampler sizes its buffers from the two rates divided by their gcd, so a rate that shares no factor with 48 000 costs time and memory proportional to the rate itself. Measured with a 4 KB 8-bit mono WAV whose header states the rate (debug build, 8 GB address-space cap):

header rate result
191 999 Hz 0.26 s
1 000 003 Hz 1.4 s
48 000 001 Hz 54 s on the calling thread
200 000 003 Hz memory allocation of 408146688 bytes failed, SIGABRT
4 000 000 007 Hz memory allocation of 16000000028 bytes failed, SIGABRT

An allocation failure is an abort, which the catch_unwind does not catch. The server would accept such a file: SoundboardService.ts stores the uploaded bytes and checks only size (20 MiB) and duration (100 ms to 30 s), and 100 ms of 8-bit mono at 200 MHz is 20 MB. So any member who may upload a sound can take down every native client that plays it, which breaks "server data must never panic the client". Suggested fix: refuse rates outside a sane range (for example 8 kHz to 192 kHz) with ClipError::Unsupported before building the resampler, with a test.

Minor

M1. Short or odd-rate clips can decode to an empty or truncated Clip and still return Ok. Same probe: 4000 frames at 44 101 Hz gave Ok with 0 frames, 60 000 frames (1.36 s) gave 24 000 frames (0.5 s). Standard rates are fine (44.1 k, 22.05 k, 11.025 k, 8 k checked, down to 3 frames). The truncation comes from the Voice 3 resampler's flush round bound, not this PR, but decode should return ClipError::Empty when the resampled clip is empty. The range check of B1 does not remove this; rejecting rates whose gcd with 48 000 is small would.

M2. Padding in finish_played_clips with a large device period. Confirmed as the implementer described: the engine sets the prefill to the device period rounded up plus 10 ms (capped at 120 ms), so with a period above about 100 ms a clip shorter than the prefill is padded past MAX_QUEUE_MS and loses up to its first 10 ms. Only clips shorter than 120 ms are affected; every chime is longer than 300 ms. No clip is lost and ClipFinished is still sent.

M3. Cache memory. 32 clips of up to 30 s are about 5.8 MB each decoded, so about 184 MB worst case. That is what the spec asks for (LRU of 32); worth a byte budget later.

M4. play_clip ignores bytes for a cached key. Fine while a sound's audio never changes under one id; the caller must use a new key if that ever changes. Documented in the rustdoc.

Checked and fine

  • Tests: the five the plan names exist in tests/clips.rs and assert the plan's values: all four fixtures to 48 kHz stereo (pitch, level, both channels), 31 s refused and 29 s accepted, 20 MiB + 1 refused, eviction at the 33rd insert with LRU order, clip mixed with a remote voice and exactly one ClipFinished, all 10 chimes decode. All run on NullHost.
  • Interfaces: clip::decode(&[u8], Option<&str>) -> Result<Clip, ClipError>, ClipCache::new(32), the ten Chime variants, play_clip(&str, Option<Bytes>, f32, u64) -> Result<Duration, ClipError>, play_chime(Chime, f32), stop_clips(), EngineEvent::ClipFinished { tag: u64 } all exist as written.
  • Constraints: fluxer-audio depends on neither fluxer-core nor LiveKit; decoding and the cache lock are on the caller's thread, the device callbacks are untouched; no secrets in code or fixtures; symphonia is the crate the plan names, bytes was already a workspace dependency.
  • The ten mp3 files are byte-identical to fluxer_app/src/media/sounds/ in the fork; the AGPL note is in the README.
  • No Review Focus item belongs to this task.
## Independent review: Voice 5 (audio clips and chimes), commit e0757c6 **Verdict: changes requested (1 blocking, 4 minor).** Local `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` on the review worktree: all steps passed. Remote runners not checked. ### Blocking **B1. A sound file with an unusual sample rate hangs or aborts the client (`clip.rs`, `decode_inner`).** The file's sample rate goes straight into `Resampler::new(rate, 48_000, 2)`. The FFT resampler sizes its buffers from the two rates divided by their gcd, so a rate that shares no factor with 48 000 costs time and memory proportional to the rate itself. Measured with a 4 KB 8-bit mono WAV whose header states the rate (debug build, 8 GB address-space cap): | header rate | result | |---|---| | 191 999 Hz | 0.26 s | | 1 000 003 Hz | 1.4 s | | 48 000 001 Hz | 54 s on the calling thread | | 200 000 003 Hz | `memory allocation of 408146688 bytes failed`, SIGABRT | | 4 000 000 007 Hz | `memory allocation of 16000000028 bytes failed`, SIGABRT | An allocation failure is an abort, which the `catch_unwind` does not catch. The server would accept such a file: `SoundboardService.ts` stores the uploaded bytes and checks only size (20 MiB) and duration (100 ms to 30 s), and 100 ms of 8-bit mono at 200 MHz is 20 MB. So any member who may upload a sound can take down every native client that plays it, which breaks "server data must never panic the client". Suggested fix: refuse rates outside a sane range (for example 8 kHz to 192 kHz) with `ClipError::Unsupported` before building the resampler, with a test. ### Minor **M1. Short or odd-rate clips can decode to an empty or truncated `Clip` and still return `Ok`.** Same probe: 4000 frames at 44 101 Hz gave `Ok` with 0 frames, 60 000 frames (1.36 s) gave 24 000 frames (0.5 s). Standard rates are fine (44.1 k, 22.05 k, 11.025 k, 8 k checked, down to 3 frames). The truncation comes from the Voice 3 resampler's `flush` round bound, not this PR, but `decode` should return `ClipError::Empty` when the resampled clip is empty. The range check of B1 does not remove this; rejecting rates whose gcd with 48 000 is small would. **M2. Padding in `finish_played_clips` with a large device period.** Confirmed as the implementer described: the engine sets the prefill to the device period rounded up plus 10 ms (capped at 120 ms), so with a period above about 100 ms a clip shorter than the prefill is padded past `MAX_QUEUE_MS` and loses up to its first 10 ms. Only clips shorter than 120 ms are affected; every chime is longer than 300 ms. No clip is lost and `ClipFinished` is still sent. **M3. Cache memory.** 32 clips of up to 30 s are about 5.8 MB each decoded, so about 184 MB worst case. That is what the spec asks for (LRU of 32); worth a byte budget later. **M4. `play_clip` ignores `bytes` for a cached key.** Fine while a sound's audio never changes under one id; the caller must use a new key if that ever changes. Documented in the rustdoc. ### Checked and fine - Tests: the five the plan names exist in `tests/clips.rs` and assert the plan's values: all four fixtures to 48 kHz stereo (pitch, level, both channels), 31 s refused and 29 s accepted, 20 MiB + 1 refused, eviction at the 33rd insert with LRU order, clip mixed with a remote voice and exactly one `ClipFinished`, all 10 chimes decode. All run on `NullHost`. - Interfaces: `clip::decode(&[u8], Option<&str>) -> Result<Clip, ClipError>`, `ClipCache::new(32)`, the ten `Chime` variants, `play_clip(&str, Option<Bytes>, f32, u64) -> Result<Duration, ClipError>`, `play_chime(Chime, f32)`, `stop_clips()`, `EngineEvent::ClipFinished { tag: u64 }` all exist as written. - Constraints: `fluxer-audio` depends on neither `fluxer-core` nor LiveKit; decoding and the cache lock are on the caller's thread, the device callbacks are untouched; no secrets in code or fixtures; `symphonia` is the crate the plan names, `bytes` was already a workspace dependency. - The ten mp3 files are byte-identical to `fluxer_app/src/media/sounds/` in the fork; the AGPL note is in the README. - No Review Focus item belongs to this task.
fix(audio): refuse absurd clip sample rates, keep odd-rate and short clips whole
All checks were successful
ci / Linux (x86_64) (push) Successful in 8m19s
ci / Windows (x64) (push) Successful in 7m43s
313e865d97
- clip::decode refuses sample rates outside 8 kHz to 192 kHz with
  ClipError::Unsupported before anything is sized by the rate: a 4 KB WAV
  whose header claims 48 000 001 Hz or more stalled or aborted the client.
- Resampler::flush sizes its round bound from the filter's block, so rates
  that share no factor with 48 kHz (block of a whole second) are no longer
  cut short or emptied; decode returns ClipError::Empty rather than an
  empty clip.
- The engine fills a clip's last frame up to 10 ms and never pads a queue
  past MAX_QUEUE_MS, so a clip shorter than the prefill of a long-period
  device keeps its beginning.

Refs #66

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Author
Owner

Review round 1, fixed in 313e865 (local FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci green).

Blocking: unchecked sample rate in decode_inner — fixed. clip::decode now refuses rates outside MIN_CLIP_RATE..=MAX_CLIP_RATE (8 kHz to 192 kHz) with ClipError::Unsupported at the first decoded packet, before anything is sized by the rate and before the resampler is built. Test refuses_sample_rates_outside_8_to_192_khz: 7 999, 192 001, 48 000 001, 200 000 003, 4 000 000 007, 1 and u32::MAX Hz are each refused in under a second; 8 000 and 192 000 Hz decode. Residual cost inside the range: a rate sharing no factor with 48 kHz still makes the resampler work in one-second blocks; the worst case I measured is a 29 s mono clip at 191 999 Hz, 8.9 s in a debug build on the calling thread (bounded, no crash; release not measured). Recorded in #119.

Minor: odd-rate clips empty or truncated — fixed. Cause: the FFT resampler takes about 10 ms per call but emits nothing until a block of from_hz / gcd frames is full (one second at 44 101 Hz, plus half a block of delay), and Resampler::flush gave up after 64 rounds. The bound is now computed from the block size and the output still owed (flush_rounds); standard rates behave as before. decode also returns ClipError::Empty instead of Ok with an empty clip. Test odd_sample_rates_keep_their_whole_duration (44 101, 11 027, 191 999, 47 999 Hz: duration within 1 ms, level at the end, pitch). This touches resample.rs from Voice 3, same crate.

Minor: finish_played_clips padding past MAX_QUEUE_MS — fixed. feed_clips fills a clip's last frame up to a whole 10 ms, so the queue holds whole frames and the padding lands exactly on the prefill; the padding is also skipped when it would exceed MAX_QUEUE_MS. Test a_short_clip_is_played_whole_on_a_device_with_a_long_period uses a test host with a 110 ms period (it reproduced the loss: a 115 ms clip was heard for 110 ms) and checks 115, 95 and 25 ms clips sample for sample, with ClipFinished.

Minor: cache can hold about 184 MB — not changed (matches the spec's LRU of 32). Follow-up: #119.

Minor: play_clip ignores bytes for a cached key — behaviour not changed; the rustdoc now says a sound whose audio changes needs a new key. Follow-up for the callers: #119.

Review round 1, fixed in 313e865 (local `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` green). **Blocking: unchecked sample rate in `decode_inner`** — fixed. `clip::decode` now refuses rates outside `MIN_CLIP_RATE..=MAX_CLIP_RATE` (8 kHz to 192 kHz) with `ClipError::Unsupported` at the first decoded packet, before anything is sized by the rate and before the resampler is built. Test `refuses_sample_rates_outside_8_to_192_khz`: 7 999, 192 001, 48 000 001, 200 000 003, 4 000 000 007, 1 and `u32::MAX` Hz are each refused in under a second; 8 000 and 192 000 Hz decode. Residual cost inside the range: a rate sharing no factor with 48 kHz still makes the resampler work in one-second blocks; the worst case I measured is a 29 s mono clip at 191 999 Hz, 8.9 s in a debug build on the calling thread (bounded, no crash; release not measured). Recorded in #119. **Minor: odd-rate clips empty or truncated** — fixed. Cause: the FFT resampler takes about 10 ms per call but emits nothing until a block of `from_hz / gcd` frames is full (one second at 44 101 Hz, plus half a block of delay), and `Resampler::flush` gave up after 64 rounds. The bound is now computed from the block size and the output still owed (`flush_rounds`); standard rates behave as before. `decode` also returns `ClipError::Empty` instead of `Ok` with an empty clip. Test `odd_sample_rates_keep_their_whole_duration` (44 101, 11 027, 191 999, 47 999 Hz: duration within 1 ms, level at the end, pitch). This touches `resample.rs` from Voice 3, same crate. **Minor: `finish_played_clips` padding past `MAX_QUEUE_MS`** — fixed. `feed_clips` fills a clip's last frame up to a whole 10 ms, so the queue holds whole frames and the padding lands exactly on the prefill; the padding is also skipped when it would exceed `MAX_QUEUE_MS`. Test `a_short_clip_is_played_whole_on_a_device_with_a_long_period` uses a test host with a 110 ms period (it reproduced the loss: a 115 ms clip was heard for 110 ms) and checks 115, 95 and 25 ms clips sample for sample, with `ClipFinished`. **Minor: cache can hold about 184 MB** — not changed (matches the spec's LRU of 32). Follow-up: #119. **Minor: `play_clip` ignores bytes for a cached key** — behaviour not changed; the rustdoc now says a sound whose audio changes needs a new key. Follow-up for the callers: #119.
Author
Owner

Independent review, round 2 — Voice 5 (clips and chimes) at 313e865

Scope: git diff 65cd5a3..313e865. Read cold; implementer's notes verified, not trusted.

Verdict: APPROVE — 0 blocking, 3 minor. Local FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci is green (all steps passed); remote runners not checked.

Checks

  1. Plan tests — all five exist in crates/fluxer-audio/tests/clips.rs and assert what the plan says: decodes_mp3_ogg_m4a_wav_fixtures_to_48k_stereo (four fixtures, duration, pitch, level, both channels), rejects_overlong_clip (31 s refused, 29 s accepted, 20 MiB + 1 refused), cache_evicts_least_recently_used_at_33 (ClipCache::new(32), the 33rd insert evicts the least recently used, get counts as a use), play_clip_mixes_into_output_and_reports_finished (mixed with a remote voice, exactly one ClipFinished, cached replay without bytes), every_chime_asset_decodes (all 10). Eight further tests cover the round 1 fixes. The clips test binary passed 15 runs in a row.
  2. Interfaces — clip::decode(&[u8], Option<&str>) -> Result<Clip, ClipError>, ClipCache::new(32) keyed by string, the ten Chime variants, AudioEngine::play_clip(&str, Option<Bytes>, f32, u64) -> Result<Duration, ClipError>, play_chime(Chime, f32), stop_clips() and EngineEvent::ClipFinished { tag } all exist as written. Additions beyond the plan (has_clip, SourceId::Chime, Mixer::forget, play_chime returning the duration) are additive.
  3. Invariants — fluxer-audio gains only symphonia (named by the task) and bytes (already in the workspace, required by the signature); no fluxer-core or LiveKit dependency. Device callbacks are untouched; the new Mutex<ClipCache> is locked only on the caller's thread. No secrets: fixtures carry only ffmpeg/LAME encoder tags. The ten chime files are byte-identical to the fork's fluxer_app/src/media/sounds/, and the README has the licence note. Commits carry Refs #66 and the attribution line.
  4. Review Focus — no item belongs to this task (item 5's cap of 3 is Voice 10; the engine applies the gain it is given).
  5. Round 1 fixes verified — rates outside 8 kHz to 192 kHz are refused at the first packet; odd rates keep their whole duration; a clip shorter than the prefill plays whole on a 110 ms period device. My own probe (not committed): WAV headers with 0/32/255/65535 channels and 0/4/64 bits, 900 random corruptions of the mp3/ogg/m4a fixtures, exactly 30 s, five overlapping clips: no panic escaped, each clip finished exactly once.

Findings

  • minor — crates/fluxer-audio/src/clip.rs: the catch_unwind in decode is load-bearing, not only defensive, and no test exercises it. A 44-byte-header WAV claiming 65535 channels makes symphonia-format-riff 0.6.1 panic (wave/chunks.rs:100, "attempt to multiply with overflow") in a debug build; decode turns it into ClipError::Malformed("the decoder gave up"). A regression test with that file would catch a later panic = "abort" profile or a refactor that drops the guard. The default panic hook still prints the message to stderr, which is harmless here.
  • minor — crates/fluxer-audio/src/engine.rs (play_clip): decoding runs on the calling thread and, inside the accepted range, a rate sharing no factor with 48 kHz resamples in one-second blocks (the implementer measured 8.9 s for a 29 s clip at 191999 Hz in a debug build). Any member can upload such a file, so Voice 14 must call play_clip off the UI thread. Already recorded in #119; noting it so the integrator carries it to Voice 14.
  • minor — crates/fluxer-audio/src/engine.rs (tick): when no output device can be opened, chimes are dropped silently and clips report ClipFinished at once, although play_clip returned the full duration. Core's "speaking for the clip duration + 80 ms" (spec §5.2) should therefore key on ClipFinished, not only on the returned duration. Documented in the rustdoc and README; no code change needed here.

Not findings: the cache is bounded by count, not bytes (matches the spec; in #119), and play_clip ignores bytes for a cached key (documented; in #119).

## Independent review, round 2 — Voice 5 (clips and chimes) at 313e865 Scope: `git diff 65cd5a3..313e865`. Read cold; implementer's notes verified, not trusted. **Verdict: APPROVE — 0 blocking, 3 minor. Local `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` is green (all steps passed); remote runners not checked.** ### Checks 1. **Plan tests** — all five exist in `crates/fluxer-audio/tests/clips.rs` and assert what the plan says: `decodes_mp3_ogg_m4a_wav_fixtures_to_48k_stereo` (four fixtures, duration, pitch, level, both channels), `rejects_overlong_clip` (31 s refused, 29 s accepted, 20 MiB + 1 refused), `cache_evicts_least_recently_used_at_33` (`ClipCache::new(32)`, the 33rd insert evicts the least recently used, `get` counts as a use), `play_clip_mixes_into_output_and_reports_finished` (mixed with a remote voice, exactly one `ClipFinished`, cached replay without bytes), `every_chime_asset_decodes` (all 10). Eight further tests cover the round 1 fixes. The clips test binary passed 15 runs in a row. 2. **Interfaces** — `clip::decode(&[u8], Option<&str>) -> Result<Clip, ClipError>`, `ClipCache::new(32)` keyed by string, the ten `Chime` variants, `AudioEngine::play_clip(&str, Option<Bytes>, f32, u64) -> Result<Duration, ClipError>`, `play_chime(Chime, f32)`, `stop_clips()` and `EngineEvent::ClipFinished { tag }` all exist as written. Additions beyond the plan (`has_clip`, `SourceId::Chime`, `Mixer::forget`, `play_chime` returning the duration) are additive. 3. **Invariants** — `fluxer-audio` gains only `symphonia` (named by the task) and `bytes` (already in the workspace, required by the signature); no `fluxer-core` or LiveKit dependency. Device callbacks are untouched; the new `Mutex<ClipCache>` is locked only on the caller's thread. No secrets: fixtures carry only ffmpeg/LAME encoder tags. The ten chime files are byte-identical to the fork's `fluxer_app/src/media/sounds/`, and the README has the licence note. Commits carry `Refs #66` and the attribution line. 4. **Review Focus** — no item belongs to this task (item 5's cap of 3 is Voice 10; the engine applies the gain it is given). 5. **Round 1 fixes verified** — rates outside 8 kHz to 192 kHz are refused at the first packet; odd rates keep their whole duration; a clip shorter than the prefill plays whole on a 110 ms period device. My own probe (not committed): WAV headers with 0/32/255/65535 channels and 0/4/64 bits, 900 random corruptions of the mp3/ogg/m4a fixtures, exactly 30 s, five overlapping clips: no panic escaped, each clip finished exactly once. ### Findings - **minor** — `crates/fluxer-audio/src/clip.rs`: the `catch_unwind` in `decode` is load-bearing, not only defensive, and no test exercises it. A 44-byte-header WAV claiming 65535 channels makes `symphonia-format-riff` 0.6.1 panic (`wave/chunks.rs:100`, "attempt to multiply with overflow") in a debug build; `decode` turns it into `ClipError::Malformed("the decoder gave up")`. A regression test with that file would catch a later `panic = "abort"` profile or a refactor that drops the guard. The default panic hook still prints the message to stderr, which is harmless here. - **minor** — `crates/fluxer-audio/src/engine.rs` (`play_clip`): decoding runs on the calling thread and, inside the accepted range, a rate sharing no factor with 48 kHz resamples in one-second blocks (the implementer measured 8.9 s for a 29 s clip at 191999 Hz in a debug build). Any member can upload such a file, so Voice 14 must call `play_clip` off the UI thread. Already recorded in #119; noting it so the integrator carries it to Voice 14. - **minor** — `crates/fluxer-audio/src/engine.rs` (`tick`): when no output device can be opened, chimes are dropped silently and clips report `ClipFinished` at once, although `play_clip` returned the full duration. Core's "speaking for the clip duration + 80 ms" (spec §5.2) should therefore key on `ClipFinished`, not only on the returned duration. Documented in the rustdoc and README; no code change needed here. Not findings: the cache is bounded by count, not bytes (matches the spec; in #119), and `play_clip` ignores bytes for a cached key (documented; in #119).
charles manually merged commit fb05a010cb into voice 2026-11-11 21:03:42 +00:00
Sign in to join this conversation.
No description provided.