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

```bash
# 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:

```bash
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:

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

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

### Resolution Override

Force specific output resolution:

```bash
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:

```bash
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:

```bash
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