atlas/docs/ASR_API_CONTRACT.md

ASR API Contract

API specification for the Automatic Speech Recognition (ASR) service.

Overview

The ASR service converts audio input to text. It supports streaming audio for real-time transcription.

Base URL

http://localhost:8001/api/asr

(Configurable port and host)

Endpoints

1. Health Check

GET /health

Response:

{
  "status": "healthy",
  "model": "faster-whisper",
  "model_size": "base",
  "language": "en"
}

2. Transcribe Audio (File Upload)

POST /transcribe
Content-Type: multipart/form-data

Request:

• audio: Audio file (WAV, MP3, FLAC, etc.)
• language (optional): Language code (default: "en")
• format (optional): Response format ("text" or "json", default: "text")

Response (text format):

This is the transcribed text.

Response (json format):

{
  "text": "This is the transcribed text.",
  "segments": [
    {
      "start": 0.0,
      "end": 2.5,
      "text": "This is the transcribed text."
    }
  ],
  "language": "en",
  "duration": 2.5
}

3. Streaming Transcription (WebSocket)

WS /stream

Client → Server:

• Send audio chunks (binary)
• Send {"action": "end"} to finish

Server → Client:

{
  "type": "partial",
  "text": "Partial transcription..."
}

{
  "type": "final",
  "text": "Final transcription.",
  "segments": [...]
}

4. Get Supported Languages

GET /languages

Response:

{
  "languages": [
    {"code": "en", "name": "English"},
    {"code": "es", "name": "Spanish"},
    ...
  ]
}

Error Responses

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Error Codes:

• INVALID_AUDIO: Audio file is invalid or unsupported
• TRANSCRIPTION_FAILED: Transcription process failed
• LANGUAGE_NOT_SUPPORTED: Requested language not supported
• SERVICE_UNAVAILABLE: ASR service is unavailable

Rate Limiting

• File upload: 10 requests/minute
• Streaming: 1 concurrent stream per client

Audio Format Requirements

• Format: WAV, MP3, FLAC, OGG
• Sample Rate: 16kHz recommended (auto-resampled)
• Channels: Mono or stereo (converted to mono)
• Bit Depth: 16-bit recommended

Performance

• Latency: < 500ms for short utterances (< 5s)
• Accuracy: > 95% WER for clear speech
• Model: faster-whisper (base or small)

Integration

With Wake-Word Service

1. Wake-word detects activation
2. Sends "start" signal to ASR
3. ASR begins streaming transcription
4. Wake-word sends "stop" signal
5. ASR returns final transcription

With LLM

1. ASR returns transcribed text
2. Text sent to LLM for processing
3. LLM response sent to TTS

Example Usage

Python Client

import requests

# Transcribe file
with open("audio.wav", "rb") as f:
    response = requests.post(
        "http://localhost:8001/api/asr/transcribe",
        files={"audio": f},
        data={"language": "en", "format": "json"}
    )
    result = response.json()
    print(result["text"])

JavaScript Client

// Streaming transcription
const ws = new WebSocket("ws://localhost:8001/api/asr/stream");

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === "final") {
        console.log("Transcription:", data.text);
    }
};

// Send audio chunks
const audioChunk = ...; // Audio data
ws.send(audioChunk);

Future Enhancements

• Speaker diarization
• Punctuation and capitalization
• Custom vocabulary
• Confidence scores per word
• Multiple language detection