Skip to content

refactor!: smaller codebase, stats cut to what diagnosed real issues - #35

Merged
datagutt merged 28 commits into
masterfrom
refactor/lean
Oct 2, 2026
Merged

datagutt merged 28 commits into
masterfrom
refactor/lean

Conversation

@datagutt

@datagutt datagutt commented Oct 2, 2026 •

Copy link
Copy Markdown
Member

Why

The codebase carried a lot of weight from the port: functions nothing called, generality in obs and ffmpeg no other plugin uses, 30 stats of which most never helped diagnose anything, comments that described the 1.x C plugin, and a 274 line CLAUDE.md that every agent session had to load. This PR removes that weight without changing settings, stat names that remain, or media controls.

What changed

  • Dead code removed across the workspace, and obs and ffmpeg trimmed to what the plugin calls. The obs-sys ABI mirrors stay complete, since layout-test checks them.
  • Duplicated helpers merged: PCM byte helpers, the rate limit for warnings, state constructors, the hot config store, the NS_TIME_BASE constant. The PacedFrame trait is gone.
  • Fixes: the low latency clock suspend now reads the pump's injected clock, two hardcoded thresholds moved into irl_core::consts, and AudioBuffer::new no longer returns an Option that could never be None.
  • Breaking: the stats surface is cut from 30 fields to the 11 that diagnosed real issues in issues and commits. The stats log line keeps its evidenced keys and gains ll= and ctrl=off. README, irl-stats.lua and the bug template are updated.
  • Tests share fixtures through crates/irl-source/tests/common/, repeated cases are table driven, and the constants test pins current values instead of the C plugin's.
  • Comments that described the C port or narrated past changes are gone.
  • CLAUDE.md is cut to the rules (94 lines). The design narrative moved to docs/architecture.md, and the list of deviations from the C plugin is deleted: current behaviour is the spec.

Rust code goes from 28,219 to 26,572 lines.

How to review

Go commit by commit; each one passes make check on its own. Most are deletions or mechanical moves. Look closely at:

  • 58bbae2, the stats prune. Check that the kept internal counters (audible_skipped_chunks, audio_offset_reanchors, video_corrupt_held) are the ones the tests and log lines need.
  • d71587b, the only behaviour fix in the low latency path.
  • 9540fd1, CLAUDE.md and docs/architecture.md.

How to release

Release as 3.0.0. The release notes must list the removed get_stats and GetStats fields, since overlays that read them will see them missing. The BREAKING CHANGE footer on 58bbae2 carries the list.

Risks

  • Overlays and bots that read a removed stat break silently (missing field, not a crash).
  • The "video lead beyond what OBS can queue" warning is still here. Its premise is wrong, and feat(irl-source): video delay follows the audio playout offset #36 removes it.
  • Real-stream validation against master is still to do: compare the 30 second stats line field by field.

Summary by CodeRabbit

  • Updates
    • The stats display now focuses on playback status, buffer fill, speed, A/V timing, underruns, output restarts, maximum PTS gap, and audio/video frame totals. Detailed diagnostic counters are no longer shown.
    • Audio decoder error bursts now trigger rate-limited warnings and recovery actions.
  • Documentation
    • Updated troubleshooting guidance and the bug-report template with current stats and buffer information.

…clock

the reset recovery hold and the packet keyframe gate timeout move into
irl_core::consts with the other tuning values.
get_stats and GetStats keep buffer_fill_ms, current_speed,
total_audio_frames, total_video_frames, pts_max_gap_ms, audio_underruns,
audio_output_restarts, video_delay_ms, av_skew_ms, audio_hold_ms and
reconnecting. removed: adaptive_latency_control, low_latency_audio,
reconnect_count, pts_repairs, pts_normalizations, pts_interpolations,
pts_resets, pts_last_gap_ms, silence_insertions,
audio_resync_skipped_chunks, audio_hidden_trimmed_chunks,
audio_quality_events, obs_lead_ms, audio_decoder_flushes,
video_corrupt_frames, video_corrupt_held, video_lead_ms, video_lead_excess
and stream_delay_ms, along with the counters and mirrors that only fed them.
stream_delay_ms measured schedule drift since the first frame, not
end-to-end delay.

