feat: add --fps option to render.py (default 24)

[redsung-team]

Summary

The output frame rate is hardcoded to 24fps inside extract_segment's ffmpeg call. This is a great default for cinematic talking-head footage but drops motion fidelity for 60fps screen-capture or 30fps tutorial sources. This PR adds a --fps CLI option (default 24) so users can match the source rate without patching the file.

• extract_segment(..., fps: int = 24) — new keyword arg, threaded through to -r.
• extract_all_segments(..., fps: int = 24) — passes through.
• main() — exposes --fps argparse flag, default 24.

Default stays at 24, so existing behavior is unchanged.

Motivation

Real-world case: a 60fps screen-capture of a financial simulator with voice-over. With the hardcoded 24fps, mouse cursor / chart animation looked stuttery in the cut. --fps 60 preserves the original feel; --fps 30 is a sensible middle ground for tutorial content.

Test plan

• python helpers/render.py --help shows the new --fps FPS option
• Default render (no flag) still produces 24fps — verified with ffprobe r_frame_rate=24/1
• --fps 60 produces 60fps output — verified with ffprobe r_frame_rate=60/1
• Audio loudness normalization, fades, scale, preset/CRF ladder all unchanged
• Syntax check passes (ast.parse)

Future direction (not in this PR)

A natural follow-up would be --fps source to auto-match the first source clip's frame rate via ffprobe. Kept out of this PR to keep the change focused — happy to add in a follow-up if maintainers want it.

---

Summary by cubic

Adds a --fps option to helpers/render.py to set the output frame rate (default 24). This lets you match 30/60fps sources to preserve motion without changing code.

• New Features
  • extract_segment(..., fps=24) and extract_all_segments(..., fps=24) pass fps to ffmpeg via -r.
  • main() exposes a --fps CLI flag; default stays 24.

^{Written for commit 78f7a48. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="helpers/render.py">

<violation number="1" location="helpers/render.py:594">
P2: `--fps` accepts non-positive integers and passes them straight to ffmpeg, so a bad CLI value can abort rendering.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[cubic-dev-ai]

P2: --fps accepts non-positive integers and passes them straight to ffmpeg, so a bad CLI value can abort rendering.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At helpers/render.py, line 594:

<comment>`--fps` accepts non-positive integers and passes them straight to ffmpeg, so a bad CLI value can abort rendering.</comment>

<file context>
@@ -584,6 +589,12 @@ def main() -> None:
     )
+    ap.add_argument(
+        "--fps",
+        type=int,
+        default=24,
+        help="Output frame rate (e.g., 24, 30, 60). Default: 24 (cinematic). Use 60 to preserve screen-capture or 60fps source motion.",
</file context>

Suggested change

	type=int,
	type=lambda v: int(v) if int(v) > 0 else (_ for _ in ()).throw(argparse.ArgumentTypeError("--fps must be a positive integer")),