Text chat 58: fluxer-audio sound outline, trim to WAV, stopping one clip (#387) #409

Manually merged
charles merged 0 commits from textchat-58-audio-sound-edit into textchat 2026-11-13 04:31:19 +00:00
Owner

What this builds

fluxer-audio

  • edit.rs (new): SoundOutline { duration, channels, peaks } and edit::outline(bytes, content_type, buckets), where each bucket holds the loudest absolute sample of the channel average, from 0 to 1 (based on AudioWaveform.tsx computePeaks). Also edit::trim_to_wav(bytes, content_type, range, mono), which writes RIFF/WAVE PCM 16-bit at 48 kHz. The output is stereo, or one channel when mono is set (the average, as downmixToMono) or when the source is mono (as AudioWavEncode.ts). The range is clamped to the sound, and an empty range returns ClipError::Empty. The WAV header is written by hand, so there is no new dependency.
  • clip.rs: a private decode_capped(bytes, content_type, Option<Duration>) that also returns the source channel count. decode calls it with the 30 s cap. edit calls it with no cap, so a long file is trimmed down instead of refused. The 20 MiB input limit still applies.
  • engine.rs: AudioEngine::stop_clip(tag) stops one clip and reports EngineEvent::ClipFinished for it. Other clips and the chimes keep playing. A tag that is not playing is ignored.
  • README updated.

How it was tested

  • Unit tests (edit.rs): wav_header_is_pcm16_48k, trim_keeps_only_the_range, mono_downmix_averages_the_channels, stereo_is_kept_without_mono, range_is_clamped_to_the_sound, empty_range_is_an_error, long_source_is_trimmed_not_refused, entrance_length_mono_wav_fits_one_mib, outline_has_the_requested_buckets_and_duration, outline_of_garbage_is_an_error, trimmed_wav_decodes_back_to_the_range.
  • tests/clips.rs: stop_clip_stops_only_that_tag (on NullHost).
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci passes locally on Linux, at 4d40f28.

Deviations from the plan

None.

Closes #387

🤖 Generated with Claude Code

## What this builds **fluxer-audio** - `edit.rs` (new): `SoundOutline { duration, channels, peaks }` and `edit::outline(bytes, content_type, buckets)`, where each bucket holds the loudest absolute sample of the channel average, from 0 to 1 (based on `AudioWaveform.tsx` `computePeaks`). Also `edit::trim_to_wav(bytes, content_type, range, mono)`, which writes RIFF/WAVE PCM 16-bit at 48 kHz. The output is stereo, or one channel when `mono` is set (the average, as `downmixToMono`) or when the source is mono (as `AudioWavEncode.ts`). The range is clamped to the sound, and an empty range returns `ClipError::Empty`. The WAV header is written by hand, so there is no new dependency. - `clip.rs`: a private `decode_capped(bytes, content_type, Option<Duration>)` that also returns the source channel count. `decode` calls it with the 30 s cap. `edit` calls it with no cap, so a long file is trimmed down instead of refused. The 20 MiB input limit still applies. - `engine.rs`: `AudioEngine::stop_clip(tag)` stops one clip and reports `EngineEvent::ClipFinished` for it. Other clips and the chimes keep playing. A tag that is not playing is ignored. - README updated. ## How it was tested - Unit tests (`edit.rs`): `wav_header_is_pcm16_48k`, `trim_keeps_only_the_range`, `mono_downmix_averages_the_channels`, `stereo_is_kept_without_mono`, `range_is_clamped_to_the_sound`, `empty_range_is_an_error`, `long_source_is_trimmed_not_refused`, `entrance_length_mono_wav_fits_one_mib`, `outline_has_the_requested_buckets_and_duration`, `outline_of_garbage_is_an_error`, `trimmed_wav_decodes_back_to_the_range`. - `tests/clips.rs`: `stop_clip_stops_only_that_tag` (on `NullHost`). - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` passes locally on Linux, at 4d40f28. ## Deviations from the plan None. Closes #387 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Refs #387

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Author
Owner

Review round 1. What changed for each finding:

  • Blocking: the branch is not on origin and there is no PR. Fixed. I ran FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci to completion on 4d40f28 and every step passed, including package_produces_appimage_on_linux. Then I pushed textchat-58-audio-sound-edit and opened this PR. The code is unchanged.
  • Minor: mono source gives a 1-channel WAV. No code change. This matches the original, AudioWavEncode.ts (sourceChannels === 1), which the plan tells us to follow (encodeAudioBufferSliceToWav). The behaviour is documented in the trim_to_wav doc, the README and the stereo_is_kept_without_mono test. Tasks 59 and 60 only pass the bytes on.
  • Minor: more than 2 channels are averaged as 2; outline uses even buckets. Deferred to follow-up #410. Averaging every channel means changing how clip::decode keeps a source's channels, which is more than a cheap fix.
  • Minor: no frame cap in decode_capped(.., None). Deferred to follow-up #410. The plan specifies no cap, and the original has none, so choosing a sanity cap (such as 10 minutes) needs a decision.

🤖 Generated with Claude Code

Review round 1. What changed for each finding: - **Blocking: the branch is not on origin and there is no PR.** Fixed. I ran `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` to completion on 4d40f28 and every step passed, including `package_produces_appimage_on_linux`. Then I pushed `textchat-58-audio-sound-edit` and opened this PR. The code is unchanged. - **Minor: mono source gives a 1-channel WAV.** No code change. This matches the original, `AudioWavEncode.ts` (`sourceChannels === 1`), which the plan tells us to follow (`encodeAudioBufferSliceToWav`). The behaviour is documented in the `trim_to_wav` doc, the README and the `stereo_is_kept_without_mono` test. Tasks 59 and 60 only pass the bytes on. - **Minor: more than 2 channels are averaged as 2; outline uses even buckets.** Deferred to follow-up #410. Averaging every channel means changing how `clip::decode` keeps a source's channels, which is more than a cheap fix. - **Minor: no frame cap in `decode_capped(.., None)`.** Deferred to follow-up #410. The plan specifies no cap, and the original has none, so choosing a sanity cap (such as 10 minutes) needs a decision. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Author
Owner

Independent review: Text chat 58 (fluxer-audio sound outline, trim to WAV, stopping one clip)

Reviewed cold: git diff 6113a8e..origin/textchat-58-audio-sound-edit (commit 4d40f28).

(1) Tests. All 12 tests the plan names exist and pass. entrance_length_mono_wav_fits_one_mib asserts 44 + 48 000 × 5.2 × 2 bytes, which is < 1 048 576. long_source_is_trimmed_not_refused first shows that clip::decode returns TooLong. trimmed_wav_decodes_back_to_the_range makes the round trip through clip::decode. stop_clip_stops_only_that_tag runs on NullHost and checks that the other tag plays to its end.
(2) Interfaces. These exist exactly as Task 59/61 consume them:

  • edit::SoundOutline { duration, channels, peaks }
  • edit::outline(&[u8], Option<&str>, usize)
  • edit::trim_to_wav(&[u8], Option<&str>, Range<Duration>, bool) -> Result<Vec<u8>, ClipError>
  • ClipError::Empty for an empty or clamped-away range
  • AudioEngine::stop_clip(&self, u64), which emits ClipFinished

clip::decode_capped is a private (pub(crate)) variant with the cap as a parameter, and decode keeps the 30 s cap. The WAV header is written by hand and there is no new dependency. mixer.rs is listed in the plan but did not need a change.
(3) Invariants. The diff only touches fluxer-audio. Nothing is logged or written to disk, no paths, no secrets. Decoding stays inside catch_unwind. No path through frame_at, clamp or the header arithmetic panics: start is at most len, and the sizes saturate.
(4) Review Focus. No item belongs to this task.
(5) Local CI. cargo xtask ci passed every step in the review worktree. The screenshot and livekit steps were skipped because their env vars were not set; this crate has no screenshots. The implementer reports a green run with FLUXER_SCREENSHOT_TESTS=1. I did not check remote CI.

Findings

  • minor: when a source has more than 2 channels, the mono downmix and the outline average only the first two channels. The original averages all of them. This is already tracked in #410.
  • minor: with no duration cap, a very low-bitrate file can decode to gigabytes. The plan asks for no cap and the file is the user's own pick. Tracked in #410.
  • minor: a mono source gives a 1-channel WAV even without mono. This matches AudioWavEncode.ts (sourceChannels === 1), so no change is needed.
  • minor (test strength): stop_clip_stops_only_that_tag starts a chime but never checks that the chime keeps sounding after stop_clip. The code is correct: the worker only matches SourceId::Clip(tag).

Verdict: approve. No blocking findings, and local CI is green.

## Independent review: Text chat 58 (`fluxer-audio` sound outline, trim to WAV, stopping one clip) Reviewed cold: `git diff 6113a8e..origin/textchat-58-audio-sound-edit` (commit 4d40f28). **(1) Tests.** All 12 tests the plan names exist and pass. `entrance_length_mono_wav_fits_one_mib` asserts 44 + 48 000 × 5.2 × 2 bytes, which is < 1 048 576. `long_source_is_trimmed_not_refused` first shows that `clip::decode` returns `TooLong`. `trimmed_wav_decodes_back_to_the_range` makes the round trip through `clip::decode`. `stop_clip_stops_only_that_tag` runs on `NullHost` and checks that the other tag plays to its end. **(2) Interfaces.** These exist exactly as Task 59/61 consume them: - `edit::SoundOutline { duration, channels, peaks }` - `edit::outline(&[u8], Option<&str>, usize)` - `edit::trim_to_wav(&[u8], Option<&str>, Range<Duration>, bool) -> Result<Vec<u8>, ClipError>` - `ClipError::Empty` for an empty or clamped-away range - `AudioEngine::stop_clip(&self, u64)`, which emits `ClipFinished` `clip::decode_capped` is a private (`pub(crate)`) variant with the cap as a parameter, and `decode` keeps the 30 s cap. The WAV header is written by hand and there is no new dependency. `mixer.rs` is listed in the plan but did not need a change. **(3) Invariants.** The diff only touches `fluxer-audio`. Nothing is logged or written to disk, no paths, no secrets. Decoding stays inside `catch_unwind`. No path through `frame_at`, `clamp` or the header arithmetic panics: `start` is at most `len`, and the sizes saturate. **(4) Review Focus.** No item belongs to this task. **(5) Local CI.** `cargo xtask ci` passed every step in the review worktree. The screenshot and livekit steps were skipped because their env vars were not set; this crate has no screenshots. The implementer reports a green run with `FLUXER_SCREENSHOT_TESTS=1`. I did not check remote CI. **Findings** - minor: when a source has more than 2 channels, the mono downmix and the outline average only the first two channels. The original averages all of them. This is already tracked in #410. - minor: with no duration cap, a very low-bitrate file can decode to gigabytes. The plan asks for no cap and the file is the user's own pick. Tracked in #410. - minor: a mono source gives a 1-channel WAV even without `mono`. This matches `AudioWavEncode.ts` (`sourceChannels === 1`), so no change is needed. - minor (test strength): `stop_clip_stops_only_that_tag` starts a chime but never checks that the chime keeps sounding after `stop_clip`. The code is correct: the worker only matches `SourceId::Clip(tag)`. **Verdict: approve.** No blocking findings, and local CI is green.
charles manually merged commit 67da1c73b3 into textchat 2026-11-13 04:31:19 +00:00
Sign in to join this conversation.
No description provided.