Transcription

How Transcription Works#

Voice uses OpenAI's Whisper Large V3 model running on Groq's inference infrastructure for speech-to-text. Two Whisper variants are available:

• whisper-large-v3 — Highest accuracy, best for offline batch processing
• whisper-large-v3-turbo — Lower latency, suited for real-time and interactive use cases

The transcription service accepts audio files, sends them to Groq's Whisper API, and returns structured results with full text, per-segment timestamps, detected language, and duration.

Batch Transcription#

Upload an audio file and receive a complete transcription with segment-level detail.

curl -X POST http://localhost:8003/api/v1/transcribe \
  -F "file=@citizen_call.mp3" \
  -G -d "language=ar" \
  -G -d "model=whisper-large-v3"

Response:

{
  "id": "tx-001",
  "text": "مرحبا، أريد الاستفسار عن خدمات الحكومة",
  "language": "ar",
  "duration": 4.5,
  "segments": [
    {"start": 0.0, "end": 2.1, "text": "مرحبا"},
    {"start": 2.1, "end": 4.5, "text": "أريد الاستفسار عن خدمات الحكومة"}
  ],
  "model": "whisper-large-v3",
  "created_at": "2024-01-15T10:30:00Z"
}

Each segment includes precise start and end timestamps, enabling downstream features like subtitle generation and speaker attribution.

Real-Time Streaming#

For live transcription, Voice exposes a WebSocket endpoint that accepts raw audio bytes and returns JSON results as speech is processed.

const ws = new WebSocket("ws://localhost:8003/api/v1/transcribe/stream");

ws.onopen = () => {
  // Send raw audio bytes from a microphone stream
  navigator.mediaDevices.getUserMedia({ audio: true }).then((stream) => {
    const recorder = new MediaRecorder(stream);
    recorder.ondataavailable = (e) => ws.send(e.data);
    recorder.start(250); // Send chunks every 250ms
  });
};

ws.onmessage = (event) => {
  const result = JSON.parse(event.data);
  if (result.status === "completed") {
    console.log(result.text, result.language, result.duration);
  }
};

The WebSocket endpoint sends two types of messages:

• {"status": "processing"} — Audio chunk received and being processed
• {"status": "completed", "text": "...", "language": "ar", "duration": 2.1, "segments": [...]} — Final transcription result

Language Detection#

Voice supports three language modes via the language query parameter:

Supported Audio Formats#

Voice accepts the following audio formats through both the batch and streaming endpoints:

Maximum file size is 25 MB by default, configurable via the MAX_FILE_SIZE_MB environment variable.

Model Configuration#

Transcription History#

All transcriptions are persisted to the database and queryable via the list endpoint:

curl http://localhost:8003/api/v1/transcriptions?page=1&page_size=20

The analytics endpoint provides aggregate statistics across all transcriptions:

curl http://localhost:8003/api/v1/analytics