From 4375be641edaf4a5298c66896f4ece5a9c5d9284 Mon Sep 17 00:00:00 2001
From: pat-e <pat-e@pat-e.net>
Date: Wed, 16 Jul 2025 23:11:04 +0200
Subject: [PATCH] updated readme

---
 README.md | 83 ++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 49 insertions(+), 34 deletions(-)

diff --git a/README.md b/README.md
index 7cdc3ea..8eabb35 100644
--- a/README.md
+++ b/README.md
@@ -1,62 +1,77 @@
-# anime_audio_encoder.py
+# Anime Audio Encoder
 
 ## Overview
 
-`anime_audio_encoder.py` is a batch-processing script for MKV files, designed for anime encoding workflows. It automates video encoding (with AV1 via SVT-AV1 and `av1an`), audio conversion (to Opus with normalization and optional downmixing), and preserves detailed per-file logs. The script also handles VFR-to-CFR conversion using HandBrakeCLI when needed.
+anime_audio_encoder.py is a comprehensive batch-processing script for MKV files, specifically tailored for modern anime 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.
 
 ## Features
 
-- **Video encoding**: Uses UTVideo intermediate, VapourSynth, and AV1 encoding via `av1an` and SVT-AV1.
-- **Audio processing**: Converts non-Opus/AAC tracks to normalized Opus, with optional downmixing for surround audio.
-- **VFR handling**: Detects Variable Frame Rate sources and converts to Constant Frame Rate using HandBrakeCLI.
-- **Logging**: Creates a log file for each processed MKV in the `conv_logs` directory.
-- **Cleanup**: Moves original files to `original/`, completed files to `completed/`, and deletes temporary files.
+*   **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.
+
+*   **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.
+
+*   **Sophisticated Audio Processing:** Converts common audio formats to normalized Opus files. It provides an option to downmix surround sound to stereo or preserve the original channel layout.
+
+*   **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 tools must be installed and available in your `PATH`:
+The following command-line tools must be installed and available in your system's PATH:
 
-- ffmpeg
-- ffprobe
-- mkvmerge
-- mkvpropedit
-- sox
-- opusenc
-- mediainfo
-- av1an
-- HandBrakeCLI
+*   ffmpeg
+
+*   ffprobe
+
+*   mkvmerge
+
+*   mkvpropedit
+
+*   sox
+
+*   opusenc
+
+*   mediainfo
+
+*   av1an
+
+*   HandBrakeCLI
 
 ## Usage
 
-Place your `.mkv` files in the working directory. Run the script:
+1.  Place your `.mkv` files in the same directory as the script.
 
-```sh
-python3 anime_audio_encoder.py
+2.  Make the script executable by running `chmod +x anime_audio_encoder.py`.
+
+3.  Execute the script from your terminal:
+
+```bash
+./anime_audio_encoder.py
 ```
 
 ### Optional Arguments
 
-- `--no-downmix`  
-  Preserve original audio channel layout (do not downmix surround audio to stereo).
+*   `--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.
 
-  Example:
+Example:
 
-```sh
-python3 anime_audio_encoder.py --no-downmix
+```bash
+./anime_audio_encoder.py --no-downmix
 ```
 
 ## Output
 
-- Processed files are moved to the `completed/` directory.
-- Originals are moved to the `original/` directory.
-- Per-file logs are saved in the `conv_logs/` directory.
+*   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 skip files that cannot be decoded by ffmpeg.
-- Temporary files are cleaned up automatically after processing.
-- Scene detection and AV1 encoding may take a long time depending on file size and system performance.
+*   The script will check if a file can be decoded by ffmpeg before processing and will skip corrupted or unsupported files.
 
-## License
-
-This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
\ No newline at end of file
+*   The entire process, especially scene detection and AV1 encoding, can be very time-consuming and CPU-intensive.
\ No newline at end of file