README.md

---
title: Pulse Translate
emoji: 🎤
colorFrom: indigo
colorTo: blue
sdk: docker
app_port: 7860
fullWidth: true
short_description: Live AI4Bharat meeting translation with FastAPI.
---

# Pulse Translate

Pulse Translate is now oriented around the fastest path to a usable live product: browser microphone chunks sent to a lightweight FastAPI backend, which runs speech recognition and translation with the AI4Bharat stack.

## What changed

The app now:

- captures microphone audio directly in the browser
- sends audio chunks to the backend for ASR and translation
- uses AI4Bharat IndicTrans2 for translation
- plays translated audio back in the browser when TTS is available
- shows source and translated transcripts in the UI

This is a much better fit for live meetings than the earlier upload-and-translate approach, and it keeps the translation logic fully on the backend.

## Project Structure

```text
app/
  config.py
  main.py
web/
  index.html
  styles.css
  app.js
requirements.txt
requirements-local.txt
Dockerfile
README.md
```

## Local Setup

### 1. Create and activate a virtual environment

```powershell
cd "d:\Projects\LANGUAGE AI"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

If PowerShell blocks activation:

```powershell
Set-ExecutionPolicy -Scope Process Bypass
```

### 2. Install dependencies

```powershell
python -m pip install --upgrade pip
pip install -r requirements.txt
pip install -r requirements-local.txt
```

The AI4Bharat pipeline depends on the local extras in `requirements-local.txt` for speech recognition, translation, and TTS.

### 3. Make sure model downloads are allowed

The first translation request may download Whisper and IndicTrans model weights. If the machine is offline or blocked from Hugging Face, the app will start but translation will fail on the first audio chunk.

Optional configuration:

```powershell
$env:APP_MODE="ai4bharat"
$env:TRANSLATION_PROVIDER="ai4bharat"
$env:DEFAULT_TARGET_LANG="hi"
```

### 4. Run the app

```powershell
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
```

Open:

```text
http://127.0.0.1:8000
```

## Environment Variables

| Variable | Default | Purpose |
| --- | --- | --- |
| `TRANSLATION_PROVIDER` | `ai4bharat` | Translation backend |
| `APP_MODE` | `ai4bharat` | UI health mode label |
| `DEFAULT_TARGET_LANG` | `hi` | Default output language |
| `WHISPER_MODEL_SIZE` | `base` | Whisper model used for ASR |
| `ENABLE_TTS` | `true` | Enables local TTS playback |

## How It Works

1. The browser records short microphone chunks and sends them to `POST /api/translate/chunk`.
2. The backend runs Whisper for transcription, AI4Bharat IndicTrans2 for translation, and optional TTS for playback.
3. The translated audio is returned to the browser and played locally.

This keeps the translation pipeline behind your backend while still giving you a low-friction live experience.

## Current Scope

This build is the fastest route to a usable live translator, but it is still a single-user live interpreter session in the browser.

It is well suited for:

- one participant listening to live translated speech
- demos
- prototypes
- early customer validation

It is not yet a full multi-party meeting platform with participant identity, room mixing, recording, or admin controls.

## Publish To Hugging Face

You can still publish this as a Docker Space, but note the tradeoff:

- the FastAPI app and frontend can run on Hugging Face
- the first request may need to download model weights
- you should make sure the container has enough memory for Whisper and IndicTrans2

### Recommended Hugging Face setup

1. Create a new Space.
2. Choose `Docker` as the SDK.
3. Push this repo to the Space.
4. Add any optional environment variables you want, such as `DEFAULT_TARGET_LANG`.
5. Ensure the container has network access for the first model download.

### CLI flow

```powershell
pip install -U "huggingface_hub[cli]"
hf auth login
hf repos create your-username/pulse-translate --type space --space-sdk docker
```

Then push the repo:

```powershell
git init
git add .
git commit -m "Add Pulse Translate realtime app"
git branch -M main
git remote add space https://huggingface.co/spaces/your-username/pulse-translate
git push space main
```

## Production Direction

For a real meetings product, this app is a strong starting point, but you will likely want to add:

- authenticated users
- meeting rooms and participant management
- speaker routing and per-user target languages
- persistent session logs and analytics
- retry and reconnection logic
- usage metering and rate limiting
- moderation and safety controls

## Troubleshooting

### The app says the backend is missing an API key

The current backend does not use an OpenAI API key. If translation fails, install both dependency files, confirm the model downloads are allowed, and restart `uvicorn`.

```powershell
pip install -r requirements.txt
pip install -r requirements-local.txt
```

### I cannot hear translated audio

- Click once on the page to unlock browser audio playback.
- Confirm the browser has microphone permission.
- Check the debug log for ASR, translation, or TTS errors.
- Make sure the backend returned a translated chunk successfully.

### The connection fails after starting

- Confirm the backend is running at the URL in the page.
- Confirm `requirements-local.txt` has been installed.
- Confirm your network allows outbound model downloads on first run.
- Check the browser console and the debug log panel.

## Sources

- Hugging Face Spaces overview: https://huggingface.co/docs/hub/spaces-overview
- Hugging Face Docker Spaces: https://huggingface.co/docs/hub/en/spaces-sdks-docker