OpenTranscode/README.md

OpenTranscode

A single-file, batch transcoding GUI for Linux built with PySide6. Wraps av1an for chunk-parallel AV1/VP9/x265 encoding with a retro-futuristic MMD3 media console aesthetic.

Features

• Batch encoding — Drop a source folder, pick settings, hit encode. Processes every matching file recursively.
• Three open codecs — AV1 (SVT-AV1), VP9 (libvpx), x265 (HEVC) with per-codec preset selection.
• Config-driven profiles — Codecs, audio, containers, and resolutions defined as dataclass tables — no nested if/else chains.
• av1an chunk-parallel encoding — Scene-based chunking with multi-worker parallelism. Automatically detects --chunk-method support and scales workers to physical CPU cores minus one.
• Lossless intermediate pipeline — Resolution changes use a lossless libx264 ultrafast CRF 0 pre-scale pass (yuv420p10le) with duration integrity verification before the final encode.
• Forced subtitle muxing — Optional soft-subtitle remux post-encode. Prefers forced-disposition tracks. Container-aware: WebVTT for WebM, stream copy for MKV.
• Audio normalization — Rotary volume knob (-20 dB to +6 dB gain).
• Real-time FFmpeg library probing — Greys out audio codecs whose underlying FFmpeg libraries are missing.
• Distro-aware dependency management — Auto-detects Arch, Debian/Ubuntu, Fedora/RHEL/Rocky/Alma, openSUSE, and NixOS. Installs packages, handles av1an version conflicts, and builds from source when repos are stale.
• Post-encode integrity checks — Verifies output file size (≥ 5% of source) and duration (≥ 95% of source) before accepting. Failed outputs are deleted automatically.
• Batch delete with confirmation — Single pre-flight prompt showing file count and total size. Sources deleted only after individual verification passes.
• Custom radio-knob widgets — Retro rotary controls for CRF and audio normalization with snap-to-tick, glow indicators, and mouse/scroll interaction.
• MMD3 theme — Brushed aluminum, amber/green LED displays, beveled metallic panels via QSS.

Requirements

Dependency	Minimum Version	Purpose
Python	3.12+	Runtime
PySide6	6.6+	Qt6 GUI framework
av1an	0.4.0+	Chunk-parallel encoder frontend
FFmpeg	5.0+ (with libsvtav1, libvpx, libx265, libopus, libvorbis, flac)	Encoding, probing, remuxing
ffprobe	(bundled with FFmpeg)	Stream analysis and validation
mkvtoolnix	any	MKV container support
Rust/Cargo	latest stable	Building av1an from source (if repo version is stale)

Per-Distro Package Lists

Arch / Manjaro / Endeavouros / Garuda / CachyOS: ffmpeg mkvtoolnix-cli nasm cython gcc cmake git ninja python-pip svt-av1 rav1e aom libvpx x265 libopus libvorbis flac

Debian / Ubuntu / Linux Mint / Pop!_OS: ffmpeg av1an mkvtoolnix svt-av1 rav1e aom-tools libvpx-tools x265 nasm gcc cmake git cargo rustc

Fedora: ffmpeg mkvtoolnix svt-av1 rav1e aom libvpx x265 nasm gcc cmake git ninja-build cargo rustc (requires RPM Fusion)

RHEL / CentOS / Rocky / Alma: Same as Fedora, plus epel-release and RPM Fusion.

openSUSE (Tumbleweed/Leap): ffmpeg av1an mkvtoolnix svt-av1 rav1e aom-tools libvpx-tools x265 nasm gcc cmake git ninja cargo rustc (requires Packman repo)

NixOS: Manual configuration required — see quickstart.

All distros: if the packaged av1an is below 0.4.0, the app automatically builds from git.

Install & Run

# Clone the repo
git clone https://github.com/YOUR_USER/open-transcode.git
cd open-transcode

# Install Python dependency
pip install PySide6

# Run — dependency auto-install triggers on first launch
python open-transcode-master.py

On first launch, if av1an or FFmpeg is missing, the app detects your distro and offers to install everything automatically (Arch, Debian, Fedora, openSUSE). NixOS users will see a config snippet to paste into their configuration.

Project Structure

