About • Features • Requirements • Installation • Usage • Troubleshooting • Contributing • License

Leg2Sub breaks down language barriers in education. With only 1% of Brazil's population fluent in English while quality content remains concentrated in that language, Leg2Sub provides free, powerful subtitle generation, translation, and customization.

Built with Streamlit and powered by Whisper/WhisperX, the platform transcribes, translates, and synchronizes subtitles automatically. Deploy on CPU for accessibility or GPU for high-performance processing.

• 🎯 Video Subtitling - Automatic transcription with embedded subtitles (soft & hard)
• 🌐 Translation - Multi-language support via Google Translate
• 📝 Transcription - Whisper and WhisperX engines
• 🎨 Subtitle Customization - Color adjustment and formatting
• 🐳 Multi-Platform - Unified Docker with CPU and GPU variants
• ⚙️ Advanced Config - Fine-tune transcription, translation, and video parameters
• 🚀 Production Ready - Error handling and batch processing support

• Python: 3.10 - 3.12 (strongly recommended)
• Docker & Docker Compose: Any recent version
• WSL 2 (Windows only): For Docker support
• GPU (Optional): NVIDIA with CUDA 11.0+ support

CPU Version:

git clone https://github.com/Paulogb98/Leg2Sub.git
cd Leg2Sub

docker compose up leg2sub_cpu -d

GPU Version (NVIDIA):

# Prerequisites: Install NVIDIA Container Toolkit
# https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html

docker compose up leg2sub_gpu -d

Monitor Startup:

docker compose logs -f leg2sub_cpu
# or for GPU:
docker compose logs -f leg2sub_gpu

Access Application: Open browser to http://localhost:8501

git clone https://github.com/Paulogb98/Leg2Sub.git
cd Leg2Sub

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

pip install -r requirements.txt

streamlit run app/streamlit.py

Open PowerShell as Administrator:

wsl --install -d Ubuntu

Open Ubuntu terminal:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

sudo usermod -aG docker $USER
newgrp docker

# Follow official guide:
# https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html

# Verify installation:
dpkg -l | grep nvidia-container-toolkit

# Test GPU support:
docker run --rm --gpus all nvidia/cuda:11.0-runtime nvidia-smi

cd /mnt/c/Users/<username>/Downloads
git clone https://github.com/Paulogb98/Leg2Sub.git
cd Leg2Sub

# CPU version
docker compose up leg2sub_cpu -d

# GPU version
docker compose up leg2sub_gpu -d

1. Access: http://localhost:8501
2. Select Feature: Choose from navigation menu
3. Upload File: Select media or subtitle file
4. Configure (Optional): Adjust parameters in Advanced Settings
5. Process: Click button and wait for completion
6. Download: Results saved to temp_output/ folder

Transcription:

• Engine: Whisper, WhisperX
• Model: tiny, small, medium, large, large-v3-turbo
• Device: auto, cpu, cuda
• Batch Size: 1-32 (default: 12)
• Compute Type: float32, float16, int8

Video Encoding:

• Video Codec: h264, hevc, mpeg4
• Audio Codec: aac, libopus, libmp3lame
• Hardware APIs: nvenc, vaapi, amf, qsv (auto-detected)

Translation:

• Languages: Portuguese, English, Spanish, French, German, Chinese, Japanese, Korean, and 20+ more

Check logs:

docker compose logs leg2sub_cpu
# or
docker compose logs leg2sub_gpu

Verify Docker is running:

docker ps

Verify NVIDIA Container Toolkit:

docker run --rm --gpus all nvidia/cuda:11.0-runtime nvidia-smi

Expected output: GPU information should display

• Reduce batch size in Advanced Settings (try 4-8)
• Process smaller files
• Close other applications
• Increase available disk space for temp files

Port 8501 already in use:

# Kill existing process or change port in docker-compose.yml
# Change: "8501:8501" to "8502:8501"

Enable WSL 2 optimizations:

# In PowerShell as Admin:
wsl --set-default-version 2
wsl -l -v  # Verify WSL 2 is default

# Fix permission issues:
sudo chown -R $USER:$USER /root_dir
chmod -R 755 /root_dir

