README.md

# Whisper Transcribe

A local speech-to-text service powered by [faster-whisper](https://github.com/SYSTRAN/faster-whisper) and exposed publicly via [ngrok](https://ngrok.com). Upload any audio/video file and get back a full transcript with timestamps.

---

## Quick start

### 1. Install dependencies

```bash
pip install -r requirements.txt
```

### 2. Set your ngrok auth token

Open `.env` and paste your token after `NGROK_AUTHTOKEN=`:

```
NGROK_AUTHTOKEN=your_token_here
```

Get your free token at: https://dashboard.ngrok.com/get-started/your-authtoken

### 3. Run

```bash
python run.py
```

The terminal will print a public URL like:

```
================================================================
   Whisper Transcribe is live -> https://xxxx.ngrok-free.app
================================================================
```

Open that URL in any browser to use the web interface.

---

## Configuration (`.env`)

| Variable             | Default     | Description                                              |
|----------------------|-------------|----------------------------------------------------------|
| `NGROK_AUTHTOKEN`    | *(empty)*   | Your ngrok auth token (required for stable tunnels)      |
| `WHISPER_MODEL_SIZE` | `large-v3`  | Model to use: `tiny`, `base`, `small`, `medium`, `large-v3` |
| `HOST`               | `0.0.0.0`   | Flask bind address                                       |
| `PORT`               | `5000`       | Flask port                                               |
| `MAX_UPLOAD_MB`      | `100`        | Max upload size in MB                                    |

Smaller models (`tiny`, `base`, `small`) load faster and use less memory; `large-v3` gives the best accuracy.

---

## API

### `POST /api/transcribe`

Upload an audio or video file.

**Request** — `multipart/form-data`

| Field  | Type | Description           |
|--------|------|-----------------------|
| `file` | file | Audio/video to transcribe |

**Supported formats:** `.mp3`, `.wav`, `.m4a`, `.aac`, `.ogg`, `.flac`, `.mp4`, `.webm`

**Response** — `200 OK`

```json
{
  "text": "Full transcript as a single string.",
  "language": "en",
  "duration": 12.34,
  "segments": [
    { "start": 0.0, "end": 3.5, "text": "Hello world." },
    { "start": 3.5, "end": 6.1, "text": "This is a test." }
  ]
}
```

### `GET /api/progress/<job_id>`

Server-sent events (SSE) progress stream for a queued transcription job.

### `GET /api/download/<job_id>`

Download the generated output file once the job is completed.

### `GET /health`

Returns `{ "status": "ok", "model_size": "large-v3" }`.

---

## Deploying on Render

Use this app as a single web service (frontend + backend served by Flask) or split frontend/backend services.

- Single service: no extra frontend configuration is needed.
- Split services: set frontend API base to your backend URL by either:
  - adding `?api_base=https://your-backend.onrender.com` to the frontend URL, or
  - adding `<meta name="api-base" content="https://your-backend.onrender.com">` in `frontend/index.html`.

The frontend always calls `/api/*` endpoints now, and backend supports both `/api/*` and legacy non-`/api/*` routes.

---

## Project structure

```
.
├── backend/
│   ├── app.py          # Flask routes
│   ├── config.py       # Settings loaded from .env
│   └── transcriber.py  # faster-whisper inference
├── frontend/
│   ├── index.html
│   ├── style.css
│   └── app.js
├── outputs/            # Temporary upload scratch space (auto-cleaned)
├── run.py              # Entry point — starts Flask + ngrok tunnel
├── requirements.txt
└── .env                # Your local config (never commit this)
```

---

## Notes

- The model weights are downloaded automatically on the first run (~3 GB for `large-v3`). Subsequent runs use the cached weights.
- Transcription runs on **CPU** by default (`compute_type=int8`). If you have a CUDA GPU, edit `transcriber.py` and change `device="cpu"` to `device="cuda"` and `compute_type` to `"float16"`.
- Without an ngrok token the tunnel still works on the anonymous free tier but may be rate-limited.
# Whisper_AI_Transcription_model