conversion_project/README_RESTRUCTURE.md

AV1 Batch Video Transcoder

A clean, modular batch video transcoding system using NVIDIA's AV1 NVENC codec with intelligent audio and subtitle handling.

Project Structure

conversion_project/
├── main.py                 - CLI entry point for batch transcoding
├── config.xml              - Configuration (encoding settings, audio buckets, etc.)
│
├── core/                   - Core modules
│   ├── config_helper.py    - XML configuration loader
│   ├── logger_helper.py    - Logging setup
│   ├── process_manager.py  - Main transcoding orchestration
│   ├── encode_engine.py    - FFmpeg command builder and execution
│   ├── audio_handler.py    - Audio stream analysis and bitrate decisions
│   ├── video_handler.py    - Video resolution detection and scaling logic
│   └── hardware_helper.py  - Hardware detection (GPU/CPU)
│
├── /rename/                - Separate rename utility (rolling_rename.py)
├── /path_manager/          - GUI path management (kept separate from conversion)
│   ├── gui_path_manager.py
│   ├── transcode.bat
│   ├── paths.txt
│   └── cache/
│
├── logs/                   - Log files and conversion tracker CSV
├── processing/             - Temporary encoding files (cleaned up after move)
└── cache/ (removed)        - Folder cache now in /path_manager/cache

Quick Start

Basic Usage

# Encode a folder (smart mode: CQ first, bitrate fallback if size exceeds 75%)
python main.py "P:\tv\Show Name"

# Force CQ mode with specific quality
python main.py "P:\movies\Movie" --cq 30

# Force Bitrate mode
python main.py "P:\tv\Show" --m bitrate

# Explicit resolution
python main.py "P:\movies\Movie" --r 1080

# Test mode: encode first file only, show compression ratio, don't move files
python main.py "P:\tv\Show" --test

# Optional: tag audio streams with language code
python main.py "P:\tv\Show" --language eng

Features

• Hardware Encoding: NVIDIA av1_nvenc (8-bit yuv420p, preset p7)
• Smart Audio: Analyzes streams, re-encodes excessive bitrate, preserves good quality
• Smart Video: Detects source resolution, scales 4K→1080p, preserves lower resolutions
• Subtitle Detection: Auto-finds and embeds subtitles (vtt, srt, ass, ssa, sub)
  • Supports language-prefixed files: movie.en.vtt, movie.eng.vtt
  • Cleans up subtitle files after embedding
• Two-Phase Encoding (smart mode):
  • Phase 1: Try CQ mode for quality
  • Phase 2: Retry failed files with Bitrate mode
• File Tagging: Encodes output with - [EHX] suffix
• CSV Tracking: Detailed conversion log with compression ratios
• Automatic Cleanup: Deletes originals + subtitles after successful move

Configuration

Edit config.xml to customize:

• CQ Values: Per content type (tv_1080, tv_720, movie_1080, movie_720)
• Audio Buckets: Bitrate targets for stereo/multichannel
• Fallback Bitrates: Used in Phase 2 bitrate retry
• Subtitle Settings: Extensions to detect, codec for embedding
• Path Mappings: Windows ↔ Linux path conversion (optional)

Encoding Process (Per File)

1. Detect subtitles: Looks for matching .en.vtt, .srt, etc.
2. Analyze source: Resolution, audio streams, bitrates
3. FFmpeg encode:
   • Video: AV1 NVENC (8-bit yuv420p)
   • Audio: Per-stream decisions (copy or re-encode)
   • Subtitles: Embedded as SRT (if found)
4. Size check: Compare output vs original (default 75% threshold)
5. Move file: From temp folder → original location with - [EHX] suffix
6. Cleanup: Delete original file + subtitle file

Audio Encoding Logic

Stereo audio?
├─ YES + 1080p: [>192kbps] ENCODE to 192k AAC, [≤192k] COPY
├─ YES + 720p: [>160kbps] ENCODE to 160k AAC, [≤160k] COPY  
└─ NO (Multichannel): ENCODE to 384k/448k AAC (5.1)

Removed Features

• ❌ Sonarr/Radarr integration (was complex, removed for simplicity)
• ❌ Auto-rename based on Sonarr metadata
• ❌ Web UI (kept separate if needed in future)
• ❌ Rename functionality (moved to /rename folder)

Advanced Options

Test Mode

Encodes first file only, shows compression ratio, leaves file in temp folder:

python main.py "P:\tv\Show" --test

Useful for: Testing CQ values, checking quality before batch conversion.

Language Tagging (Optional)

Only tags audio if explicitly provided:

python main.py "P:\tv\Show" --language eng

Without --language flag, original audio metadata is preserved.

Resolution Override

Force specific output resolution:

python main.py "P:\movies" --r 720   # Force 720p
python main.py "P:\tv" --r 1080      # Force 1080p

Output Examples

Input File:

SupernaturalS07E21.mkv (size: 1.5GB)
SupernaturalS07E21.en.vtt (subtitle)

Output:

SupernaturalS07E21 - [EHX].mkv (size: 450MB, subtitle embedded)
(original files deleted)

Troubleshooting

Wrong Bitrate

Check CQ values in config.xml or use --cq override:

python main.py "P:\tv\Show" --cq 31

Subtitles Not Embedding

• Verify file is named correctly: filename.en.vtt or filename.vtt
• Check config.xml has subtitles enabled and extensions listed
• Check logs for "Found subtitle" message

Files Not Moving

Check if reduction ratio threshold (default 0.75) is exceeded:

python main.py "P:\tv\Show" --test  # Check ratio in Phase 1

If ratio is high, lower CQ value or use bitrate mode.

Logs

• logs/conversion.log: Detailed encoding info, errors, decisions
• logs/conversion_tracker.csv: Summary table of all conversions
• logs/conversion_failures.log: Failed file tracking