chore: simplify and clarify audio, core, and container nodes

[staging-devin-ai-integration]

Summary

Pre-release cleanup pass across 27 files in crates/nodes/src/audio/, crates/nodes/src/core/, and crates/nodes/src/containers/, plus root-level utility files (lib.rs, codec_utils.rs, streaming_utils.rs, test_utils.rs).

Net change: −772 lines (77 insertions, 849 deletions) — all comment removals/edits, no behavioral changes.

What was removed

• Explanatory restatements that echo what code already says (e.g. "Create channels", "Get codec parameters", "Send packet", "Decode the packet")
• Implementation notes from previous AI iterations explaining why a previous approach was wrong
• Section label comments (// --- Register X ---, // Stats tracking, // Declare the submodules, etc.)
• Structural dividers within functions that just narrate control flow
• Dead code (decode_mp3_streaming — explicitly marked as legacy/unused with #[allow(dead_code)])
• Commented-out debug tracing code (ogg.rs)

What was kept

• All SPDX license headers
• Lint suppression rationale comments per AGENTS.md linting discipline
• Codec-domain documentation — VP9 keyframe parsing, AV1 codec private layout, Opus granule position (48 kHz per RFC 7845), Symphonia probe false-positive avoidance, H.264 Annex B → AVCC conversion
• Buffer management trade-off comments — SharedPacketBuffer vs FileBackedBuffer, streaming vs file mode
• Timing/sync constraint comments — per-track rebase offsets, monotonicity enforcement, compositor calibration resets, WebM timecode resolution
• Non-obvious control flow comments — deadlock-avoidance in input_done select! branches, jitter buffer timeout sync in mixer

Files changed (27)

Audio (8 files): codecs/{flac,mp3,opus,mod}.rs, filters/{gain,mixer,resampler}.rs, pacer.rs
Core (11 files): {passthrough,pacer,file_read,file_write,bytes_input,bytes_output,json_serialize,telemetry_tap,text_chunker,mod}.rs
Containers (5 files): {mod,wav,ogg,webm,mp4,tests}.rs
Root-level (3 files): lib.rs, streaming_utils.rs, test_utils.rs

No functionality changes. No bugs found.

Review & Testing Checklist for Human

• Spot-check a few files to confirm no domain-critical comments were removed (recommended: ogg.rs stage_frame/granule comments, webm.rs rebase-reset logic, mixer.rs jitter buffer comments)
• Verify just test passes (479 nodes tests pass; plugin_integration_test failures are pre-existing and unrelated)

Notes

• The plugin_integration_test suite (8 failures in streamkit-server) fails on the base branch as well — not related to this change.
• mp4.rs and webm.rs have extensive codec-domain documentation that was intentionally preserved. Only clearly redundant structural/inline comments were removed from those files.
• containers/tests.rs was left mostly untouched since test comments aid readability.

Link to Devin session: https://staging.itsdev.in/sessions/25d0ff011ddd4978b0673f2fe7442ed0
Requested by: @streamer45

---

Devin Review

Status	Commit
🟢 Reviewed	3ebb58d

[staging-devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[staging-devin-ai-integration]

Devin Review found 8 potential issues.

Debug

Playground

[staging-devin-ai-integration]

📝 Info: Dead code removal of decode_mp3_streaming is safe

The PR removes the decode_mp3_streaming function from crates/nodes/src/audio/codecs/mp3.rs (previously around lines 400-563 on the LEFT side). This function was annotated with #[allow(dead_code)] and its doc comment explicitly stated "Legacy decode function (kept for reference, not used)". The removal also correctly removes the now-unused use std::io::Cursor import at the former line 11. No callers exist in the codebase for this function, so the removal is safe and reduces maintenance burden.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

Debug

Playground

[staging-devin-ai-integration]

Devin Review found 2 new potential issues.

Debug

Playground

[staging-devin-ai-integration]

📝 Info: Some pre-existing #[allow] directives lack rationale comments

AGENTS.md requires lint suppressions to include a comment explaining the rationale. Several pre-existing #[allow] directives in files touched by this PR lack rationale — e.g. #[allow(clippy::too_many_lines)] at crates/nodes/src/audio/filters/mixer.rs:215 and #[allow(clippy::needless_range_loop)] at line 979. These were not introduced or modified by this PR (verified via git show on the parent commit), so they are pre-existing debt rather than a violation introduced here. The PR did correctly preserve rationale on all suppressions it touched (reformatting some from above-line to inline).

(Refers to line 215)

---

Was this helpful? React with 👍 or 👎 to provide feedback.

Debug

Playground

[staging-devin-ai-integration]

Confirmed — these are pre-existing and not introduced by this PR. Fixing pre-existing lint rationale gaps is out of scope here but could be addressed in a follow-up.

[staging-devin-ai-integration]

📝 Info: Removed doc comments on internal functions are acceptable

Several /// doc comments were removed from non-public functions (e.g. decode_flac_streaming_incremental, decode_mp3_streaming_incremental, demux_wav_streaming_incremental). CONTRIBUTING.md requires "doc comments for public APIs" but these are all fn (not pub fn), so removing the doc comments does not violate the rule. The #[allow(clippy::cognitive_complexity)] annotations on these functions still retain their inline rationale comments.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

Debug

Playground

[staging-devin-ai-integration]

Correct — these are all crate-internal functions, so the /// doc comments were removed intentionally as redundant.