Video Subtitle Processor V2.0 - Production Installation Guide

Overview

The Video Subtitle Processor V2.0 is a PHP-based web application that provides automated video subtitle generation, translation, and burning functionality. It combines AI transcription (Whisper), translation (DeepL), and video processing (FFmpeg) into a unified web interface.

Key Features

• Dual Processing Modes:

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

• AI-Powered Processing:

  • OpenAI Whisper for speech-to-text transcription
  • DeepL API for high-quality translation (46+ supported languages)
  • Advanced subtitle styling with ASS format support

• Production Features:

  • Automatic file cleanup based on retention policies
  • Comprehensive logging with daily rotation
  • System font detection and custom font support
  • Dark mode responsive web interface

System Requirements

Operating System

• Ubuntu 20.04 LTS or newer (recommended)
• CentOS 8 or newer
• Debian 11 or newer

Hardware Requirements (Minimum)

• CPU: 4 cores (8 recommended for large video files)
• RAM: 8GB (16GB+ recommended for Whisper processing)
• Storage: 50GB+ free space (videos require significant temporary storage)
• Network: Stable internet connection for DeepL API calls

Software Dependencies

• Apache 2.4 with mod_php or Nginx with PHP-FPM
• PHP 8.0+ with required extensions
• Python 3.8+ with pip
• FFmpeg 4.4+ with encoding support
• fontconfig for system font detection

Pre-Installation Setup

1. System Update

# Ubuntu/Debian
sudo apt update && sudo apt upgrade -y

# CentOS/RHEL
sudo dnf update -y

2. Install Core Dependencies

# Ubuntu/Debian
sudo apt install -y apache2 php8.1 php8.1-cli php8.1-common php8.1-mysql \
    php8.1-zip php8.1-gd php8.1-mbstring php8.1-curl php8.1-xml \
    python3 python3-pip python3-venv ffmpeg fontconfig-config \
    fonts-liberation fonts-dejavu-core

# CentOS/RHEL
sudo dnf install -y httpd php php-cli php-common php-mysql php-zip \
    php-gd php-mbstring php-curl php-xml python3 python3-pip \
    ffmpeg fontconfig liberation-fonts dejavu-fonts-common

3. Verify FFmpeg Installation

ffmpeg -version
# Should show version 4.4 or newer

4. Configure PHP Settings

Edit /etc/php/8.1/apache2/php.ini (Ubuntu) or /etc/php.ini (CentOS):

# File Upload Settings
upload_max_filesize = 500M
post_max_size = 500M
max_execution_time = 600
max_input_time = 600
memory_limit = 2G

# Security Settings
allow_url_fopen = Off
allow_url_include = Off
expose_php = Off

Installation Steps

1. Create Application Directory

sudo mkdir -p /var/www/html/subtitle-processor
sudo chown -R www-data:www-data /var/www/html/subtitle-processor
cd /var/www/html/subtitle-processor

2. Deploy Application Files

# Copy all application files to /var/www/html/subtitle-processor/
# Ensure the following structure:
# ├── config.php
# ├── index.php
# ├── process.php
# ├── process-reburn.php
# ├── logger.php
# ├── Video-Translator-options.py
# ├── Video-Translator-Rerun.py
# ├── requirements.txt
# ├── styles.css
# ├── uploads/
# ├── processed/
# ├── subtitles/
# ├── logs/
# └── fonts/

3. Set Up Python Virtual Environment

cd /var/www/html/subtitle-processor

# Create virtual environment
sudo -u www-data python3 -m venv venv

# Activate virtual environment
sudo -u www-data bash -c "source venv/bin/activate && pip install --upgrade pip"

# Install Python dependencies
sudo -u www-data bash -c "source venv/bin/activate && pip install -r requirements.txt"

# Verify installation
sudo -u www-data bash -c "source venv/bin/activate && python -c 'import whisper, deepl, ffmpeg; print(\"All dependencies installed successfully\")'"

