vid-repair/README.md

Vid-Repair

Vid-Repair is a cross‑platform CLI that scans video files for container/stream/decode problems and applies safe repairs using your system ffmpeg/ffprobe.

Quick Start (Regular Users)

Requirements

• ffmpeg and ffprobe available on PATH

Install

cargo build --release

Common commands

# Scan files or folders
vid-repair scan /path/to/videos

# Watch a folder and scan new/changed files once they finish writing
vid-repair scan --watch /path/to/videos

# Fix (safe policy, in-place)
vid-repair fix /path/to/videos

# Fix with aggressive policy (allows re-encode)
vid-repair fix --policy aggressive /path/to/videos

# JSON output (for scripts)
vid-repair scan --json /path/to/videos

Scan depth

# Quick scan (faster, less thorough)
vid-repair scan --scan-depth quick /path/to/videos

# Standard scan
vid-repair scan --scan-depth standard /path/to/videos

# Deep scan (default, full decode)
vid-repair scan --scan-depth deep /path/to/videos

Recursive vs non‑recursive

# Disable recursive scanning
vid-repair scan --no-recursive /path/to/videos

Exit codes

• 0 no issues
• 1 issues found
• 2 fix failed
• 3 fatal error

Config (Regular Users)

On first run, a commented TOML config is created in the XDG config directory:

• Linux: ~/.config/vid-repair/config.toml
• macOS: ~/Library/Application Support/vid-repair/config.toml
• Windows: %APPDATA%/vid-repair/config.toml

You can edit this file to set defaults like scan depth, include/exclude patterns, and watch behavior. CLI flags always override config values.

Rulesets (Regular Users)

Rulesets tell Vid‑Repair how to interpret ffmpeg error messages. They’re shipped with the app and already work out of the box.
You generally do not need to edit them unless you want to add your own rules or tune behavior.

If you do edit rulesets, run the linter:

vid-repair rules lint

Fixtures (Regular Users)

Fixtures are small, generated test videos used to validate the scanner.
You only need this if you are developing or testing changes.

If you want to generate them manually:

scripts/generate_fixtures.sh

---

Developer Guide

This section is for contributors and anyone building on the project.

Project layout

• vid-repair/ – CLI binary
• vid-repair-core/ – core library (scan, rules, fix, report, watch)
• rulesets/ – modular rule packs (TOML)
• scripts/ – helper scripts (fixtures, checks)

Rulesets (Dev)

Rules are data‑driven and split by domain in rulesets/*.toml.
Before shipping changes:

vid-repair rules lint

Fixtures (Dev)

Generate fixtures locally (git‑ignored):

scripts/generate_fixtures.sh

Use fixtures to validate scan logic and rule coverage. Add new fixtures for real‑world edge cases (truncated files, corrupted NAL units, etc.).

Tests

scripts/check.sh

This runs the full test suite and ruleset lint.