# Technical Overview

## 🏗 Architecture

The project is modularized into specialized Python scripts:

*   **`main.py`**: The entry point. Manages the batch processing loop and job tracking.
*   **`extractor.py`**: Media handling via FFmpeg. Responsible for audio extraction and subtitle embedding. Contains the "Flatpak Escape" logic.
*   **`transcriber.py`**: Integration with `openai-whisper`. Manages GPU health checks and model loading.
*   **`translator.py`**: The AI translation engine. Implements the 4-tier fallback logic (Gemini -> Google -> Ollama -> MyMemory).
*   **`utils.py`**: Shared utilities for encoding detection (chardet), port checking, and service health monitoring.
*   **`tracker.py`**: Persistence layer using SQLite/SQLAlchemy to track job status across runs.

## 🛡 Safety Mechanisms

1.  **Duration Match Check**: Uses `ffprobe` to ensure the final subbed video length matches the original source.
2.  **File Size Sanity**: Rejects any remux operation that results in a file < 80% of the original size (preventing video stream loss).
3.  **SRT Health Check**: Compares the last timestamp of the translated SRT against the original transcript to detect partial/truncated translations.
4.  **Encoding Detection**: Uses `chardet` to reliably read foreign subtitle files without manual configuration.

## 🐳 Flatpak / Sandbox Support

Since this project is designed for Bazzite/Atomic distros, all system-level calls (`ffmpeg`, `ffprobe`, `ollama`) are wrapped in a check that detects the presence of `/.flatpak-info`. If found, it automatically prefixes commands with `flatpak-spawn --host` to utilize system-installed binaries.

## 💾 Database Schema

The `job_history.db` tracks:
- `file_path`: Absolute path to source.
- `status`: PENDING, PROCESSING, COMPLETED, FAILED.
- `step_status`: Individual status for Extract, Transcribe, Translate, and Embed steps.
- `error_message`: Captured stack traces for failed jobs.