encoding-scripts/README_MkvOpusEnc.md

MkvOpusEnc

Overview

MkvOpusEnc.py is a cross-platform Python script designed for batch-processing the audio tracks within MKV files. It automatically scans the current directory for MKV files and processes them sequentially. The script intelligently converts various audio codecs to the highly efficient Opus format while preserving all other tracks (video, subtitles, etc.) and metadata.

Features

• Automated Batch Processing: Automatically finds and processes all MKV files in its directory, one by one.
• Intelligent Codec Handling:
  • Remuxes existing AAC and Opus tracks without re-encoding to preserve quality.
  • Re-encodes all other audio formats (DTS, AC3, TrueHD, FLAC, etc.) to Opus.
• Advanced Downmixing: Includes an optional --downmix flag that converts multi-channel audio (5.1, 7.1) to stereo using a dialogue-boosting formula.
• Audio Normalization: Uses SoX to normalize audio levels for a consistent listening experience.
• Metadata Preservation: Carefully preserves audio track metadata such as titles, language tags, and delay/sync information.
• Detailed Logging: Creates a separate, detailed log file for each processed MKV in the conv_logs/ directory, capturing the full terminal output and conversion details for easy review.
• File Organization: Automatically moves the original source files to an original/ directory and the newly processed files to a completed/ directory, keeping your workspace clean.
• Cross-Platform: As a Python script using common command-line tools, it is designed to work on Windows, macOS, and Linux.

Requirements

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

• ffmpeg
• ffprobe
• mkvmerge
• sox
• opusenc
• mediainfo

Usage

1. Place your .mkv files in the same directory as the script.

2. Execute the script from your terminal:

   python MkvOpusEnc.py
   

Optional Arguments

• --downmix: By default, the script preserves the original audio channel layout. Use this flag to downmix multi-channel audio to stereo.

  Example:

  python MkvOpusEnc.py --downmix
  

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, containing detailed information about:
  • Original audio track properties (codec, bitrate, channels)
  • Track titles, languages, and delay information
  • Conversion details for each track, including target bitrates
  • Any errors or warnings encountered during processing