dcosnet
/
OpenTranscode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
OpenTranscode/quickstart.md

5.6 KiB
Raw Permalink Blame History

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

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

Step 2 — Install PySide6

pip install PySide6

If you hit permission errors, use a venv:

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

Step 3 — Launch

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:

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.

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.