153 lines
5.6 KiB
Markdown
153 lines
5.6 KiB
Markdown
# 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. |