# recscripts

FFmpeg encode helpers for FPV recordings (HDZero, Analog, Walksnail).

## Install

Requires [ffmpeg](https://ffmpeg.org/) (includes `ffprobe`) on your PATH.

```sh
uv pip install -e .
```

## Commands

### `hdzero`

Encode HDZero recordings with denoise, scale, and sharpen.

```sh
hdzero <input> <output> [options]
```

**Options**

| Flag                         | Default | Description                          |
| ---------------------------- | ------- | ------------------------------------ |
| `-ss <time>`                 | —       | Start time (e.g. `00:01:30` or `90`) |
| `-to <time>`                 | —       | End time (e.g. `00:02:00` or `120`)  |
| `--crop`                     | off     | Crop to 4:3                          |
| `--no-audio`                 | off     | Strip audio                          |
| `--height <px>`              | `1080`  | Output height                        |
| `--crf <n>`                  | `23`    | Quality (lower = better)             |
| `--preset <name>`            | `fast`  | Encoder preset                       |
| `--gpu [nvidia\|amd\|intel]` | off     | Use GPU encoder                      |
| `--threads <n>`              | all     | Limit CPU threads                    |
| `-n`, `--dry-run`            | off     | Print ffmpeg command without running |

**Examples**

```bash
# Basic encode
hdzero VID_0013.TS output.mp4

# Crop to 4:3, strip audio
hdzero VID_0013.TS output.mp4 --crop --no-audio

# Trim a clip
hdzero VID_0013.TS clip.mp4 -ss 00:01:00 -to 00:02:30

# GPU encode (NVIDIA)
hdzero VID_0013.TS output.mp4 --gpu

# Limit CPU usage
hdzero VID_0013.TS output.mp4 --threads 4
```

---

### `realesrgan`

AI upscaler using [Real-ESRGAN](https://github.com/xinntao/Real-ESRGAN) (NCNN
portable executable). Upscales video by extracting frames, running Real-ESRGAN
on each frame, then reassembling with original audio.

Place the NCNN executable in `.tools/realesrgan-ncnn-vulkan-*/`.

```sh
realesrgan <input> <output> [options]
```

**Options**

| Flag             | Default | Description                 |
| ---------------- | ------- | --------------------------- |
| `-ss <time>`     | —       | Start time                  |
| `-to <time>`     | —       | End time                    |
| `--model <name>` | `x4`    | Model (see below)           |
| `--gpu <id>`     | `0`     | GPU device ID, `-1` for CPU |
| `--crf <n>`      | `18`    | Output CRF quality          |

**Models**

| Flag              | Model                   | Scale | Best for                 |
| ----------------- | ----------------------- | ----- | ------------------------ |
| `x4`              | realesrgan-x4plus       | 4x    | Real-world footage (FPV) |
| `x4-anime`        | realesrgan-x4plus-anime | 4x    | Animation                |
| `x2` / `video-x2` | realesr-animevideov3-x2 | 2x    | Animation video          |
| `x3` / `video-x3` | realesr-animevideov3-x3 | 3x    | Animation video          |
| `video-x4`        | realesr-animevideov3-x4 | 4x    | Animation video          |

**Examples**

```bash
# Upscale a clip (recommended model for FPV)
realesrgan VID_0013.TS output.mp4 --model x4

# Test on a short segment first
realesrgan VID_0013.TS test.mp4 --model x4 -ss 00:01:00 -to 00:01:10

# CPU only
realesrgan VID_0013.TS output.mp4 --gpu -1
```

---

## To investigate

### SeedVR

[ByteDance-Seed/SeedVR](https://github.com/ByteDance-Seed/SeedVR) — video
super-resolution via diffusion model. Potentially much higher quality than
Real-ESRGAN but significantly heavier:

- Requires Python 3.10, PyTorch, `flash_attn`, `apex` (Linux/CUDA only)
- Minimum 1× H100-80G for 720p; 4× H100 for 1080p+
- Not natively runnable on Windows — needs WSL2 or a Linux machine