Skip to content

feat(encoder): EncoderOptions::segment_frames so a bitrate cap can hold across segments - #276

Open
SwapShaOnline wants to merge 1 commit into
dmtrKovalenko:mainfrom
SwapShaOnline:fix/encoder-segment-frames
Open

SwapShaOnline wants to merge 1 commit into
dmtrKovalenko:mainfrom
SwapShaOnline:fix/encoder-segment-frames

Conversation

@SwapShaOnline

@SwapShaOnline SwapShaOnline commented Nov 21, 2026 •

Copy link
Copy Markdown

Fixes #275.

Segments are at most a second long (min_segment_frames is min(gop_size, fps)), and each one is a fresh encoder run, so an x264 maxrate/bufsize cap starts over with a full buffer every second. This adds an opt-in EncoderOptions::segment_frames: Option<usize> that sets the minimum segment length:

  • None (the default) keeps today's behaviour, so nothing changes for existing renders.
  • The video's length in frames (or more) encodes it in one run, so a cap holds across the whole file.

The doc comment on the field explains when to use it. A scheduler test checks that a minimum equal to the length gives one segment.

Results on the repro in #275 (1080×1920, 60 fps, 20 s, crf 22, maxrate 4.5M, bufsize 9M, Apple M2, Skia on Metal):

avg Mb/s render time
main (1 s segments) 8.09 69 s
segment_frames: Some(1200) 4.68 223 s
segment_frames: Some(1200) + ("threads", "0") 4.67 40 s

One segment alone is slow because segments default to one codec thread each, so it is worth pairing with ("threads", "0"). The field's doc doesn't say so yet; I can add that, or make one segment imply automatic threads, if you prefer.

The other design I considered was switching to one segment automatically when codec_params has maxrate. I kept it opt-in because that is your call; happy to change it.

Checked: cargo test -p fframes (99 passed, 1 ignored), cargo clippy -p fframes -- -D warnings (no errors; the existing unused-dependency warnings only) and cargo fmt -p fframes --check, on macOS 27.2 with rustc 1.100.0. The rendering results above use the Skia Metal pipeline. The CPU renderer reads the same min_segment_frames (cpu.rs#L195), but I didn't render with it, and the e2e snapshots were not run.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features
    • Encoder options now include an optional setting for the minimum number of frames per segment. When configured, it sets the minimum; when left unset, the existing default calculation is preserved.
  • Tests
    • Added coverage confirming that a video matching the minimum segment length is scheduled as one segment, with its final frame marked correctly.

…gth so a bitrate cap can hold

Segments are at most a second long, and each is a fresh encoder, so an x264
maxrate/bufsize cap starts over every second (dmtrKovalenko#275). segment_frames: None
keeps today's behaviour; the video's length in frames encodes it in one run.

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

coderabbitai Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

EncoderOptions adds an optional setting for the minimum number of frames per segment. When unset, the existing GOP/FPS calculation remains in use. A scheduler test checks that 1,200 frames form one segment when the minimum is 1,200.

Changes: Encoder segment length

Layer / File(s) Summary
Configure and validate segment length
fframes/src/renderer/encoder.rs, fframes/src/renderer/scheduler.rs
EncoderOptions adds segment_frames. When set, min_segment_frames returns at least one configured frame; when unset, it retains the GOP/FPS calculation. The default is None. A scheduler test checks that 1,200 frames are assigned to one segment, with exactly one claim marked as the segment’s last frame.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature · Severity of issue fixed: Medium

Suggested reviewers: dmtrkovalenko, ashtonchew

Merge Risk: Minimal · up to 6ebb2

Adds an opt-in setting for the minimum segment length. The default behavior is unchanged. No concrete merge-blocking risk was found.

Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the main change: a new opt-in EncoderOptions::segment_frames field that lets a bitrate cap hold across segments. The raw summary confirms the added field, the min_segment_frames change…
Linked Issues check Passed Issue #275 is the only active direct link. Its coding requirements are: (1) add an opt-in EncoderOptions::segment_frames: Option<usize> that overrides the minimum segment length; (2) keep the existi…
Out of Scope Changes check Passed The whole-PR changes are limited to fframes/src/renderer/encoder.rs (new field, its doc comment, Default entry, and the min_segment_frames branch) and a scheduler test in `fframes/src/renderer/s…
Full details: Title check

Explanation

The title names the main change: a new opt-in EncoderOptions::segment_frames field that lets a bitrate cap hold across segments. The raw summary confirms the added field, the min_segment_frames change, and a scheduler test. The title is specific and matches the linked issue's goal, so it passes.

Full details: Linked Issues check

Explanation

Issue #275 is the only active direct link. Its coding requirements are: (1) add an opt-in EncoderOptions::segment_frames: Option&lt;usize&gt; that overrides the minimum segment length; (2) keep the existing behaviour when it is None; (3) make a value equal to the video length produce one encoder run; (4) add a scheduler test for that case. At head fframes/src/renderer/encoder.rs declares pub segment_frames: Option&lt;usize&gt; with a doc comment, sets segment_frames: None in Default, and min_segment_frames returns frames.max(1) for Some and the prior min(gop_size, fps) for None. Requirements 1, 2 and the wiring of the override are satisfied. The scheduler test (FrameScheduler::new(1200, 8, 1200) gives one segment) is reported in the PR summary and the raw summary. I did not read scheduler.rs at head because the diff and file read were unavailable, so the test body is taken from the summary. The reported x264 bitrate measurements are author reports and were not independently reproduced. These do not change the coding-requirement verdict.

Full details: Out of Scope Changes check

Explanation

The whole-PR changes are limited to fframes/src/renderer/encoder.rs (new field, its doc comment, Default entry, and the min_segment_frames branch) and a scheduler test in fframes/src/renderer/scheduler.rs. Each change serves issue #275 directly. The head encoder.rs also shows a documentation placement defect: the former doc comment of split_gop_chunks ('Split video for concurrent rendering...') now sits above min_segment_frames, and split_gop_chunks has no doc comment. This is a documentation quality issue in an in-scope file. It is not an unrelated change and does not affect behaviour.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 6af75bf8-cce6-4b0d-8828-6fe95b4926f2
Commits

Reviewing files that changed from the base of the PR and between 1cb1940 and 6ebb2d4.

Files selected for processing: 2

  • fframes/src/renderer/encoder.rs
  • fframes/src/renderer/scheduler.rs

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

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.

x264 maxrate/bufsize overshoot by ~40% of bufsize per second, because each ≤1 s segment is a fresh encoder

1 participant