encoding-scripts/README_av1_opus_encoder.md

AV1 Opus Encoder

Overview

av1_opus_encoder.py is a comprehensive, all-in-one batch-processing script for MKV files, designed for modern encoding workflows. It automates the entire pipeline, including advanced video encoding with AV1 (via av1an), sophisticated audio conversion to Opus, and intelligent handling of both Variable Frame Rate (VFR) and Constant Frame Rate (CFR) sources. To ensure transparency and aid in debugging, the script also preserves detailed, per-file logs of the entire conversion process.

This script serves as the primary tool for creating high-quality, efficient AV1/Opus encodes.

Features

• Advanced Video Encoding: Uses a robust VapourSynth-based pipeline with av1an and SVT-AV1 for efficient, high-quality AV1 video encoding.
• VFR Handling: Automatically detects Variable Frame Rate (VFR) sources using mediainfo and converts them to Constant Frame Rate (CFR) with HandBrakeCLI before encoding, ensuring broader playback compatibility.
• Autocrop: Includes an optional --autocrop flag to intelligently detect and remove black bars, maximizing encoding efficiency.
• Detailed Logging: Creates a separate, detailed log file for each processed MKV in the conv_logs/ directory, capturing the full terminal output for easy review.
• Loudness-Normalized Audio: Converts all audio tracks (except AAC/Opus) to the Opus format, using EBU R 128 loudness normalization for a consistent listening experience.
• File Organization: Keeps your workspace tidy by automatically moving original files to original/ and completed encodes to completed/.
• Resumable & Efficient: The script processes files one by one and uses av1an's resume feature, making it easy to continue an encoding batch if it's interrupted.

Requirements

The following command-line tools must be installed and available in your system's PATH:

• ffmpeg
• ffprobe
• mkvmerge
• mkvpropedit
• opusenc
• mediainfo
• av1an
• HandBrakeCLI

Usage

1. Place your .mkv files in the same directory as the script.
2. Make the script executable (on Linux/macOS) by running chmod +x av1_opus_encoder.py.
3. Execute the script from your terminal:

   ./av1_opus_encoder.py
   

Optional Arguments

• --no-downmix: By default, the script downmixes surround sound audio (e.g., 5.1) to stereo. Use this flag to preserve the original audio channel layout.
• --autocrop: Automatically detect and crop black bars from video. The crop is applied to the UTVideo intermediate file.
• --speed: Override the default SVT-AV1 encoding speed (e.g., --speed slow).
• --quality: Override the default SVT-AV1 quality level (e.g., --quality high).
• --grain: Override the default SVT-AV1 film grain synthesis level (e.g., --grain 8).

Example with multiple arguments:

./av1_opus_encoder.py --autocrop --no-downmix --speed slow

Output

• Processed files are moved to the completed/ directory.
• Original files are moved to the original/ directory.
• Per-file logs are saved in the conv_logs/ directory.

Notes

• The script will check if a file can be decoded by ffmpeg before processing and will skip corrupted or unsupported files.
• The entire process, especially scene detection and AV1 encoding, can be very time-consuming and CPU-intensive.