The 12 Hard Rules Enforced by video-use for Production Correctness

The video-use framework guarantees production-ready output by enforcing 12 non-negotiable hard rules that prevent silent failures, broken media alignment, and timing drift, immediately aborting the build if any violation is detected.

The browser-use/video-use repository implements a rigorous validation system codified in SKILL.md and enforced across helper modules like render.py and transcribe.py. These 12 hard rules govern everything from FFmpeg filter chain ordering to word-level ASR requirements, ensuring that automated video editing produces broadcast-quality results without manual intervention.

Overview of the 12 Hard Rules

According to the SKILL.md file in the repository root, the following twelve constraints are hard-coded into the tooling and verified by the self-evaluation loop:

1. Subtitles Last in Filter Chain – Subtitles are applied after every overlay to prevent graphics from obscuring captions.
2. Lossless Per-Segment Extract – Use -c copy for segment extraction and concatenation rather than single-pass filtergraph encoding.
3. 30ms Audio Fades – Apply afade=t=in:st=0:d=0.03 and corresponding fade-out at every segment boundary to eliminate pops.
4. Overlay Timing Synchronization – Overlays must use setpts=PTS-STARTPTS+T/TB to shift frame 0 to the window start.
5. Master SRT Offset Calculation – Subtitle timestamps use output_time = word.start – segment_start + segment_offset to maintain sync after concatenation.
6. Word-Boundary Snap – Cuts must never occur inside a word; all edges snap to Scribe transcript boundaries.
7. Cut Edge Padding – Every cut edge receives 30–200ms of padding to absorb Scribe timestamp drift (50–100ms).
8. Word-Level Verbatim ASR – Only word-level transcripts are permitted; SRT/phrase mode or normalized fillers are prohibited.
9. Transcript Caching – Transcripts are cached per source file and never re-transcribed unless the source changes.
10. Parallel Animation Agents – Multiple animations run via parallel sub-agents, never sequentially.
11. Strategy Confirmation – User approval of a plain-English plan is required before any cut is executed.
12. Isolated Output Directories – All session outputs live in <videos_dir>/edit/ and never inside the video-use/ project directory.

Technical Implementation in the Codebase

The hard rules are not merely documentation; they are enforced by helpers/render.py, helpers/grade.py, and helpers/transcribe.py. When any rule is violated, the pipeline aborts before showing a preview.

Subtitle Placement and Filter Chain Order (Rule 1)

In helpers/render.py, the subtitle filter is appended after all overlay filters to ensure captions remain visible:

# … after all overlay filters have been built …

subtitle_filter = f"subtitles={master_srt_path}:force_style='...'"
cmd = [
    "ffmpeg", "-y", "-i", segment_path,
    "-filter_complex", f"{overlay_chain},{subtitle_filter}",
    "-c:a", "copy", output_path,
]

Lossless Concatenation and Audio Fades (Rules 2–3)

To avoid generational loss, segments are extracted using -c copy and concatenated via the FFmpeg demuxer:

# extract each segment losslessly

subprocess.run(["ffmpeg", "-i", src, "-ss", start, "-to", end,
                "-c", "copy", segment_file])

# later concat via demuxer (no re‑encoding)

with open("list.txt", "w") as f:
    for seg in segment_files:
        f.write(f"file '{seg}'\n")
subprocess.run(["ffmpeg", "-f", "concat", "-safe", "0",
                "-i", "list.txt", "-c", "copy", final_output])

Simultaneously, 30ms audio fades are injected via afade filters to prevent audible pops at cut points:

fade_in = "afade=t=in:st=0:d=0.03"
fade_out = f"afade=t=out:st={duration-0.03}:d=0.03"
audio_filter = f"{fade_in},{fade_out}"

Timeline Synchronization for Overlays and Subtitles (Rules 4–5)

Rule 4 prevents mid-animation starts by resetting the overlay's presentation timestamp:

# shift overlay start to its window start

overlay_filter = "[1]setpts=PTS-STARTPTS+{offset}/TB[ov]"
cmd = ["ffmpeg", "-i", video, "-i", overlay,
       "-filter_complex", f"{overlay_filter};[0][ov]overlay"]

