Increase SCK queue depth to avoid timeouts

[Brendonovich]

This will hopefully mitigate some of the 'Stream was stopped by the system' SCK errors, though due to the lack of information in those errors it could have no effect at all.

Summary by CodeRabbit

• Performance
  • Increased video buffer capacity to improve tolerance for frame processing delays, reducing stutter during screen capture.
  • Added frame-rate–adaptive queue depth that auto-adjusts capture buffering based on FPS (with sensible clamping) for more consistent, reliable recordings across varying system conditions.

[coderabbitai]

Walkthrough

Increased video buffer channel from 4 to 12 and added dynamic queue depth computation: queue_depth = ceil((fps / 30) * 5), clamped to [3, 8], logged and passed into stream configuration via a new with_queue_depth(...) builder call.

Changes

Cohort / File(s)	Summary
macOS Screen Capture Implementation crates/recording/src/sources/screen_capture/macos.rs	Increased video channel buffer size to 12. Compute queue_depth = ceil((fps / 30) * 5), clamp to [3, 8], log the selected queue depth, and pass it to the stream configuration using with_queue_depth(queue_depth).
Configuration Builder API Extension crates/scap-screencapturekit/src/config.rs	Added pub fn set_queue_depth(&mut self, depth: isize) (internal setter that clamps to a maximum of 8) and pub fn with_queue_depth(mut self, depth: isize) -> Self (chainable alias). Doc comments describe semantics, defaults, and max. No other signature changes.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Init as Initializer
  participant Mac as macOS capture
  participant Cfg as StreamCfgBuilder
  participant Stream as Stream

  Init->>Mac: start screen capture (fps)
  note right of Mac `#D3E4CD`: compute queue_depth = ceil((fps/30)*5)\nclamp to [3,8]
  Mac->>Cfg: with_queue_depth(queue_depth)
  Cfg->>Stream: build & start stream (with queue depth)
  Stream-->>Mac: stream running

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Small, localized changes: channel buffer size, a simple math formula, logging, and two builder methods.
• Review focus:
  • Verify queue depth formula and clamping match expectations across caller and builder.
  • Ensure no off-by-one or integer/float rounding issues in ceil/clamp code.
  • Confirm logging message clarity and no unintended performance impact.

Poem

🐰
A rabbit watched the frames align,
I nudged the queue to keep them fine,
From tiny four to kinder twelve,
Depth tuned by framerate, calm and delve,
Hopping bytes, our stream will shine.

Pre-merge checks and finishing touches

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main change: increasing SCK queue depth parameters to mitigate timeout-related errors, which is demonstrated across both modified files.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch sck-queue-depth

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a2d34a3 and 205f299.

📒 Files selected for processing (2)

• crates/recording/src/sources/screen_capture/macos.rs (2 hunks)
• crates/scap-screencapturekit/src/config.rs (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• crates/scap-screencapturekit/src/config.rs

🧰 Additional context used

📓 Path-based instructions (2)

**/*.rs

📄 CodeRabbit inference engine (AGENTS.md)

**/*.rs: Format Rust code using rustfmt and ensure all Rust code passes workspace-level clippy lints.
Rust modules should be named with snake_case, and crate directories should be in kebab-case.

Files:

• crates/recording/src/sources/screen_capture/macos.rs

crates/*/src/**/*

📄 CodeRabbit inference engine (AGENTS.md)

Rust crates should place tests within the src/ and/or a sibling tests/ directory for each crate inside crates/*.

Files:

• crates/recording/src/sources/screen_capture/macos.rs

🧠 Learnings (2)

📚 Learning: 2025-10-28T08:39:42.230Z

Learnt from: Brendonovich
Repo: CapSoftware/Cap PR: 1305
File: crates/recording/src/output_pipeline/macos.rs:80-90
Timestamp: 2025-10-28T08:39:42.230Z
Learning: In `crates/recording/src/output_pipeline/macos.rs`, the `AVFoundationMp4Muxer` intentionally holds the `Mutex<MP4Encoder>` lock during retry attempts in `send_video_frame()` and `send_audio_frame()`. This blocking behavior is correct because frame processing must happen sequentially to prevent audio and video frames from being interleaved incorrectly in the encoder.

Applied to files:

• crates/recording/src/sources/screen_capture/macos.rs

📚 Learning: 2025-10-17T05:58:22.586Z

Learnt from: Brendonovich
Repo: CapSoftware/Cap PR: 1219
File: crates/enc-avfoundation/src/mp4.rs:350-373
Timestamp: 2025-10-17T05:58:22.586Z
Learning: In crates/enc-avfoundation/src/mp4.rs, the `finish()` method intentionally skips video extension when `is_paused` is true. This is correct behavior because if recording is paused, the video should not be extended beyond the pause point—the pause is user-initiated, unlike the case where ScreenCaptureKit stops providing frames during static content.

Applied to files:

• crates/recording/src/sources/screen_capture/macos.rs

🧬 Code graph analysis (1)

crates/recording/src/sources/screen_capture/macos.rs (1)

crates/scap-screencapturekit/src/config.rs (1)

• default (89-91)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Build Desktop (x86_64-pc-windows-msvc, windows-latest)
• GitHub Check: Build Desktop (aarch64-apple-darwin, macos-latest)
• GitHub Check: Analyze (rust)

🔇 Additional comments (3)

crates/recording/src/sources/screen_capture/macos.rs (3)

71-72: LGTM: Channel buffer increase looks reasonable.

The 3x increase to 12 provides adequate headroom above the maximum queue_depth of 8, which should help mitigate frame processing delays and timeout issues.

---

132-134: Queue depth computation looks correct.

The formula scales with FPS (approximately 1 buffer slot per 6 fps) and the clamp to [3, 8] prevents extremes. The debug logging will be helpful for diagnostics.

---

141-141: Correct usage of the new builder method.

The computed queue_depth is properly passed to the stream configuration via the chainable builder method.

---

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

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