Architecture

How LingoScribe works

Two independent speech engines, one clean interface. Choose between cloud-powered Groq Whisper with full translation and AI insights, or a self-hosted Whisper model running on HuggingFace with zero external API calls.

Try it now
LingoScribe dual-engine architecture: Groq Orchestration and Self-hosted Whisper pipelines
Two engines, one interface
01

Your Browser

lingoscribe-frontend.vercel.app

A zero-dependency static frontend served from Vercel. No framework, no build step. An engine toggle lets you switch between Groq Orchestration (full pipeline) and Self-hosted Whisper (transcription only) before submitting. Audio is sent as a multipart fetch() request to whichever engine is selected.

  • Upload any format: WAV, MP3, OGG, FLAC, M4A, WEBM, AAC, WMA
  • Record live from microphone with real-time timer
  • Both backends pinged on load to keep them warm
  • Translation, insights, and Q&A shown only in Groq mode
02

Groq Orchestration

FastAPI · Docker · Render + Groq API

A Python FastAPI app on Render acts as a secure orchestration layer. The Groq API key never leaves the server. Transcription uses Whisper large-v3, translation and all text tasks use GPT-OSS-120B, all via Groq's low-latency inference API.

  • /transcribe: Groq Whisper large-v3 + batch segment translation
  • /analyze: summary, key topics, tone, linguistic observation
  • /ask: natural language Q&A grounded in the transcript
  • ffmpeg converts non-native formats before sending to Groq
03

Self-hosted Whisper

faster-whisper · Docker · HuggingFace Spaces

A separate FastAPI service on HuggingFace Spaces runs faster-whisper small (int8) entirely on CPU with no external API calls. The Whisper model is baked into the Docker image at build time so cold starts are instant. Language is forced to Urdu to ensure Perso-Arabic script output for both Urdu and Pakistani Punjabi.

  • No API key required, fully self-contained
  • faster-whisper small, int8 quantized, CPU inference
  • Model pre-downloaded at Docker build, not at runtime
  • Transcription only, no translation or insights
Step-by-step workflow

Groq Orchestration: full pipeline

  1. 1
    Select engine and upload or record

    User selects Groq Orchestration, then drops an audio file or records from the microphone. Any format is accepted.

  2. 2
    POST to Render backend

    Browser sends POST /transcribe with audio as multipart form data to the FastAPI service on Render over HTTPS.

  3. 3
    Format conversion

    If the format is not natively supported by Groq (e.g. WMA), ffmpeg converts it to MP3 before forwarding.

  4. 4
    Groq Whisper transcription

    Audio is posted to Groq's Whisper large-v3 endpoint with language=ur forced. Returns time-stamped segments in Perso-Arabic script.

  5. 5
    Batch translation

    All segment texts are sent to GPT-OSS-120B in one prompt. Returns a JSON array of English translations, one per segment.

  6. 6
    Response assembled and rendered

    Backend returns segments with timestamps, original Urdu/Punjabi text, and English translation. Browser renders the full table.

  7. 7
    AI insights

    Browser auto-sends POST /analyze. Groq LLM returns summary, key topics, tone, and a linguistic observation as structured JSON.

  8. 8
    Ask anything

    User types a question. POST /ask sends the transcript and question together; the LLM answers strictly from the transcript content.

Self-hosted Whisper: transcription only

  1. 1
    Select Self-hosted Whisper engine

    User switches the engine toggle to Self-hosted Whisper. The translation column, insights, and Q&A blocks are hidden automatically.

  2. 2
    POST directly to HuggingFace Space

    Browser sends POST /transcribe directly to farhan2-lingo.hf.space. No Render backend involved.

  3. 3
    faster-whisper inference on CPU

    The HF Space container runs faster-whisper small (int8) with language="ur" forced. No external API call, everything runs locally inside Docker.

  4. 4
    Transcript returned

    Returns segments with start/end timestamps and Urdu/Shahmukhi text. Browser renders the time and original text columns only.

Security & privacy
HTTPS everywhere

All traffic between browser, backend, and Groq is encrypted in transit.

CORS restricted

The backend only accepts requests from the Vercel frontend domain. No third-party access.

API key server-side only

The Groq API key is stored as an environment variable on Render. Never sent to the browser or committed to GitHub.

No data stored

Audio files are written to a temporary directory and deleted immediately after processing. Nothing is persisted.

Tech stack
LayerTechnologyRole
FrontendHTML · CSS · JavaScriptStatic UI, engine toggle, file upload, MediaRecorder, fetch API
Hosting (frontend)VercelStatic site deployment, global CDN
Backend (Groq mode)FastAPI + UvicornREST API, multipart file handling, CORS, Groq orchestration
ContainerDocker (python:3.11-slim)Reproducible runtime, ffmpeg included
Hosting (Groq mode)RenderDocker web service, environment secrets
Transcription (Groq mode)Groq Whisper large-v3Urdu/Punjabi speech to text, Perso-Arabic script forced
TranslationGroq GPT-OSS-120BBatch segment translation to English
Insights & Q&AGroq GPT-OSS-120BSummary, topics, tone, question answering
Backend (Whisper mode)FastAPI + faster-whisperSelf-contained transcription, no external API
Transcription (Whisper mode)faster-whisper small (int8)CPU inference, model baked into Docker image
Hosting (Whisper mode)HuggingFace SpacesFree CPU Docker container, 16GB RAM
Format conversionffmpegNon-native formats to MP3 (Groq mode only)

Ready to try it?

Upload an Urdu or Punjabi audio file or record directly from your microphone. No signup needed.

Launch LingoScribe View source on GitHub