Rule 5 ensures subtitle accuracy after concatenation by recalculating timestamps relative to the output timeline:

# In render.py: adjust SRT timestamps before feeding to ffmpeg

def shift_srt(word_start, seg_start, seg_offset):
    return word_start - seg_start + seg_offset

Word-Level Precision and Cut Padding (Rules 6–8)

Implemented in helpers/grade.py and helpers/transcribe.py, these rules guarantee intelligible speech boundaries. Cuts snap to the nearest word boundary from the Scribe transcript, then receive padding to absorb ASR drift:

# snap cut to nearest word boundary

cut_time = round_nearest_word_boundary(requested_cut)

# apply padding

pad = max(0.03, min(0.2, estimated_drift))
final_start = cut_time - pad
final_end   = cut_time + pad

Rule 8 mandates word-level verbatim ASR (no phrase-mode or filler normalization), which helpers/transcribe.py enforces by calling the Scribe API with specific parameters and caching the granular JSON output.

Transcript Caching and Deterministic Builds (Rule 9)

To save API quota and ensure reproducibility, transcripts are cached per source file:

cache_path = f"{cache_dir}/{source_path.stem}.json"
if cache_path.exists() and not source_path.stat().st_mtime > cache_path.stat().st_mtime:
    load_from_cache(cache_path)
else:
    scribe_call(...)

Parallel Execution and Output Isolation (Rules 10, 12)

Rule 10 minimizes wall-clock time by spawning animation sub-agents concurrently:

# spawn N agents at once

for slot in slots:
    agents.append(Agent(tool="Animation", params=slot))
await asyncio.gather(*[a.run() for a in agents])

Rule 12 enforces workspace hygiene by restricting writes to <videos_dir>/edit/:

output_dir = Path(edit_dir) / "edit"
output_path = output_dir / "final.mp4"
output_dir.mkdir(parents=True, exist_ok=True)

Summary

• The 12 hard rules are defined in SKILL.md and enforced by helpers/render.py, helpers/grade.py, and helpers/transcribe.py.
• Violations trigger immediate build aborts before any preview is rendered.
• Key technical safeguards include 30ms audio fades, setpts overlay timing, word-boundary snapping with 30–200ms padding, and lossless -c copy concatenation.
• The system requires word-level verbatim ASR and deterministic transcript caching to ensure precise editing.
• All outputs are isolated to <videos_dir>/edit/ to maintain source tree cleanliness.

Frequently Asked Questions

What happens if a hard rule is violated during processing?

The self-evaluation loop in the pipeline detects violations through helpers/grade.py and helpers/timeline_view.py. If any rule is broken—such as subtitles not being last in the filter chain or a cut falling inside a word—the build aborts immediately and reports the specific failure before generating a preview. This prevents silent failures and ensures only production-correct videos reach the user.

Why does video-use require word-level ASR instead of phrase-level transcripts?

Word-level ASR (Rule 8) provides sub-second timing granularity required to snap cuts to exact word boundaries (Rule 6). Phrase-level or normalized SRT modes lose the precise timestamps needed to avoid clipping words or cutting mid-syllable. The helpers/transcribe.py module enforces this by caching raw Scribe JSON with per-word timings rather than formatted SRT files.

How does the 30ms audio fade prevent production errors?

The 30ms fade (Rule 3) eliminates audible pops and clicks that occur when audio waveforms are cut at non-zero crossings. Implemented via FFmpeg's afade filter in helpers/render.py, this short crossfade acts as a safety margin that masks minor timestamp inaccuracies while maintaining perceptual seamlessness between segments.

Where are the 12 hard rules documented in the source code?

The canonical definitions reside in SKILL.md at the repository root, with specific line references for each rule (lines 22–33). The enforcement mechanisms are implemented in helpers/render.py (filter chains, concat, output paths), helpers/grade.py (cut validation), and helpers/transcribe.py (ASR and caching). The helpers/timeline_view.py module provides visual verification for overlay and subtitle timing rules.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}