open-transcode/
├── open-transcode-master.py   # Single-file application (~2800 lines)
├── README.md                  # This file
├── quickstart.md              # Setup & first-encode walkthrough
├── LICENSE                    # AGPL-3.0
└── .gitignore                 # Python/Qt/OS artifacts

How It Works

Encoding Pipeline

Source file
  │
  ├─ ffprobe pre-validation (skip if no video stream or < 0.5s)
  │
  ├─ [If resolution != Original]
  │   └─ Lossless pre-scale → {file}.scaled_tmp.mkv
  │       (libx264 ultrafast CRF 0, yuv420p10le, scale+pad filter)
  │       └─ Duration integrity check (≥ 95% of source)
  │
  ├─ av1an encode (chunk-parallel, scene-based splitting)
  │   └─ Workers: physical_cores - 1
  │
  ├─ Post-encode verification
  │   ├─ Size check: output ≥ 5% of source
  │   └─ Duration check: output ≥ 95% of source
  │
  ├─ [If subtitle language selected]
  │   └─ Soft subtitle remux (forced track preferred)
  │       ├─ MKV: -c:s copy (any codec)
  │       └─ WebM: -c:s webvtt (container requirement)
  │
  └─ [If delete-source enabled]
      └─ Delete source (only after verification passes)

Distro Auto-Detection

On startup, reads /etc/os-release and matches against known distro families. Each family has:

• Package manager and install command template
• Extra binary search paths (e.g. ~/.cargo/bin for Rust-built tools)
• Distro-specific av1an encoder name quirks
• A dedicated *_prep_deps() function with fine-grained package installation

Config-Driven Profiles

All codec/container/audio/resolution options are defined as @dataclass tables:

• VIDEO_CODECS — Label, av1an encoder name, CRF range, default CRF, params function, preset map
• AUDIO_PROFILES — Label + FFmpeg parameter tokens
• CONTAINER_PROFILES — Label + file extension
• RESOLUTION_PRESETS — Label, category (standard/wide/ultrawide/original), dimensions
• SUBTITLE_OPTIONS — Label + ISO 639-2 language code (or None)

The UI indexes into these tables — zero conditional logic for profile selection.

Supported Input Formats

Default: .mp4 .mkv .avi .mov .ts .m4v .flv .wmv .webm .mpg .mpeg

Configurable at runtime via the FILTER field in the UI (comma-separated extensions).

Supported Output Formats

Container	Video Codecs	Audio Codecs	Subtitles
MKV (.mkv)	AV1, VP9, x265	Opus, Vorbis, FLAC	Any (stream copy)
WebM (.webm)	AV1, VP9	Opus, Vorbis, FLAC	WebVTT only

UI Controls

Control	Type	Range / Options
SOURCE / SINK	Path fields + browse	Any directory
VIDEO	Combo	AV1 (SVT-AV1), VP9, x265 (HEVC)
PRESET	Combo	4 per codec (e.g. Slow/Medium/Fast/Faster)
AUDIO	Combo	Opus 96k/128k/64k, Vorbis 128k/192k, FLAC
CONTAINER	Combo	MKV, WebM
RESOLUTION	Combo	Original, 720p–4K (16:9 / 21:9 / 32:9)
SUBS	Combo	None, English (forced track preferred)
CRF	Rotary knob	18–52 (codec-dependent range)
AUDIO NORM	Rotary knob	-20 dB to +6 dB (0 = off)
DELETE SOURCE	Checkbox	Per-batch confirmation prompt

Troubleshooting

av1an build fails: Ensure Rust is installed (rustup) and you have ~2 GB of free disk space in /tmp. The build takes 5–15 minutes depending on hardware.

Codec greyed out: The corresponding FFmpeg library is missing. Install it via your package manager or re-run the auto-prep.

"chunk-method not recognized": Your av1an is below 0.4.0. The auto-prep should handle this by building from git. If it doesn't, manually remove the packaged av1an and rebuild.

WebM + non-WebVTT subtitles fail: WebM only supports WebVTT subtitles. The app auto-converts during remux. If the source subtitle codec can't be converted, the mux is silently skipped.

Permission denied on av1an install: The git build attempts sudo cp to /usr/local/bin. Ensure your user has sudo access, or manually copy the binary from /tmp/av1an-build/target/release/av1an.

License

AGPL-3.0 — see LICENSE.