4. Configure DeepL API Key

⚠️ SECURITY CRITICAL: Replace the hardcoded API key with your production key.

Edit config.php:

define('DEEPL_API_KEY', 'your-production-deepl-api-key-here');

Edit Video-Translator-options.py:

DEEPL_API_KEY = "your-production-deepl-api-key-here"

5. Set Directory Permissions

sudo chown -R www-data:www-data /var/www/html/subtitle-processor
sudo chmod -R 755 /var/www/html/subtitle-processor
sudo chmod -R 775 /var/www/html/subtitle-processor/uploads
sudo chmod -R 775 /var/www/html/subtitle-processor/processed
sudo chmod -R 775 /var/www/html/subtitle-processor/subtitles
sudo chmod -R 775 /var/www/html/subtitle-processor/logs
sudo chmod -R 775 /var/www/html/subtitle-processor/fonts

6. Configure Apache Virtual Host

Create /etc/apache2/sites-available/subtitle-processor.conf:

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/html/subtitle-processor
    
    <Directory /var/www/html/subtitle-processor>
        AllowOverride All
        Require all granted
        
        # PHP Configuration
        php_value upload_max_filesize 500M
        php_value post_max_size 500M
        php_value max_execution_time 600
        php_value max_input_time 600
        php_value memory_limit 2G
    </Directory>
    
    # Security Headers
    Header always set X-Content-Type-Options nosniff
    Header always set X-Frame-Options DENY
    Header always set X-XSS-Protection "1; mode=block"
    
    # Logging
    ErrorLog ${APACHE_LOG_DIR}/subtitle-processor_error.log
    CustomLog ${APACHE_LOG_DIR}/subtitle-processor_access.log combined
</VirtualHost>

Enable the site:

sudo a2ensite subtitle-processor
sudo a2enmod rewrite headers
sudo systemctl reload apache2

7. Configure SSL (Production Required)

