OpenTranscode/quickstart.md

# Quickstart — OpenTranscode

Get from zero to your first batch encode in under 10 minutes.

## Prerequisites

- **Linux** (x86_64, any major distro)
- **Python 3.12+** with pip
- **~2 GB free disk** in `/tmp` (for av1an source build, if needed)
- **sudo access** (for system package installation)

## Step 1 — Get the Code

```bash
git clone https://git.dcos.net/dcosnet/open-transcode.git
cd open-transcode
```

## Step 2 — Install PySide6

```bash
pip install PySide6
```

If you hit permission errors, use a venv:

```bash
python -m venv .venv
source .venv/bin/activate
pip install PySide6
```

## Step 3 — Launch

```bash
python open-transcode.py
```

The window opens with the MMD3 console theme. The ENCODE button is disabled — the app needs to probe your system first.

## Step 4 — First-Run Auto-Setup

### What happens automatically

~500ms after launch, the app:

1. **Detects your distro** by reading `/etc/os-release` (Arch, Debian, Fedora, openSUSE, NixOS, or generic).
2. **Probes for binaries** — searches distro-specific paths for `av1an`, `ffmpeg`, and `ffprobe`.
3. **Checks av1an version** — needs ≥ 0.4.0 (for `--chunk-method` support).
4. **Probes FFmpeg libraries** — verifies libsvtav1, libvpx, libx265, libopus, libvorbis, and flac availability.
5. **If anything is missing**, spawns a background thread that:
   - Installs all required packages via your distro's package manager.
   - If av1an is too old, removes it and builds from source (git clone + cargo build).
   - Re-probes the environment after installation completes.

You'll see the log box filling with status messages. Wait for the ENCODE button to light up.

### NixOS (manual setup)

NixOS can't auto-install packages at runtime. Add this to your configuration:

```nix
environment.systemPackages = with pkgs; [
  ffmpeg-full av1an svt-av1 rav1e aom libvpx x265
  mkvtoolnix nasm gcc cmake git ninja cargo rustc
  opus libvorbis flac
];
```

Then rebuild: `sudo nixos-rebuild switch`

### Fedora / RHEL — RPM Fusion

If you're on Fedora or RHEL-like systems, the auto-prep installs RPM Fusion repos before attempting FFmpeg. This is handled automatically — just wait for it.

## Step 5 — Your First Encode

### 5a. Set up folders

The defaults are `~/Videos/INCOMING` (source) and `~/Videos/ARCHIVE` (output). Create them or click the browse buttons to pick your own.

```bash
mkdir -p ~/Videos/INCOMING ~/Videos/ARCHIVE
```

Drop some video files into `~/Videos/INCOMING`.

### 5b. Pick your settings

| Setting | Recommended first run | Why |
|---|---|---|
| VIDEO | AV1 (SVT-AV1) | Best compression, modern standard |
| PRESET | Medium | Good balance of speed and quality |
| AUDIO | Opus 128k | Excellent quality at low bitrate |
| CONTAINER | MKV | Universal, supports all codecs and subtitle formats |
| RESOLUTION | Original | Skip pre-scaling for fastest first run |
| SUBS | None | Skip subtitle muxing for first test |
| CRF knob | 30 | Reasonable file size reduction on most sources |
| AUDIO NORM knob | 0 (off) | No gain adjustment |

### 5c. Hit ENCODE

Click the amber `> ENCODE` button. The log box shows per-file progress:

```
> [1/5] Encoding: video1.mkv → /home/you/Videos/ARCHIVE/video1_archived.mkv
>   av1an: workers=7 encoder=svt_av1 chunk-method=select
>   ✓ video1.mkv — 1.2 GB → 340 MB (28.3%) duration match: 99.8%
> [2/5] Encoding: video2.mp4 → ...
```

### 5d. Verify output

Check `~/Videos/ARCHIVE/`. Each file should play correctly in mpv, VLC, or any modern player.

## Common First-Run Issues

### "ENCODE button stays disabled"

The environment probe found a critical issue. Check the log box for red/warning messages. Common causes:

- **No internet** — auto-prep can't fetch packages or clone av1an from git.
- **av1an build failed** — scroll up in the log for the cargo error. Usually a missing Rust toolchain.
- **FFmpeg missing libraries** — the auto-prep should install them. If not, manually install the FFmpeg "full" variant for your distro.

### "Codec greyed out in AUDIO dropdown"

The corresponding FFmpeg library isn't installed. For example, if FLAC is greyed out, install `flac` (Arch) or `flac libflac-dev` (Debian). The auto-prep handles this, but if you skipped it, re-launch and let it run.

### Encoding is slow

- **Try a faster preset** (Faster instead of Slow/Medium).
- **Raise the CRF** — higher = smaller file = faster encode (but lower quality).
- **Check your worker count** — logged at the start of each encode. It's `physical_cores - 1`. If it says 1, your CPU topology detection may have fallen back to a conservative estimate.

### Output file is much larger than expected

- **Lower the CRF** — you may have it set too low (high quality, large file).
- **x265/VP9 at low CRF** produces significantly larger files than AV1 at the same CRF.
- **FLAC audio** is lossless and can be 500 MB+ for a 2-hour movie. Use Opus instead.

## Next Steps

- **Try resolution scaling** — pick 1080p or 720p to normalize mixed-resolution batches.
- **Enable subtitles** — switch SUBS to "English" for forced-track soft subs.
- **Batch delete** — check "DELETE SOURCE AFTER VERIFY" to auto-remove originals after verified encoding. You'll get a confirmation dialog showing total file count and size before anything is deleted.
- **Audio normalization** — twist the AUDIO NORM knob if your sources have inconsistent volume. +3 dB is a good starting point for quiet sources.

## Keyboard & Mouse

- **CRF / Volume knobs** — click and drag, or scroll the mouse wheel.
- **Knobs snap to ticks** by default for precise values.
- **Log box** — scrollable, read-only. Copy text with mouse selection.