Korean Windows fixes, and per-range grade/crop/speed + capture audio on the EDL

[beyondwork5]

Seven commits from using video-use daily on Korean Windows, in two groups. Each commit stands alone and compiles on its own — happy to drop or split anything.

Bug fixes

• Korean Windows paths. subprocess.run(..., text=True) decodes with the locale codec (cp949 here) while ffmpeg echoes the input path to stderr, so a path containing Hangul raised UnicodeDecodeError, stderr came back None, and the failure surfaced as an unrelated TypeError. The concat list, transcript read and subtitle write used the locale codec too. Separately, backslashes in a subtitles path are consumed by the filtergraph parser, so libass received the path with its separators stripped — forward slashes work on every platform.
• ffprobe output decoded as utf-8, same root cause.
• Hangul in timeline_view rendered as tofu on Windows.
• A clips folder now records which EDL produced it. Segment filenames carry only an index and a source name, so a leftover render of a different EDL matches by name and hands back the wrong durations to anything that measures those files. This bit me: a 46-segment render left from an earlier EDL made a 41-segment one measure 259.9s instead of 480.0s, and subtitle placement reads those durations, so captions drifted with no error at all. clips_*/_ranges.json lets a consumer check before trusting them.

New EDL fields

• grade per range. Sources shot in one session still drift in white balance when the camera restarts, and a single EDL-wide grade has nowhere to express that. Measure a fixed patch (a cheek, a wall) with signalstats on each source and correct toward the reference.
• crop per range, applied before the scale. Crop values are measured against the source's own resolution; after the scale they reframe a different picture, and a 4K-measured crop does not even fit a 1080p frame.
• audio at the EDL level for a fixed capture chain (highpass, EQ, gate, compressor). Deliberately not the place for loudnorm — segments are normalized independently, so a quiet one gets lifted to match a loud one and the relative levels between segments are destroyed. Loudness stays a single two-pass step on the finished cut.
• speed per range via setpts/atempo, so pitch is preserved. The 30ms edge fades are computed against the post-atempo length, not the source duration, so they still land on the true out-point.
• width on the EDL raises the output target above the 1080p default, so a 4K source can stay full size. The default is unchanged, and --preview stays 1080p on purpose: it is a fast QC pass, not a resolution preview.

One behaviour change worth calling out: -t now precedes -i, so the duration limits how much input is read rather than how much output is written. With -ss before -i that is the fast-seek form.

SKILL.md documents the new fields and four failure modes that are silent.

Rebased on current main. The earlier "read output fps from the EDL" change from my fork is dropped — #55 solved that better.

---

Summary by cubic

Fixes Korean Windows rendering, where Hangul paths crashed subprocess decoding and subtitle paths lost their separators, and guards against stale clips folders returning wrong durations. Adds per-range grade/crop/speed, an EDL-level audio capture chain, and an optional output width.

Bug Fixes

• ffmpeg/ffprobe output is decoded as UTF-8 with errors="replace" instead of the locale codec, so Hangul paths no longer surface as UnicodeDecodeError and hide the real failure.
• Subtitle paths use forward slashes, so the filtergraph parser doesn't strip backslashes on Windows.
• Malgun Gothic is now in the font search path, so Hangul renders in the timeline view instead of tofu.
• Each clips_* folder gets a _ranges.json so consumers can tell whether the render came from the current EDL before trusting measured durations.

New Features

• A range can override the EDL-wide grade and crop; crop runs before scale, where its values are measured.
• audio sets a fixed per-EDL or per-range capture chain (highpass, EQ, gate, compressor); loudnorm is intentionally not part of it because per-segment normalization would flatten relative levels.
• speed per range time-remaps via setpts/atempo, preserving pitch; fades are timed against the post-speed duration.
• width raises the output target above 1080p; --preview stays 1080p for fast QC.
• -t now precedes -i, so the duration limits input read (fast-seek) instead of output write.

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

[cubic-dev-ai]

8 issues found across 3 files

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:306">
P2: ffmpeg's `atempo` filter only accepts tempo in [0.5, 100.0]. If an EDL sets `speed` below 0.5 (e.g. 0.25x slow-motion) or above 100, the audio filter graph fails and the whole segment extraction errors out, even though `setpts=PTS/{speed}` on the video accepts any value. Consider chaining multiple `atempo` filters for out-of-range speeds, or clamping/documenting the supported range.</violation>

<violation number="2" location="helpers/render.py:400">
P2: When a range overrides `grade` with the documented `"auto"` value, the renderer sends `__AUTO__` to ffmpeg and the extraction fails. Resolve per-range `"auto"` through `auto_grade_for_clip` just like an EDL-wide auto grade.</violation>

