Self-Eval Loop and Cut-Boundary Verification in video-use: How It Validates Every Edit

The self-eval loop in video-use automatically validates rendered previews by running the timeline_view helper on cut boundaries within a ±1.5 second window, checking for visual discontinuity, audio pops, and overlay alignment issues, retrying up to three times before surfacing errors to the user.

The video-use repository (browser-use/video-use) ensures every video edit meets quality standards before users see the final output. This automated validation relies on a self-eval loop that inspects rendered content at cut boundaries while enforcing hard rules like subtitle visibility and overlay alignment. The process is documented in SKILL.md (lines 91‑99) and implemented across helpers/timeline_view.py and helpers/render.py.

How the Self-Eval Loop Works

The self-eval loop is an iterative validation pipeline that activates automatically when running render.py --preview. Rather than trusting the initial render, the system re-examines the actual output file to catch errors that traditional editing timelines might miss.

The loop follows this sequence:

1. Render the video via render.py --preview to generate a preview file.
2. Identify cut boundaries from the generated Edit Decision List (EDL).
3. Execute timeline_view on the rendered output at each boundary using a ±1.5 s window.
4. Inspect generated frames for four specific failure modes:
   • Visual discontinuity, flashes, or frame jumps
   • Waveform spikes indicating audio pops that bypassed the 30 ms fade
   • Subtitles obscured by overlays (Rule 1 violation)
   • Mis-aligned overlays or incorrect frame content (Rule 4 violation)
5. Sample additional sections (first 2 s, last 2 s, and 2–3 mid-points) to verify grade consistency and subtitle readability.
6. Run ffprobe to confirm the total duration matches the expected EDL length.
7. Re-render if necessary, automatically fixing detected issues and repeating the validation.

According to the source code documentation in SKILL.md lines 97‑99, the loop caps at three passes. After the third attempt, any remaining issues are reported to the user rather than triggering an infinite retry cycle.

Cut-Boundary Verification Process

The core of the validation happens at cut boundaries, where transitions are most likely to introduce errors.

The ±1.5 Second Inspection Window

At each cut boundary identified in the EDL, the system invokes timeline_view from helpers/timeline_view.py to extract a contextual window spanning 1.5 seconds before and after the cut. This window provides enough temporal context to generate a film-strip of 10 frames (by default) that the self-eval logic can analyze for continuity errors.

Visual and Audio Integrity Checks

The timeline_view script produces PNG frame strips and waveform visualizations. The self-eval loop scans these outputs for:

• Visual discontinuity: Sudden brightness changes or missing frames in the generated PNG strips
• Audio pops: Waveform spikes exceeding the allowed fade-out threshold (30 ms), indicating transitions that lack proper audio smoothing

Subtitle and Overlay Compliance

The verification enforces hard rules defined in the documentation:

• Rule 1: Subtitles must remain visible and cannot be hidden behind overlays
• Rule 4: Overlays must be aligned and display the correct frames

The self-eval inspects the specific pixel regions where subtitles should appear to ensure they are not obscured by graphic overlays.

Implementation Details

The self-eval loop spans three key files in the repository:

• SKILL.md (lines 91‑99): Defines the high-level workflow, hard rules, and the three-pass retry limit
• helpers/timeline_view.py: Provides the CLI used to extract frames, waveforms, and overlay renders for a given time window
• helpers/render.py: Orchestrates the rendering process, activates preview mode, and invokes the self-eval loop after generation

Practical Usage Example

While the self-eval loop runs automatically during preview renders, you can manually inspect specific cut boundaries using the following commands:

# 1. Render a quick preview (triggers automatic self-eval)

render.py --preview -o out.mp4

# 2. Manually run timeline_view on a cut at 12.3s (±1.5s window)

timeline_view out.mp4 \
  --start 10.8 --end 13.8 \
  --n-frames 10 \
  -o cut_12.3.png

# 3. Inspect the generated filmstrip for visual/audio issues

display cut_12.3.png

The --preview flag in render.py automatically executes the full verification pipeline, including the ffprobe duration check and the three-pass retry logic.

Summary

• The self-eval loop automatically validates every preview render before presenting it to users, preventing low-quality outputs from reaching the interface.
• Verification occurs within a ±1.5 s window around each cut boundary, using timeline_view to generate frame strips and waveform data.
• The system checks for visual discontinuity, audio pops exceeding 30 ms fades, subtitle visibility (Rule 1), and overlay alignment (Rule 4).
• Failed renders trigger automatic fixes and re-rendering, with a hard limit of three passes before surfacing errors to the user.
• Implementation relies on helpers/timeline_view.py for inspection and helpers/render.py for orchestration, as documented in SKILL.md lines 91‑99.

Frequently Asked Questions

What triggers the self-eval loop to re-render a video?

The loop re-renders when timeline_view detects visual discontinuity, audio waveform spikes that indicate pops, subtitles hidden behind overlays (Rule 1 violations), or mis-aligned overlays (Rule 4 violations). Additionally, if ffprobe reports a duration mismatch with the EDL, the system triggers a retry.

How many times does video-use retry failed verifications?

According to the source documentation in SKILL.md lines 97‑99, the self-eval loop allows a maximum of three passes. After the third attempt, any persistent issues are surfaced to the user as errors rather than attempting further automatic fixes.

What is the ±1.5 second window used for in cut-boundary verification?

The ±1.5 second window provides temporal context around each cut boundary, allowing timeline_view to generate a 10-frame film-strip that captures the transition state. This window is wide enough to detect flash frames or audio pops that occur at the cut point while remaining narrow enough to process efficiently.

Which files contain the verification logic for the self-eval loop?

The verification logic is split across helpers/timeline_view.py, which handles frame extraction and waveform analysis, and helpers/render.py, which orchestrates the rendering and retry logic. The behavior is specified in SKILL.md at lines 91‑99, which defines the hard rules and three-pass limit.

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