Bilingual Transcription System

A production-ready bilingual transcription and translation system with a modern web interface.

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js 16+
• FFmpeg (for audio processing)
• NSSM (download from https://nssm.cc/download)

Recent Optimizations

• Streamlined Deployment: Single deploy-complete.bat script for complete deployment
• Consolidated Documentation: All guides merged into comprehensive README
• Clean Project Structure: Removed unnecessary files and directories
• Windows-Focused: Optimized for Windows service deployment
• Production Ready: Optimized for Windows service deployment with automatic startup

One-Command Deployment

# Right-click and "Run as administrator"
deploy-complete.bat

Manual Deployment

1. setup.bat
2. cd transcribing-system && npm run build:prod && cd ..
3. install-windows-service.bat (as administrator)
4. Access at http://localhost:5000

📋 Features

• Audio/Video Transcription: Support for MP3, MP4, WAV, M4A, AVI, MOV, MKV, FLV, WEBM
• Bilingual Translation: Translate between multiple languages
• Multiple Export Formats: TXT, SRT, VTT, JSON
• Session Management: Save and load previous transcriptions
• Real-time Progress: Live transcription status updates
• Production Ready: Windows service with automatic startup
• Modern Web Interface: React-based responsive UI

🏗️ Architecture

Backend (Flask + Gunicorn)

• Framework: Flask with production configuration
• Server: Gunicorn with multiple workers
• AI Models: OpenAI Whisper for transcription
• Translation: Google Translate API
• Storage: File-based session management

Frontend (React + Vite)

• Framework: React 18 with modern hooks
• Build Tool: Vite for fast development and optimized builds
• Styling: Tailwind CSS for responsive design
• UI Components: Lucide React icons, React Dropzone for file uploads

📁 Project Structure

bilingual-transcriber/
├── 🚀 Core Application
│   ├── app.py                          # Main Flask application
│   ├── bilingual_transcriber_gui.py    # Core transcription logic
│   ├── wsgi.py                         # WSGI entry point for production
│   └── production_config.py            # Production configuration
│
├── 🛠️ Deployment Scripts
│   ├── deploy-complete.bat             # Complete deployment (recommended)
│   ├── install-windows-service.bat     # Windows service installer
│   ├── uninstall-windows-service.bat   # Windows service uninstaller
│   ├── setup.bat                       # Initial setup script
│   └── gunicorn.conf.py               # Gunicorn configuration
│
├── 📦 Dependencies
│   ├── requirements.txt               # Development dependencies
│   ├── requirements-prod.txt          # Production dependencies
│   └── env.example                    # Environment variables template
│
├── 🌐 Frontend
│   └── transcribing-system/           # React application
│       ├── src/                      # React source code
│       ├── package.json              # Node.js dependencies
│       ├── vite.config.js            # Vite configuration
│       ├── tailwind.config.js        # Tailwind CSS configuration
│       ├── postcss.config.js         # PostCSS configuration
│       ├── eslint.config.js          # ESLint configuration
│       ├── index.html                # Main HTML template
│       └── dist/                     # Built frontend (generated)
│
├── 📁 Storage
│   ├── uploads/                      # File upload directory
│   │   └── .gitkeep                  # Git tracking placeholder
│   ├── sessions/                     # Session storage directory
│   │   └── .gitkeep                  # Git tracking placeholder
│   └── logs/                         # Application logs (generated)
│
├── 📚 Documentation & Tools
│   ├── README.md                     # Comprehensive documentation
│   ├── monitor.py                    # System monitoring script
│   ├── .gitignore                    # Git ignore rules
│   └── nssm.exe                      # Windows service manager
│
└── 📁 Git
    └── .git/                         # Git repository (hidden)

🧹 Cleanup Summary

Removed Files: 22 unnecessary files including Docker configs, Linux scripts, redundant documentation, and cache directories Optimizations: Streamlined deployment, consolidated documentation, Windows-focused structure Added: Comprehensive .gitignore, .gitkeep files, and production-ready deployment scripts

🔧 Configuration

Environment Variables

Create a .env file based on env.example:

# Flask Environment
FLASK_ENV=production
SECRET_KEY=your-secret-key-here

# Server Configuration
HOST=0.0.0.0
PORT=5000
WORKERS=4

# Model Configuration
WHISPER_MODEL=base
DEVICE=cpu

# Performance Settings
THREAD_POOL_SIZE=4
MAX_CONCURRENT_TRANSCRIPTIONS=2

# Session Management
MAX_SESSIONS=100
SESSION_CLEANUP_INTERVAL=3600

# Logging
LOG_LEVEL=INFO

🛠️ Development

Backend Development

# Install dependencies
pip install -r requirements.txt

# Run development server
python app.py

Frontend Development

cd transcribing-system

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build:prod

🚀 Production Deployment

Windows Service (Recommended)

# Complete deployment (Recommended)
deploy-complete.bat

# Or step by step
setup.bat
cd transcribing-system && npm run build:prod && cd ..
install-windows-service.bat

Deployment Options

Option 1: One-Command Deployment (Recommended)

# Right-click and "Run as administrator"
deploy-complete.bat

Option 2: Manual Deployment

1. setup.bat
2. cd transcribing-system && npm run build:prod && cd ..
3. install-windows-service.bat (as administrator)
4. Access at http://localhost:5000

Service Management

# Start service
net start BilingualTranscriber

# Stop service
net stop BilingualTranscriber

# Check status
sc query BilingualTranscriber

# Remove service
uninstall-windows-service.bat

📊 Monitoring

Health Checks

• Backend Health: http://localhost:5000/api/health
• System Status: http://localhost:5000/api/status
• System Info: http://localhost:5000/api/system-info

Logs

• Application Logs: logs/app.log
• Access Logs: logs/gunicorn_access.log
• Error Logs: logs/gunicorn_error.log

Monitoring Script

# Single health check
python monitor.py once

# Continuous monitoring
python monitor.py continuous

🔍 Troubleshooting

Common Issues

1. Port 5000 Already in Use

   netstat -ano | findstr :5000
   taskkill /PID <PID> /F

2. Service Won't Start

   sc query BilingualTranscriber
   type logs\app.log

3. Permission Errors

   • Run scripts as Administrator
   • Check file permissions

4. Model Loading Issues

   rm -rf ~/.cache/whisper
   pip install --force-reinstall openai-whisper

Debug Mode

# Set environment variables
set FLASK_ENV=development
set LOG_LEVEL=DEBUG

# Run manually
python wsgi.py

📈 Performance Optimization

Backend Optimization

• Workers: Adjust based on CPU cores (default: 4)
• Model Caching: Whisper models are cached automatically
• File Processing: Uses temporary RAM storage
• Memory Management: Optimized for transcription workloads

Frontend Optimization

• Code Splitting: Automatic chunk optimization
• Asset Compression: Gzip compression enabled
• Caching: Static assets cached for 1 year
• Bundle Optimization: Vendor and UI chunks separated

🔒 Security

Security Features

• CORS Protection: Configured for local development
• File Validation: Strict file type and size validation
• Security Headers: XSS protection, content type validation
• Environment Variables: Sensitive data externalized
• Non-root Execution: Service runs with limited privileges

Best Practices

• Use strong secret keys
• Keep dependencies updated
• Monitor logs regularly
• Use HTTPS in production
• Implement rate limiting if needed

📚 API Reference

Core Endpoints

Health Check

GET /api/health

System Status

GET /api/status

File Upload

POST /api/upload
Content-Type: multipart/form-data

Transcription

POST /api/transcribe
Content-Type: application/json
{
  "filepath": "/path/to/file.mp3"
}

Translation

POST /api/translate
Content-Type: application/json
{
  "text": "Hello world",
  "target_language": "es",
  "source_language": "en"
}

Download Results

POST /api/download/{format}
Content-Type: application/json
{
  "session_id": "uuid"
}

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

This project is licensed under the MIT License.

🆘 Support

For issues and questions:

1. Check the troubleshooting section
2. Review logs for error messages
3. Check system resources
4. Verify configuration settings
5. Test with smaller files first

📋 Recent Project Cleanup

Files Removed (22 total)

• Redundant Scripts: start.py, start.bat, start-production.bat, start-production.sh
• Linux/Docker Files: bilingual-transcriber.service, Dockerfile.backend, Dockerfile.frontend, docker-compose.yml, nginx.conf
• Redundant Documentation: MODEL_LOADING_GUIDE.md, SERVER_REQUIREMENTS.md, SESSION_STORAGE_GUIDE.md, SETUP_GUIDE.md, PRODUCTION_DEPLOYMENT_GUIDE.md, WINDOWS_SERVICE_GUIDE.md, DEPLOYMENT_CHECKLIST.md
• Cache & Build Files: __pycache__/, transcribing-system/.gitignore, transcribing-system/README.md
• Documentation Files: Proposal.docx

Optimizations Made

• Streamlined Deployment: Single deploy-complete.bat for complete setup
• Consolidated Documentation: All guides merged into comprehensive README
• Windows-Focused: Removed Linux/Docker files for Windows-only deployment
• Clean Structure: Removed unnecessary files and directories
• Proper Git Management: Comprehensive .gitignore and directory tracking

Files Added/Updated

• .gitignore: Comprehensive git ignore rules
• uploads/.gitkeep: Git tracking placeholder
• sessions/.gitkeep: Git tracking placeholder
• deploy-complete.bat: One-command deployment script
• README.md: Updated with current structure and optimizations

---

Note: This system is designed for Windows deployment with production-ready features including automatic startup, monitoring, and comprehensive error handling.