the 30 s stats line drops the pts split, trims, quality events, obs lead,
chunk sizes, decoder flushes, corrupt/held, video lead, early and reanchors.
it gains ll= for low latency audio and prints ctrl=off only when adaptive
latency control is disabled.

the readme table and sample line, irl-stats.lua and the docs follow.

BREAKING CHANGE: the get_stats proc and the GetStats vendor request no longer report adaptive_latency_control, low_latency_audio, reconnect_count, pts_repairs, pts_normalizations, pts_interpolations, pts_resets, pts_last_gap_ms, silence_insertions, audio_resync_skipped_chunks, audio_hidden_trimmed_chunks, audio_quality_events, obs_lead_ms, audio_decoder_flushes, video_corrupt_frames, video_corrupt_held, video_lead_ms, video_lead_excess or stream_delay_ms; overlays reading them must be updated.
…tive to docs/architecture.md

the deviation list against the 1.x C plugin is gone; current behaviour is the spec.
@coderabbitai

coderabbitai Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 191b9d9a-7599-4c9c-9b04-0261946ed8bb

📥 Commits

Reviewing files that changed from the base of the PR and between 7c7a41e and 9540fd1.

📒 Files selected for processing (82)
  • .github/ISSUE_TEMPLATE/bug_report.yml
  • CLAUDE.md
  • README.md
  • crates/ffmpeg/src/codec.rs
  • crates/ffmpeg/src/dict.rs
  • crates/ffmpeg/src/format.rs
  • crates/ffmpeg/src/frame.rs
  • crates/ffmpeg/src/hw.rs
  • crates/ffmpeg/src/lib.rs
  • crates/ffmpeg/src/log.rs
  • crates/ffmpeg/src/packet.rs
  • crates/ffmpeg/src/swr.rs
  • crates/ffmpeg/src/sws.rs
  • crates/irl-core/examples/speed-controller-sim.rs
  • crates/irl-core/src/arrival.rs
  • crates/irl-core/src/audio_buffer.rs
  • crates/irl-core/src/audio_hold.rs
  • crates/irl-core/src/config.rs
  • crates/irl-core/src/consts.rs
  • crates/irl-core/src/dsp.rs
  • crates/irl-core/src/lib.rs
  • crates/irl-core/src/pacing.rs
  • crates/irl-core/src/pts_repair.rs
  • crates/irl-core/src/speed.rs
  • crates/irl-core/src/stats.rs
  • crates/irl-core/src/timing.rs
  • crates/irl-core/src/url_opts.rs
  • crates/irl-core/src/video_delay.rs
  • crates/irl-core/src/video_time.rs
  • crates/irl-provider/src/loopback.rs
  • crates/irl-source/src/audio/mod.rs
  • crates/irl-source/src/audio/pump.rs
  • crates/irl-source/src/config.rs
  • crates/irl-source/src/lib.rs
  • crates/irl-source/src/log.rs
  • crates/irl-source/src/providers.rs
  • crates/irl-source/src/receiver/audio_in.rs
  • crates/irl-source/src/receiver/decode.rs
  • crates/irl-source/src/receiver/mod.rs
  • crates/irl-source/src/receiver/probe.rs
  • crates/irl-source/src/receiver/stream.rs
  • crates/irl-source/src/settings.rs
  • crates/irl-source/src/shared.rs
  • crates/irl-source/src/source.rs
  • crates/irl-source/src/video/decode.rs
  • crates/irl-source/src/video/intake.rs
  • crates/irl-source/src/video/mod.rs
  • crates/irl-source/src/video/output.rs
  • crates/irl-source/src/video/thread.rs
  • crates/irl-source/src/websocket.rs
  • crates/irl-source/tests/audio_core.rs
  • crates/irl-source/tests/common/mod.rs
  • crates/irl-source/tests/network_sim.rs
  • crates/irl-source/tests/provider_seam.rs
  • crates/irl-source/tests/receiver_probe.rs
  • crates/irl-source/tests/receiver_stream_open.rs
  • crates/irl-source/tests/shell_config.rs
  • crates/irl-source/tests/shell_redact.rs
  • crates/irl-source/tests/shell_stats.rs
  • crates/irl-source/tests/smoke.rs
  • crates/irl-source/tests/video_pipeline.rs
  • crates/obs-sys/src/lib.rs
  • crates/obs/src/audio.rs
  • crates/obs/src/data.rs
  • crates/obs/src/lib.rs
  • crates/obs/src/log.rs
  • crates/obs/src/module.rs
  • crates/obs/src/panic.rs
  • crates/obs/src/proc.rs
  • crates/obs/src/properties.rs
  • crates/obs/src/scene.rs
  • crates/obs/src/source.rs
  • crates/obs/src/time.rs
  • crates/obs/src/video.rs
  • crates/obs/src/websocket.rs
  • crates/obs/tests/frames.rs
  • crates/obs/tests/module_macro.rs
  • crates/obs/tests/sleep.rs
  • docs/architecture.md
  • docs/audio-pipeline.md
  • docs/viewer-quality-plan.md
  • irl-stats.lua
