134 lines
3.0 KiB
Markdown
134 lines
3.0 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
cargo build --release
|
||
```
|
||
|
||
### Common commands
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
vid-repair rules lint
|
||
```
|
||
|
||
## Fixtures (Dev)
|
||
|
||
Generate fixtures locally (git‑ignored):
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
scripts/check.sh
|
||
```
|
||
|
||
This runs the full test suite and ruleset lint.
|