Delay late-arriving video into pacing instead of dropping

[datagutt]

…pping or judder

Summary by CodeRabbit

• New Features

  • Added adaptive standing delay for late-arriving video to improve pacing and lip-sync.
  • Added the video_delay_ms statistic and delay details to receiver logs.
  • Added a delivery lead for video frames when anchoring without audio.

• Documentation

  • Updated statistics references and video-quality guidance to describe video delay behavior.

[coderabbitai]

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: 17d19e67-02b6-46f8-88a6-7b2ca285a9d8

📥 Commits

Reviewing files that changed from the base of the PR and between bad33a1 and 3fd2147.

📒 Files selected for processing (17)

• CLAUDE.md
• README.md
• crates/irl-core/src/consts.rs
• crates/irl-core/src/lib.rs
• crates/irl-core/src/pacing.rs
• crates/irl-core/src/stats.rs
• crates/irl-core/src/video_delay.rs
• crates/irl-source/src/receiver/decode.rs
• crates/irl-source/src/receiver/stream.rs
• crates/irl-source/src/shared.rs
• crates/irl-source/src/source.rs
• crates/irl-source/src/video/output.rs
• crates/irl-source/src/video/thread.rs
• crates/irl-source/tests/network_sim.rs
• crates/irl-source/tests/shell_stats.rs
• crates/irl-source/tests/video_pipeline.rs
• docs/viewer-quality-plan.md

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

---

Walkthrough

The change adds bounded standing video delay based on packet arrival margins. It records receive timestamps, adjusts queued and future due times, resets delay across connections, and exposes video_delay_ms in logs and statistics.

Changes

Standing video delay

Layer / File(s)	Summary
Delay model and queue support crates/irl-core/src/video_delay.rs, crates/irl-core/src/pacing.rs, crates/irl-core/src/consts.rs, crates/irl-core/src/lib.rs	Adds VideoDelay, delay-raise reporting, recurrence rules, caps, tick rounding, queue shifting, public exports, and unit tests.
Video timing integration crates/irl-source/src/receiver/*, crates/irl-source/src/shared.rs, crates/irl-source/src/video/*, crates/irl-source/tests/*	Carries packet receipt times into pacing, raises delay before and after anchoring, shifts queued frames, applies delay to due times, and resets delay during clears and decoder handovers.
Statistics and behavior documentation crates/irl-core/src/stats.rs, crates/irl-source/src/source.rs, crates/irl-source/src/receiver/stream.rs, README.md, CLAUDE.md, docs/viewer-quality-plan.md, crates/irl-source/tests/shell_stats.rs	Adds video_delay_ms to statistics, logs, serialization fixtures, and documentation. Updates behavior and deviation records.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant Receiver
  participant VideoThread
  participant VideoDelay
  participant PacingQueue
  participant StatsSnapshot
  Receiver->>VideoThread: deliver frame with received_ns
  VideoThread->>VideoDelay: evaluate arrival margin
  VideoDelay-->>VideoThread: return DelayRaise when required
  VideoThread->>PacingQueue: shift queued due times
  VideoThread->>StatsSnapshot: publish video_delay_ns
  StatsSnapshot-->>VideoThread: expose video_delay_ms

Loading

Merge Risk: ⚪ Minimal · up to 3fd21

This change adds a bounded standing delay to compensate for late-arriving video instead of dropping or judder-causing frames, and threads the new delay value through pacing, connection reset/handover logic, and statistics reporting. Review and direct verification found the reset and statistics-mirroring logic correctly clears stale values across connection transitions, and the core delay-raising and windowing logic is well tested. No merge-blocking issues were found.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: late-arriving video now enters pacing instead of being dropped.
Docstring Coverage	✅ Passed	Docstring coverage is 97.37% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 76 functions across 14 files. (3 skipped: 3…
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.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/video-delay

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit measures frames at night,
Late arrivals gain pacing light,
Queues shift by measured time,
Stats record the delay line,
Tests guard each timing gate,
Video hops to steady state.}

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