# AV1 Encoding Scripts ## Overview This repository contains Python scripts for batch-processing MKV files to encode video to AV1 and audio to Opus. The scripts prioritize high-quality encoding, handle complex audio track downmixing, VFR (Variable Frame Rate) conversions, and offer features like automatic cropping and resumable encoding. ## Scripts Overview * **`aom_opus_encoder.py`**: Uses the `aom` encoder (specifically designed for the `aom-psy101` fork) via `av1an`. It is tuned for high perceptual quality with specific psychovisual parameters and film grain synthesis. * **`svt_opus_encoder.py`**: Uses the `svt-av1` encoder (specifically designed for the `SVT-AV1-Essential` fork) via `av1an`. It provides a good balance between encoding speed and quality, and allows customization of speed, quality, and film-grain presets from the command line. ## Encoding Parameters Documentation For detailed information on the specific FFmpeg arguments, audio downmixing logic, VFR-to-CFR conversion processes, and the special SVT-AV1/AomEnc parameters used by these scripts, please refer to the [`parameters.md`](parameters.md) file. ## Prerequisites Both scripts require several external tools to be installed and available in your system's `PATH`: * **ffmpeg** & **ffprobe**: For video/audio extraction, filtering (cropdetect), and loudnorm analysis. * **mkvtoolnix** (`mkvmerge`, `mkvpropedit`): For remuxing the final MKV file. * **opusenc** (opus-tools): For encoding audio tracks to the Opus codec. * **mediainfo**: For extracting detailed media information (especially frame rate details). * **av1an**: The core chunking encoder used to run multiple encode workers in parallel. * **HandBrakeCLI**: Used as a fallback/pre-processor to convert VFR (Variable Frame Rate) video to CFR (Constant Frame Rate) before the main encode. * **ffmsindex** (ffms2): For indexing the intermediate UTVideo file for Vapoursynth. * **Vapoursynth**: Required by `av1an` as the frame server via the generated `.vpy` scripts. * *(Specific to `aom_opus_encoder.py`)*: **aom-psy101** encoder. You must download the correct version from [Damian101's aom-psy101 GitLab](https://gitlab.com/damian101/aom-psy101). * *(Specific to `svt_opus_encoder.py`)*: **SVT-AV1-Essential** encoder. You must download the correct version from [nekotrix's SVT-AV1-Essential GitHub](https://github.com/nekotrix/SVT-AV1-Essential/). ## Features * **Automated Batch Processing**: Simply place your `.mkv` files in the same directory as the script. The script will process them one by one. * **Resumable Encoding**: Because it uses `av1an`, if an encode is interrupted, you can restart the script, and it will resume from where it left off. * **Audio Normalization and Downmixing**: * Extracts audio tracks to FLAC. * Applies a 2-pass `loudnorm` normalization (Target: -23 LUFS, True Peak: -1 dB). * Downmixes 5.1/7.1 surround sound to stereo (unless `--no-downmix` is specified). * Encodes to Opus with bitrates automatically chosen based on the channel count (e.g., 128k for Stereo, 256k for 5.1). * Directly remuxes existing `aac` or `opus` tracks without re-encoding. * Preserves track languages, titles, and delays. * **VFR to CFR Conversion**: Detects Variable Frame Rate (VFR) media and automatically converts it to Constant Frame Rate (CFR) using HandBrakeCLI (virtually lossless `x264_10bit` CRF 0 intermediate) to prevent audio desync issues. * **Automatic Cropping**: Optional `--autocrop` flag detects black bars and determines the optimal cropping parameters before encoding. * **Organized Output**: * Completed files are moved to a `completed/` directory. * Original files are moved to an `original/` directory. * Per-file processing logs are saved in a `conv_logs/` directory. * Temporary files are automatically cleaned up upon success. ## Usage Place the script in the directory containing your `.mkv` files and execute it. ### `aom_opus_encoder.py` ```bash python aom_opus_encoder.py [options] ``` **Options:** * `--no-downmix`: Preserve original audio channel layout (do not downmix 5.1/7.1 to stereo). * `--autocrop`: Automatically detect and crop black bars from the video. * `--grain `: Set the `photon-noise` value for grain synthesis (default: 8). * `--crf `: Set the constant quality level (`cq-level`) for video encoding (default: 28). ### `svt_opus_encoder.py` ```bash python svt_opus_encoder.py [options] ``` **Options:** * `--no-downmix`: Preserve original audio channel layout (do not downmix 5.1/7.1 to stereo). * `--autocrop`: Automatically detect and crop black bars from the video. * `--speed `: Set the SVT-AV1 encoding speed preset (e.g., `slower`, `slow`, `medium`, `fast`, `faster`). Defaults to `slower`. * `--quality `: Set the SVT-AV1 encoding quality preset (e.g., `lowest`, `low`, `medium`, `high`, `higher`). Defaults to `medium`. * `--grain `: Set the `film-grain` value. Adjusts the film grain synthesis level. Defaults to 6. ## Process Workflow 1. **Preparation**: Scans for `.mkv` files and checks for required tools. 2. **Analysis**: Examines video and audio tracks using `ffprobe` and `mediainfo`. 3. **Video Processing**: * Runs crop detection (if `--autocrop` is enabled). * Converts VFR to CFR (if VFR is detected). * Extracts an intermediate lossless video (`utvideo`). * Encodes the video using `av1an`. 4. **Audio Processing**: * Remuxes AAC/Opus. * Normalizes, downmixes (if applicable), and encodes other formats to Opus. 5. **Muxing**: Combines the newly encoded video and audio tracks using `mkvmerge`, preserving synchronization delays, metadata, and languages. 6. **Cleanup**: Moves files to respective folders (`completed/`, `original/`) and deletes temporary working files. ## Notes - Encoding AV1 takes a significant amount of time and CPU resources. - Ensure you have sufficient disk space, as the scripts generate intermediate lossless `utvideo` files which can be very large depending on the length and resolution of the source media. ## License This project is licensed under the MIT License - see the [`LICENSE.md`](LICENSE.md) file for details.