Leg2Sub/
├── app/
│   └── template/
│       ├── homepage.py              # Main landing page
│       ├── sub_video_page.py        # Video subtitling interface
│       ├── translate_srt_page.py    # Subtitle translation interface
│       ├── transcribe_video_page.py # Video transcription interface
│       ├── sub_color_page.py        # Subtitle coloring interface
│       ├── static/
│       │   └── style.css            # Custom styling
│       └── streamlit.py             # App entry point
├── src/
│   ├── main_color_srt.py            # Color conversion logic
│   ├── main_subtitle.py             # Video processing pipeline
│   ├── main_transcriber.py          # Transcription entry point
│   └── main_translate_srt.py        # Translation logic
├── utils/
│   ├── ffmpeg_utils.py              # FFmpeg operations
│   ├── file_utils.py                # File handling
│   ├── subtitle_utils.py            # Subtitle processing
│   ├── translate_utils.py           # Translation utilities
│   ├── utils_func.py                # Helper functions
│   ├── whisper_utils.py             # Whisper integration
│   ├── whisperx_utils.py            # WhisperX integration
│   └── whisperx_transcription_utils.py # WhisperX helpers
├── assets/
│   ├── logo/                        # Logo files (SVG & PNG)
│   ├── content/                     # UI card images
│   └── demo/                        # Demo GIF
├── Dockerfile                       # Unified build with targets
├── docker-compose.yml               # Multi-service orchestration
├── requirements.txt                 # Python dependencies
└── README.md                        # This file

The Dockerfile uses multi-stage builds for efficient CPU and GPU deployments:

Base Stage (base):

• Python 3.10-buster
• Common dependencies (FFmpeg, tk, curl, etc.)
• Pip packages from requirements.txt
• Streamlit configuration

CPU Stage (cpu):

• Inherits from base
• Optimized for multi-core processing
• Minimal overhead

GPU Stage (gpu):

• NVIDIA CUDA 12.0.1 base
• cuDNN 8 support
• Python 3.10 with GPU optimization
• All common dependencies

Both services available simultaneously:

leg2sub_cpu:
  build:
    target: cpu      # Builds base → cpu
  ports:
    - "8501:8501"
  # Standard resource limits

leg2sub_gpu:
  build:
    target: gpu      # Builds NVIDIA base → gpu
  runtime: nvidia    # GPU support
  devices:           # GPU allocation
    - driver: nvidia

• CPU Mode: 2-4 GB system RAM
• GPU Mode: 2-4 GB system + 4-6 GB VRAM

Core dependencies:

• streamlit==1.42.2 - Web interface
• whisper - Speech recognition
• whisperx - Enhanced transcription
• deep_translator - Translation
• ffmpeg_progress_yield - FFmpeg monitoring
• pysrt - Subtitle handling

# Memory limits (adjust as needed)
deploy.resources.limits.memory: 16G
deploy.resources.reservations.memory: 4G

# GPU device allocation
devices:
  - driver: nvidia
    device_ids: ['0']  # Change to use different GPU
    capabilities: [gpu, compute, utility]

# Restart policy
restart: unless-stopped  # Auto-restart on failure

Contributions are welcome!

1. Fork repository
2. Create feature branch (git checkout -b feature/YourFeature)
3. Commit changes (git commit -m 'feat: add YourFeature')
4. Push to branch (git push origin feature/YourFeature)
5. Open Pull Request

• ✅ New language support
• ✅ UI/UX improvements
• ✅ Performance optimization
• ✅ Additional subtitle formats
• ✅ Documentation and examples
• ✅ Bug fixes and testing

This project is licensed under the GNU GPLv3 License - see LICENSE for details.

• OpenAI Whisper - Speech recognition
• WhisperX - Enhanced transcription and alignment
• LeGen - Subtitle processing reference
• Python community - All open-source libraries

📧 Email: [email protected]

🔗 LinkedIn: https://www.linkedin.com/in/paulo-goiss/

💬 GitHub Issues: Open an issue

Built with ❤️ using Python, Streamlit & FFmpeg

🔗 Repository • 📝 Issues • 📦 Releases • 👤 LinkedIn

Leg2Sub v1.0 | ✅ Production Ready | 🌐 Free & Open Source