Voice Translator

Real-time voice-to-English captioning app with a modern web UI and streaming backend.

What This Project Does

• Captures microphone audio in the browser.
• Streams PCM audio to a FastAPI WebSocket endpoint.
• Transcribes speech with Deepgram.
• Translates/captions through Groq in near real time.
• Renders clean, rolling English captions in a Next.js interface.

Tech Stack

Layer	Technology
Frontend	Next.js 16, React 19, TypeScript, Tailwind
Backend	FastAPI, WebSockets, Pydantic Settings
Speech-to-Text	Deepgram SDK
Translation/LLM	Groq API

Repository Structure

.
|- app/                        # Next.js app router frontend
|- public/                     # Static assets (includes PCM worklet)
|- backend/
|  |- app/
|  |  |- api/websockets/       # /ws/translate endpoint
|  |  |- core/                 # Settings/configuration
|  |  |- services/             # Deepgram + Groq streaming pipeline
|  |- main.py                  # FastAPI entrypoint
|  |- .env.example             # Backend env template
|  |- pyproject.toml           # Python dependencies
|- package.json                # Frontend scripts/deps

Architecture at a Glance

1. Browser captures mono mic audio.
2. Frontend sends PCM chunks over ws://<host>:8000/ws/translate.
3. Backend forwards/transforms stream for Deepgram STT.
4. Transcript is translated/refined through Groq.
5. Frontend receives non_final and final updates and renders captions.

Prerequisites

• Node.js 20+ and npm
• Python 3.10+
• Deepgram API key
• Groq API key (gsk_...)

Quick Start

1) Backend Setup

cd backend
python -m venv venv
venv\Scripts\activate
pip install -e .

Create backend/.env from template:

copy .env.example .env

Populate required values:

• DEEPGRAM_API_KEY
• GROQ_API_KEY
• Optional: CORS_ORIGINS, WS_CLIENT_KEY, model tuning values

Run backend:

uvicorn main:app --reload --host 0.0.0.0 --port 8000

Health checks:

• http://127.0.0.1:8000/health
• http://127.0.0.1:8000/health/keys
• http://127.0.0.1:8000/health/pipeline

2) Frontend Setup

From repo root:

npm install
npm run dev

Open: http://localhost:3000

Frontend Environment (Optional)

The app auto-targets <current-host>:8000, but you can override:

• NEXT_PUBLIC_WS_HOST (example: 127.0.0.1:8000)
• NEXT_PUBLIC_WS_CLIENT_KEY (if backend uses WS_CLIENT_KEY)

Key API Surface

• GET /health - basic status
• GET /health/keys - key presence and formatting checks
• GET /health/pipeline - active pipeline configuration
• WS /ws/translate - real-time stream endpoint
  • Query params:
    • language (hi default in backend)
    • sample_rate (8000-96000, frontend usually sends actual context rate)
    • client_key (optional, required when backend key auth is enabled)

Troubleshooting

• 4401 Unauthorized on WebSocket:
  • Ensure WS_CLIENT_KEY in backend matches NEXT_PUBLIC_WS_CLIENT_KEY on frontend.
• 4000 close code:
  • Missing or invalid backend API keys; verify backend/.env and restart server.
• Groq key rejected:
  • Use a real Groq secret key from console; must start with gsk_.
• No transcript updates:
  • Confirm browser mic permission and backend terminal logs.

Development Notes

• Keep secrets in .env files only; never commit live keys.
• Media fixtures and local caches are gitignored.
• Recommended flow: backend first, then frontend.

Roadmap (Project Management View)

• Add role-based auth for secure multi-user usage.
• Add session history export and searchable transcript logs.
• Add language expansion beyond Hindi/Urdu input streams.
• Add CI pipeline with lint/test gates for frontend and backend.
• Add deployment profiles (Docker + cloud templates).

License

No license file is currently defined. Add one before public distribution.