<violation number="3" location="helpers/render.py:409">
P2: Reject non-finite and non-positive range speeds before calculating the output duration or constructing ffmpeg filters.</violation>

<violation number="4" location="helpers/render.py:409">
P2: When a range uses `speed != 1.0`, the extracted segment's output duration becomes `duration/speed`, but `build_master_srt` still advances its caption timeline by the unadjusted source `seg_duration = end - start` (lines ~503/544) and maps caption times from source timestamps. Every segment after the sped one drifts, and captions inside the sped segment no longer match the audio. The `_ranges.json` and SRT are also consistent with source time, not post-speed output time. If `speed` is meant to be combined with `--build-subtitles`, the SRT offsets must be scaled by `1/speed` per segment (and the ranges recorded in `_ranges.json` should reflect the output duration).</violation>

<violation number="5" location="helpers/render.py:425">
P2: Include the effective rendering parameters, or an EDL/configuration hash, in `_ranges.json`; otherwise comparing this marker cannot detect stale clips from an EDL with the same source ranges but different speed or edits.</violation>
</file>

<file name="SKILL.md">

<violation number="1" location="SKILL.md:34">
P3: In hard rule 13, "each renders ~1 frame long" is missing the comparative and reads as "each segment is about one frame in length". Say "each renders ~1 frame longer than the EDL arithmetic" (and note it's ~2 frames at common fps if the number should match the 340.96 vs 344.31 example).</violation>

<violation number="2" location="SKILL.md:34">
P3: Adding hard rules 13–16 makes SKILL.md define 16 hard rules, but README.md line 110 still says "12 hard rules". Update the README count (and the "the 12 hard rules" reference) to 16 so the two documents agree.</violation>

<violation number="3" location="SKILL.md:298">
P3: The EDL section documents per-range `grade`/`crop`/`audio` but omits the other new fields shipped in this change: per-range `speed` (setpts/atempo, duration becomes `duration/speed`) and EDL-wide `width` (e.g. 3840 for 4K while preview stays 1080p). Add them so the manual matches the renderer.</violation>
</file>

<sub>Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Reject non-finite and non-positive range speeds before calculating the output duration or constructing ffmpeg filters.

Prompt for AI agents

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

<comment>Reject non-finite and non-positive range speeds before calculating the output duration or constructing ffmpeg filters.</comment>

<file context>
@@ -350,18 +394,39 @@ def extract_all_segments(
+        seg_audio = r.get("audio", edl_audio)
+        seg_crop = r.get("crop", edl_crop)
 
+        speed = float(r.get("speed", 1.0))
         note = r.get("beat") or r.get("note") or ""
-        print(f"  [{i:02d}] {src_name}  {start:7.2f}-{end:7.2f}  ({duration:5.2f}s)  {note}")
</file context>

Suggested change

	speed = float(r.get("speed", 1.0))
	speed = float(r.get("speed", 1.0))
	if not 0 < speed < float("inf"):
	raise ValueError("range speed must be finite and greater than zero")

[cubic-dev-ai]

P2: Include the effective rendering parameters, or an EDL/configuration hash, in _ranges.json; otherwise comparing this marker cannot detect stale clips from an EDL with the same source ranges but different speed or edits.

Prompt for AI agents

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

<comment>Include the effective rendering parameters, or an EDL/configuration hash, in `_ranges.json`; otherwise comparing this marker cannot detect stale clips from an EDL with the same source ranges but different speed or edits.</comment>

<file context>
@@ -350,18 +394,39 @@ def extract_all_segments(
+    # only an index and a source name, so a leftover render of a *different* EDL
+    # can match by name and hand back the wrong durations to anything that
+    # measures these files. Consumers compare this list before trusting them.
+    (clips_dir / "_ranges.json").write_text(
+        json.dumps([{"source": r["source"], "start": r["start"], "end": r["end"]}
+                    for r in ranges], ensure_ascii=False),
</file context>

[cubic-dev-ai]

P2: When a range overrides grade with the documented "auto" value, the renderer sends __AUTO__ to ffmpeg and the extraction fails. Resolve per-range "auto" through auto_grade_for_clip just like an EDL-wide auto grade.

Prompt for AI agents

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

<comment>When a range overrides `grade` with the documented `"auto"` value, the renderer sends `__AUTO__` to ffmpeg and the extraction fails. Resolve per-range `"auto"` through `auto_grade_for_clip` just like an EDL-wide auto grade.</comment>

<file context>
@@ -350,18 +394,39 @@ def extract_all_segments(
+        # A range may override the EDL-wide grade. Sources shot in one session can
+        # still drift in white balance (camera restart), so a per-range correction
+        # is the only place that difference can be expressed.
+        if "grade" in r:
+            seg_filter = resolve_grade_filter(r["grade"])
+        elif is_auto:
</file context>

Suggested change

	if "grade" in r:
	seg_filter = resolve_grade_filter(r["grade"])
	elif is_auto:
	seg_filter, _stats = auto_grade_for_clip(src_path, start=start, duration=duration, verbose=False)
	else:
	if r.get("grade") == "auto" or (is_auto and "grade" not in r):
	seg_filter, _stats = auto_grade_for_clip(src_path, start=start, duration=duration, verbose=False)
	elif "grade" in r:
	seg_filter = resolve_grade_filter(r["grade"])
	else:
	seg_filter = resolved

[cubic-dev-ai]

P2: ffmpeg's atempo filter only accepts tempo in [0.5, 100.0]. If an EDL sets speed below 0.5 (e.g. 0.25x slow-motion) or above 100, the audio filter graph fails and the whole segment extraction errors out, even though setpts=PTS/{speed} on the video accepts any value. Consider chaining multiple atempo filters for out-of-range speeds, or clamping/documenting the supported range.

Prompt for AI agents

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

<comment>ffmpeg's `atempo` filter only accepts tempo in [0.5, 100.0]. If an EDL sets `speed` below 0.5 (e.g. 0.25x slow-motion) or above 100, the audio filter graph fails and the whole segment extraction errors out, even though `setpts=PTS/{speed}` on the video accepts any value. Consider chaining multiple `atempo` filters for out-of-range speeds, or clamping/documenting the supported range.</comment>

<file context>
@@ -257,19 +278,35 @@ def extract_segment(
+    if audio_filter:
+        af_parts.append(audio_filter)      # capture chain runs on the raw audio
+    if speed != 1.0:
+        af_parts.append(f"atempo={speed}")
+    af_parts.append("afade=t=in:st=0:d=0.03")
+    af_parts.append(f"afade=t=out:st={fade_out_start:.3f}:d=0.03")
</file context>

[cubic-dev-ai]

P2: When a range uses speed != 1.0, the extracted segment's output duration becomes duration/speed, but build_master_srt still advances its caption timeline by the unadjusted source seg_duration = end - start (lines ~503/544) and maps caption times from source timestamps. Every segment after the sped one drifts, and captions inside the sped segment no longer match the audio. The _ranges.json and SRT are also consistent with source time, not post-speed output time. If speed is meant to be combined with --build-subtitles, the SRT offsets must be scaled by 1/speed per segment (and the ranges recorded in _ranges.json should reflect the output duration).

Prompt for AI agents

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

<comment>When a range uses `speed != 1.0`, the extracted segment's output duration becomes `duration/speed`, but `build_master_srt` still advances its caption timeline by the unadjusted source `seg_duration = end - start` (lines ~503/544) and maps caption times from source timestamps. Every segment after the sped one drifts, and captions inside the sped segment no longer match the audio. The `_ranges.json` and SRT are also consistent with source time, not post-speed output time. If `speed` is meant to be combined with `--build-subtitles`, the SRT offsets must be scaled by `1/speed` per segment (and the ranges recorded in `_ranges.json` should reflect the output duration).</comment>

<file context>
@@ -350,18 +394,39 @@ def extract_all_segments(
+        seg_audio = r.get("audio", edl_audio)
+        seg_crop = r.get("crop", edl_crop)
 
+        speed = float(r.get("speed", 1.0))
         note = r.get("beat") or r.get("note") or ""
-        print(f"  [{i:02d}] {src_name}  {start:7.2f}-{end:7.2f}  ({duration:5.2f}s)  {note}")
</file context>

[cubic-dev-ai]

P3: In hard rule 13, "each renders ~1 frame long" is missing the comparative and reads as "each segment is about one frame in length". Say "each renders ~1 frame longer than the EDL arithmetic" (and note it's ~2 frames at common fps if the number should match the 340.96 vs 344.31 example).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At SKILL.md, line 34:

<comment>In hard rule 13, "each renders ~1 frame long" is missing the comparative and reads as "each segment is about one frame in length". Say "each renders ~1 frame longer than the EDL arithmetic" (and note it's ~2 frames at common fps if the number should match the 340.96 vs 344.31 example).</comment>

<file context>
@@ -31,6 +31,10 @@ These are the things where deviation produces silent failures or broken output.
 10. **Parallel sub-agents for multiple animations.** Never sequential. Spawn N at once via the `Agent` tool; total wall time ≈ slowest one.
 11. **Strategy confirmation before execution.** Never touch the cut until the user has approved the plain-English plan.
 12. **All session outputs in `<videos_dir>/edit/`.** Never write inside the `video-use/` project directory.
+13. **Human-facing times come from measured segment durations, not EDL arithmetic.** Segments are cut to frame boundaries, so each renders ~1 frame long; over 46 segments that was 340.96s of arithmetic against 344.31s on disk. Subtitle and overlay placement must read the rendered files. And **a clips directory belongs to exactly one EDL** — segment filenames carry only an index and a source name, so a leftover render of a different EDL matches by name and hands back the wrong durations. Compare `clips_*/_ranges.json` before trusting them. Silent failure: captions drift with no error.
+14. **`loudnorm` runs once, on the finished cut.** Never inside a per-segment capture chain — segments are normalized independently, so a quiet one gets lifted to match a loud one and the relative levels between segments are destroyed. Silent failure: the mix sounds flat and pumped.
+15. **`crop` before `scale`.** Crop values are measured against the source's own resolution; after the scale they reframe a different picture, and a 4K-measured crop does not even fit a 1080p frame.
</file context>

[cubic-dev-ai]

P3: Adding hard rules 13–16 makes SKILL.md define 16 hard rules, but README.md line 110 still says "12 hard rules". Update the README count (and the "the 12 hard rules" reference) to 16 so the two documents agree.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At SKILL.md, line 34:

<comment>Adding hard rules 13–16 makes SKILL.md define 16 hard rules, but README.md line 110 still says "12 hard rules". Update the README count (and the "the 12 hard rules" reference) to 16 so the two documents agree.</comment>

<file context>
@@ -31,6 +31,10 @@ These are the things where deviation produces silent failures or broken output.
 10. **Parallel sub-agents for multiple animations.** Never sequential. Spawn N at once via the `Agent` tool; total wall time ≈ slowest one.
 11. **Strategy confirmation before execution.** Never touch the cut until the user has approved the plain-English plan.
 12. **All session outputs in `<videos_dir>/edit/`.** Never write inside the `video-use/` project directory.
+13. **Human-facing times come from measured segment durations, not EDL arithmetic.** Segments are cut to frame boundaries, so each renders ~1 frame long; over 46 segments that was 340.96s of arithmetic against 344.31s on disk. Subtitle and overlay placement must read the rendered files. And **a clips directory belongs to exactly one EDL** — segment filenames carry only an index and a source name, so a leftover render of a different EDL matches by name and hands back the wrong durations. Compare `clips_*/_ranges.json` before trusting them. Silent failure: captions drift with no error.
+14. **`loudnorm` runs once, on the finished cut.** Never inside a per-segment capture chain — segments are normalized independently, so a quiet one gets lifted to match a loud one and the relative levels between segments are destroyed. Silent failure: the mix sounds flat and pumped.
+15. **`crop` before `scale`.** Crop values are measured against the source's own resolution; after the scale they reframe a different picture, and a 4K-measured crop does not even fit a 1080p frame.
</file context>

[cubic-dev-ai]

P3: The EDL section documents per-range grade/crop/audio but omits the other new fields shipped in this change: per-range speed (setpts/atempo, duration becomes duration/speed) and EDL-wide width (e.g. 3840 for 4K while preview stays 1080p). Add them so the manual matches the renderer.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At SKILL.md, line 298:

<comment>The EDL section documents per-range `grade`/`crop`/`audio` but omits the other new fields shipped in this change: per-range `speed` (setpts/atempo, duration becomes `duration/speed`) and EDL-wide `width` (e.g. 3840 for 4K while preview stays 1080p). Add them so the manual matches the renderer.</comment>

<file context>
@@ -286,7 +293,13 @@ Match the source unless the user asked for something specific. Common targets: `
-`grade` is a preset name or raw ffmpeg filter. `overlays` are rendered animation clips. `subtitles` is optional and applied LAST.
+`grade` is a preset name, a raw ffmpeg filter, or `"auto"`. `overlays` are rendered animation clips. `subtitles` is optional and applied LAST.
+
+A **range** may carry its own `grade` and `crop`, overriding the EDL-wide value:
+
+- `grade` per range — sources shot in one session still drift in white balance when the camera restarts, and a single EDL-wide grade has nowhere to express that difference. Measure a fixed patch (a cheek, a wall) with `signalstats` on each source and correct toward the reference.
</file context>