---
title: AI Subtitle & SRT Generator
emoji: 🎬
colorFrom: green
colorTo: yellow
sdk: gradio
app_file: app.py
pinned: false
license: mit
---

# AI Subtitle & SRT Generator

A cloud-deployable web application that generates `.srt` subtitle files from
video or audio uploads, powered by **Faster-Whisper** (`large-v3` model).

## Features

| Feature | Description |
| --- | --- |
| Speech-to-Text | Automatic transcription via Faster-Whisper |
| Auto Timestamps | Accurate start / end times per segment |
| SRT Export | Standard `.srt` download |
| English | Full English transcription |
| Bangla | Bangla language support |
| Mixed / Banglish | Handles Bangla-English code-switching |
| Video Upload | MP4, MKV, AVI, MOV, WebM, FLV, WMV, M4V |
| Audio Upload | MP3, WAV, FLAC, AAC, OGG, M4A, WMA, OPUS |

## Architecture

```
Upload --> Validate --> FFmpeg (16 kHz WAV) --> Faster-Whisper --> SRT --> Download
```

## Project Structure

```
ai-subtitle-generator/
├── app.py                          # Gradio web UI + processing pipeline
├── services/
│   ├── __init__.py
│   ├── media_processor.py          # FFmpeg audio extraction
│   ├── transcription.py            # Faster-Whisper wrapper
│   └── subtitle_generator.py       # SRT file builder
├── utils/
│   ├── __init__.py
│   └── helpers.py                  # Validation, paths, utilities
├── models/                         # Downloaded Whisper models (gitignored)
├── temp/                           # Intermediate WAV files (auto-cleaned)
├── outputs/                        # Generated SRT files
├── requirements.txt
├── packages.txt                    # System packages for HF Spaces
├── README.md
└── .gitignore
```

## Local Development

### Prerequisites

- **Python 3.10+**
- **FFmpeg** installed and on PATH
  - Windows: `winget install Gyan.FFmpeg`
  - macOS: `brew install ffmpeg`
  - Linux: `sudo apt install ffmpeg`

### Setup

```bash
git clone https://github.com/<your-username>/ai-subtitle-generator.git
cd ai-subtitle-generator

python -m venv venv
source venv/bin/activate        # Linux / macOS
# venv\Scripts\activate         # Windows

pip install -r requirements.txt
python app.py
```

Open **http://localhost:7860** in your browser.

> **Note:** The Whisper `large-v3` model (~3 GB) is downloaded on the first
> transcription request. Subsequent runs use the cached model.

## Deploying to Hugging Face Spaces

### 1. Push to GitHub

```bash
cd ai-subtitle-generator
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/<your-username>/ai-subtitle-generator.git
git push -u origin main
```

### 2. Create a Hugging Face Space

1. Go to [huggingface.co/new-space](https://huggingface.co/new-space).
2. Settings:
   - **SDK:** Gradio
   - **Hardware:** CPU Basic (free)
   - **Visibility:** Public
3. Click **Create Space**.

### 3. Connect and Deploy

**Option A** -- Link your GitHub repo in Space Settings.

**Option B** -- Push directly:

```bash
git remote add hf https://huggingface.co/spaces/<your-username>/ai-subtitle-generator
git push hf main
```

`packages.txt` installs FFmpeg automatically. `requirements.txt` installs
Python dependencies. The model downloads on the first request.

## Technology Stack

| Component | Technology |
| --- | --- |
| Web UI | Gradio |
| Speech-to-Text | Faster-Whisper (large-v3) |
| Audio Processing | FFmpeg |
| Runtime | Python 3.10+ |
| Deployment | Hugging Face Spaces |

## Constraints

- Maximum upload size: **500 MB**
- Free HF Spaces run on CPU only; expect ~3-5x real-time processing.
- For faster (but less accurate) results, change `DEFAULT_MODEL_SIZE`
  in `services/transcription.py` to `"small"` or `"medium"`.

## License

MIT