brandtech-sandbox-video-subtitle-generator/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Video Subtitle Processor V2.0 - a PHP-based web application that provides automated video subtitle generation, translation, and burning functionality. The system uses AI tools (Whisper for transcription, DeepL for translation) and FFmpeg for video processing.

⚠️ This is marked as "AI Sandbox - NOT FOR PRODUCTION USE"

Architecture

Core Components

1. Web Interface (index.php) - Dual-tab interface for:

   • Translate & Burn: Upload video → AI transcription → translation → subtitle burning
   • Reburn Subtitles: Upload video + SRT file → burn subtitles with custom styling

2. Backend Processing:

   • process.php - Handles translate & burn workflow
   • process-reburn.php - Handles reburn workflow with existing SRT files
   • logger.php - Singleton logging system with daily log rotation

3. Python AI Scripts:

   • Video-Translator-options.py - Whisper transcription + DeepL translation + FFmpeg burning
   • Video-Translator-Rerun.py - FFmpeg subtitle burning only

4. Configuration:

   • config.php - Defines paths, API keys, file retention, logging settings

Key Dependencies

• Python Environment: Requires Python virtual environment with Whisper, DeepL, FFmpeg-python
• FFmpeg: System-level installation required for video processing
• DeepL API: Translation service (API key in config.php)

Directory Structure

├── uploads/          # Temporary video uploads
├── processed/        # Output videos (organized by job ID)
├── subtitles/        # Generated SRT files
├── logs/            # Application logs (daily rotation)
├── fonts/           # Custom fonts directory
└── styles.css       # Frontend styling with dark mode

Development Commands

Environment Setup

# Ensure FFmpeg is installed
brew install ffmpeg  # macOS
sudo apt install ffmpeg  # Ubuntu

# Python virtual environment should be set up with:
pip install whisper deepl-python ffmpeg-python

Key File Processing Paths

• Video uploads: uploads/ → processed/{job_id}/output.mp4
• Subtitle generation: subtitles/{filename}_english.srt and {filename}_translated.srt
• Logs: logs/app_{YYYY-MM-DD}.log

Configuration Notes

• File retention: 2-24 hours (see FILE_RETENTION_HOURS in config)
• Upload limits: 500MB max file size
• Supported formats: MP4, AVI, MKV, MOV
• Virtual environment paths differ between process.php and process-reburn.php

Key Features

Subtitle Styling Options

Both workflows support extensive styling customization:

• Font family (with system font detection via fc-list)
• Font size, text color, outline color, outline width
• Position (top/bottom)
• ASS subtitle format for advanced styling

Automatic Cleanup

• Old files are automatically cleaned up based on FILE_RETENTION_HOURS
• Cleanup runs on each request for uploads, processed files, and subtitles

Error Handling

• Comprehensive logging via Logger singleton
• JSON API responses for frontend
• File validation and environment checks

Important Security Notes

• DeepL API Key: Currently hardcoded in both config.php and Python files
• File permissions: Uses 0777 permissions extensively
• Upload validation: Basic file extension and size checks implemented
• Path sanitization: Uses escapeshellarg() for shell commands

Development Tips

• Testing: No automated test framework - manual testing required
• Logging: Check logs/app_{date}.log for debugging
• Virtual environments: Different paths configured in each processor file
• Font management: System fonts automatically detected and provided to frontend