Install SSL certificate (using Let's Encrypt):

sudo apt install certbot python3-certbot-apache
sudo certbot --apache -d your-domain.com

8. Set Up SystemD Service

Copy the provided subtitle-processor.service to /etc/systemd/system/:

sudo cp subtitle-processor.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable subtitle-processor
sudo systemctl start subtitle-processor

Verify service status:

sudo systemctl status subtitle-processor

9. Configure Firewall

# Ubuntu (UFW)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

# CentOS (firewalld)
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Post-Installation Configuration

1. Test System Components

Test PHP Configuration:

curl -s http://your-domain.com/info.php | grep -E "(upload_max_filesize|post_max_size|max_execution_time)"

Test Python Environment:

sudo -u www-data bash -c "cd /var/www/html/subtitle-processor && source venv/bin/activate && python Video-Translator-options.py --help"

Test FFmpeg:

sudo -u www-data ffmpeg -version

2. Configure Log Rotation

Create /etc/logrotate.d/subtitle-processor:

/var/www/html/subtitle-processor/logs/*.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    create 644 www-data www-data
}

3. Set Up Automated Cleanup (Cron)

Add to www-data crontab:

sudo crontab -u www-data -e

Add this line:

0 2 * * * find /var/www/html/subtitle-processor/uploads -type f -mtime +1 -delete
0 2 * * * find /var/www/html/subtitle-processor/processed -type f -mtime +1 -delete
0 2 * * * find /var/www/html/subtitle-processor/subtitles -type f -mtime +1 -delete

Production Security Hardening

1. File System Security

# Remove info.php file (contains sensitive PHP configuration)
sudo rm /var/www/html/subtitle-processor/info.php

# Set restrictive permissions on config files
sudo chmod 640 /var/www/html/subtitle-processor/config.php
sudo chmod 640 /var/www/html/subtitle-processor/Video-Translator-options.py

2. Apache Security Configuration

Add to virtual host configuration:

# Prevent access to sensitive files
<FilesMatch "\.(log|py|md)$">
    Require all denied
</FilesMatch>

# Prevent access to directories
<DirectoryMatch "(logs|venv)">
    Require all denied
</DirectoryMatch>

3. Environment Variables (Recommended)

Instead of hardcoding API keys, use environment variables:

Edit /etc/environment:

DEEPL_API_KEY=your-production-api-key-here

Update config.php:

define('DEEPL_API_KEY', getenv('DEEPL_API_KEY'));

Monitoring and Maintenance

1. Log Monitoring

# Monitor application logs
sudo tail -f /var/www/html/subtitle-processor/logs/app_$(date +%Y-%m-%d).log

# Monitor Apache logs
sudo tail -f /var/log/apache2/subtitle-processor_error.log

2. System Resource Monitoring

# Monitor Python processes
ps aux | grep python

# Monitor disk space (critical for video processing)
df -h /var/www/html/subtitle-processor

# Monitor memory usage
free -h

3. Health Check Endpoint

The application provides health information at:

http://your-domain.com/info.php

4. Backup Strategy

Daily Backup Script (/usr/local/bin/backup-subtitle-processor.sh):

#!/bin/bash
BACKUP_DIR="/backup/subtitle-processor"
DATE=$(date +%Y%m%d)

# Create backup directory
mkdir -p $BACKUP_DIR

# Backup application files (excluding temporary data)
tar -czf $BACKUP_DIR/app-$DATE.tar.gz \
    --exclude='uploads/*' \
    --exclude='processed/*' \
    --exclude='subtitles/*' \
    --exclude='logs/*' \
    --exclude='venv/*' \
    /var/www/html/subtitle-processor

# Keep only last 7 days of backups
find $BACKUP_DIR -name "app-*.tar.gz" -mtime +7 -delete

Troubleshooting

Common Issues

1. Upload Fails - File Too Large

• Check PHP settings: upload_max_filesize, post_max_size
• Verify Apache limits in virtual host configuration

2. Python Environment Not Found

• Verify path in process.php: /var/www/html/subtitle-processor/venv/
• Check ownership: sudo chown -R www-data:www-data venv/

3. FFmpeg Not Found

• Install FFmpeg: sudo apt install ffmpeg
• Verify path in process.php and process-reburn.php

4. DeepL API Errors

• Verify API key is valid and has sufficient quota
• Check network connectivity to DeepL API

5. Permission Denied Errors

• Ensure www-data owns all application files
• Check directory permissions (755 for directories, 644 for files)

Debug Mode

Enable debug logging in config.php:

define('LOG_LEVEL', 'DEBUG');

Performance Optimization

1. Large File Handling

• Consider increasing memory_limit for very large video files
• Monitor disk space during processing
• Implement queue system for multiple concurrent uploads

2. Caching

• Enable Apache mod_expires for static assets
• Consider implementing Redis for session management

3. Load Balancing

• For high-traffic deployments, consider load balancer with multiple application servers
• Shared storage for uploads/processed files (NFS or object storage)

Scaling Considerations

Horizontal Scaling

• Database backend for job queue management
• Separate processing servers from web interface
• Shared file storage (NFS/GlusterFS/Object Storage)

Monitoring Integration

• Prometheus/Grafana for metrics
• ELK stack for log aggregation
• Nagios/Zabbix for alerting

Support and Updates

Version Information

• Application Version: 2.0
• Supported PHP: 8.0+
• Supported Python: 3.8+
• Supported FFmpeg: 4.4+

Update Procedure

1. Backup current installation
2. Stop Apache service
3. Deploy new code
4. Update Python dependencies if needed
5. Run any migration scripts
6. Start Apache service
7. Test functionality

---

⚠️ Security Note: This application is marked as "AI Sandbox - NOT FOR PRODUCTION USE" in the source code. Ensure thorough security testing and code review before production deployment.

📝 License: Ensure compliance with all third-party licenses (Whisper, DeepL, FFmpeg) for commercial production use.