PRD.md

# PRD.md — AI Subtitle Generator MVP

# Goal

Build a simple web app where users can:

1. Upload a video
2. Generate English subtitles using AI speech-to-text
3. Translate subtitles into:

   * Malayalam
   * Tamil
   * Hindi
4. Download `.srt` subtitle files

The MVP should be:

* Extremely simple
* Fast to build
* Vibecoding-friendly
* Localhost only

---

# Core Features

## 1. Upload Video

Support:

* `.mp4`
* `.mov`
* `.mkv`
* `.webm`

---

## 2. Extract Audio

Use FFmpeg to extract audio from the uploaded video.

Example:

```bash
ffmpeg -i input.mp4 -ar 16000 -ac 1 output.wav
```

---

## 3. Speech to Text

Use local:

```python
faster-whisper
```

Generate:

* English transcript
* English `.srt`
* Timestamps

### MVP Decision

The MVP will use local Faster-Whisper instead of cloud APIs.

Why?

* Free
* Fast enough for short videos
* Better privacy
* Works offline
* Easy localhost setup
* Easy to vibecode

### Suggested Model

Start with:

```python
base
```

Upgrade later if needed:

* `small`
* `medium`

---

### Example

```python
from faster_whisper import WhisperModel

model = WhisperModel("base")
segments, info = model.transcribe("audio.wav")
```

---

---

## 4. Translate Subtitles

Use a small translation adapter layer.

The app should NOT directly depend on one translation provider.

This makes it easy to:

* start simple
* swap providers later
* experiment with better translation models

---

## MVP Translation Provider

Start with:

```python
deep-translator
```

Translate English subtitles into:

* Malayalam (`ml`)
* Tamil (`ta`)
* Hindi (`hi`)

---

## Future Translation Provider

Later we can swap in:

* IndicTrans2
* LibreTranslate
* OpenAI models
* Other local translation models

without changing the main application flow.

---

## Suggested Adapter Design

```text
services/
└── translators/
    ├── base.py
    ├── deep_translator_adapter.py
    └── indictrans_adapter.py
```

---

## Example Interface

```python
class Translator:
    def translate(self, text: str, target_lang: str) -> str:
        pass
```

---

## Example MVP Usage

```python
translator = DeepTranslatorAdapter()
translated = translator.translate(text, "ml")
```

---

---

## 5. Generate `.srt`

Generate downloadable subtitle files.

Example:

```srt
1
00:00:01,000 --> 00:00:03,000
Hello everyone
```

---

# Tech Stack

## Backend

* FastAPI

## Frontend

* HTML
* CSS
* Minimal JavaScript
* Jinja2 Templates

## AI/Processing

* Faster-Whisper
* FFmpeg
* deep-translator
* pysrt

---

# Simple Architecture

```text
Upload Video
   ↓
Extract Audio
   ↓
Whisper Transcription
   ↓
Translate Text
   ↓
Generate .srt
   ↓
Download File
```

---

# Suggested Folder Structure

```text
app/
├── main.py
├── templates/
│   └── index.html
├── static/
│   └── styles.css
├── uploads/
├── subtitles/
└── services/
    ├── transcribe.py
    ├── translate.py
    └── srt_generator.py
```

---

# Main UI

Single page with:

* Upload input
* Language dropdown
* Generate button
* Loading spinner
* Download links

---

# Main API

## Generate Subtitles

```http
POST /generate-subtitles
```

Inputs:

* video file
* target language

Outputs:

* English `.srt`
* Translated `.srt`

---

# Suggested Dependencies

```txt
fastapi
uvicorn
jinja2
python-multipart
faster-whisper
ffmpeg-python
deep-translator
pysrt
```

---

# Run Locally

```bash
uvicorn app.main:app --reload
```

---

# MVP Rules

* Keep everything in ONE FastAPI app
* Store files locally
* Use sync processing
* No authentication
* No database
* No React
* No Docker initially
* No microservices
* No overengineering

---

# Build Order

1. Upload video
2. Extract audio
3. Generate English transcript
4. Generate English `.srt`
5. Add translation
6. Generate translated `.srt`
7. Improve UI later

---

# Success Criteria

The MVP is successful if:

* Video upload works
* English subtitles are generated
* Translation works
* `.srt` download works
* End-to-end pipeline works locally