💤 Files with no reviewable changes (1)
  • crates/irl-provider/src/loopback.rs

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.


Walkthrough

This pull request narrows public wrapper APIs, centralizes shared timing and DSP helpers, reduces published statistics, updates audio/video recovery behavior, and aligns tests, documentation, and examples with the revised interfaces.

Changes

Runtime and API consolidation

Layer / File(s) Summary
FFmpeg and OBS wrapper surfaces
crates/ffmpeg/..., crates/obs/..., crates/obs-sys/...
Several public accessors, raw-pointer helpers, enum variants, wrapper types, and re-exports were removed or made crate-visible. NS_TIME_BASE was added.
Core timing, DSP, pacing, and configuration
crates/irl-core/...
Audio construction, fixed audio-hold tuning, byte-based DSP editing, pacing inputs, URL buffer options, video defaults, throttling, and published statistics were revised.
Source audio/video and recovery paths
crates/irl-source/src/...
Audio and video state, recovery handling, timestamp mapping, queue management, decoder throttling, and diagnostics were updated.
Tests, documentation, and examples
tests/..., docs/..., README.md, CLAUDE.md, irl-stats.lua
Tests use shared fixtures and revised interfaces. Documentation and displayed statistics describe the reduced stats surface and current runtime behavior.

Priority: ➖ Normal

Estimated code review effort: 5 (Critical) | ~90 minutes

Change: Refactor · Severity of issue fixed: Low

Merge Risk: ⚪ Minimal · up to 9540f

No actionable merge-blocking issue is established. The change is mergeable after normal checks, with real-stream comparison still to be completed.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 9540f

The change reduces statistics and low-level APIs. Reviewed cancellation, recovery, and resource-accounting behavior retains its existing safeguards. Older integrations need migration, and incomplete review coverage leaves limited residual uncertainty.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • inferred — The inspected stream-input path continues to expose the owning OBS process to configured URLs, options, and decoded media through native FFmpeg. The examined changes do not demonstrate increased authority or reachability; deployment-wide and tenant-isolation guarantees were not established.

Trust Boundaries and Controls

  • observed — FFmpeg cancellation and native-context cleanup remain centrally owned. Open installs and tracks the interrupt callback, failed open untracks it, and Drop untracks before closing the context. The watch still checks the shared active flag and timeout state, while changed accessors restrict external control.

Resilience and Maintainability Implications

  • observed — The inspected audio transition retains audio-state then buffer-lock ordering, reconnect checks under state ownership, and disconnect flush/reset cleanup. Pacing retains stored-entry byte accounting on pop and drain, and clear/exit paths release queued frames. No PR-induced weakening of these inspected containment mechanisms was established.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed Docstring coverage is 84.80% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 342 functions across 50 files. (31 skipped:…
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title identifies the refactor and reduced stats surface, which are central changes in the pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

A rabbit trims the wrapper’s gate
Shared clocks now keep their measured rate
Audio hops through bytes with care
Video queues breathe cleaner air
Stats grow small and signals clear
Tests guide every change from here

Comment @coderabbitai help to get the list of available commands.

@datagutt
datagutt merged commit 5ec18e6 into master Oct 2, 2026
4 checks passed
@datagutt
datagutt deleted the refactor/lean branch October 12, 2026 10:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant