updated readme

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.
+*   **Advanced Video Encoding:** Uses a robust VapourSynth-based pipeline with av1an and SVT-AV1 for efficient, high-quality AV1 video encoding.
-- **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.
+*   **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.
-- **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.
+*   **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
+*   ffmpeg
-- ffprobe
+
-- mkvmerge
+*   ffprobe
-- mkvpropedit
+
-- sox
+*   mkvmerge
-- opusenc
+
-- mediainfo
+*   mkvpropedit
-- av1an
+
-- HandBrakeCLI
+*   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
+2.  Make the script executable by running `chmod +x anime_audio_encoder.py`.
-python3 anime_audio_encoder.py
+
+3.  Execute the script from your terminal:
+
+```bash
+./anime_audio_encoder.py
 ```
 
 ### Optional Arguments
 
-- `--no-downmix`  
+*   `--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.
-  Preserve original audio channel layout (do not downmix surround audio to stereo).
 
 Example:
 
-```sh
+```bash
-python3 anime_audio_encoder.py --no-downmix
+./anime_audio_encoder.py --no-downmix
 ```
 
 ## Output
 
-- Processed files are moved to the `completed/` directory.
+*   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.
+*   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.
+*   The script will check if a file can be decoded by ffmpeg before processing and will skip corrupted or unsupported files.
-- 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.
 
-## License
+*   The entire process, especially scene detection and AV1 encoding, can be very time-consuming and CPU-intensive.
-
-This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.