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

> Discover the 12 hard rules enforced by video-use to ensure production-ready video output. Prevent failures and ensure alignment with this essential guide.

- Repository: [Browser Use/video-use](https://github.com/browser-use/video-use)
- Tags: best-practices
- Published: 2026-07-07

---

**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`](https://github.com/browser-use/video-use/blob/main/SKILL.md) and enforced across helper modules like [`render.py`](https://github.com/browser-use/video-use/blob/main/render.py) and [`transcribe.py`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py), and [`helpers/transcribe.py`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), the subtitle filter is appended after all overlay filters to ensure captions remain visible:

```python

# … 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:

```python

# 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:

```python
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:

```python

# 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:

```python

# 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`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) and [`helpers/transcribe.py`](https://github.com/browser-use/video-use/blob/main/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:

```python

# 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`](https://github.com/browser-use/video-use/blob/main/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:

```python
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:

```python

# 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/`:

```python
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`](https://github.com/browser-use/video-use/blob/main/SKILL.md) and enforced by [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py), and [`helpers/transcribe.py`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) and [`helpers/timeline_view.py`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) (filter chains, concat, output paths), [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) (cut validation), and [`helpers/transcribe.py`](https://github.com/browser-use/video-use/blob/main/helpers/transcribe.py) (ASR and caching). The [`helpers/timeline_view.py`](https://github.com/browser-use/video-use/blob/main/helpers/timeline_view.py) module provides visual verification for overlay and subtitle timing rules.