Realtime transcription

Stream PCM16 audio and receive partial and final transcripts with Perigee-1-transcribe-realtime.

Perigee-1-transcribe-realtime receives audio over WebSocket and emits transcript events at approximately 200 ms end-to-end transcription latency.

Endpoint and audio format

wss://api.orbitalsai.com/api/v1/streaming/transcribe?token=<API_KEY>

Send binary audio frames as PCM16 little-endian, mono audio. Use a 16 kHz sample rate and make the configuration match the source.

Connection lifecycle

Open the authenticated WebSocket.
Wait for ready.
Send a config message.
Send binary PCM audio frames.
Render partial events as replaceable draft text.
Persist final events.
Send {"type":"flush"} when the source ends.
Wait for flushed, then close the connection.

Configure the session

{
  "type": "config",
  "language": "hausa",
  "sample_rate": 16000,
  "return_timestamps": true
}

Set the expected language explicitly. Automatic mixed-language detection is not supported.

Events

Event	Use
`ready`	Connection accepted and ready for configuration or audio.
`speech_start`	Voice activity detection found speech.
`partial`	Replaceable draft transcript for the current segment.
`speech_end`	Voice activity detection found the end of an utterance.
`final`	Stable transcript with `segment_id` and optional timestamps.
`flushed`	Buffered audio has been finalized.
`error`	The request or session cannot continue.

When return_timestamps is enabled, a final event may include:

{
  "type": "final",
  "segment_id": 7,
  "text": "Sannu da zuwa",
  "timestamps": [
    { "start": 0.0, "end": 0.48, "text": "Sannu" },
    { "start": 0.49, "end": 0.91, "text": "da" },
    { "start": 0.92, "end": 1.42, "text": "zuwa" }
  ]
}

Python async SDK

import asyncio
import os
from orbitalsai.streaming import (
    AsyncStreamingClient,
    StreamingConfig,
    StreamingEventHandlers,
)
 
class Handlers(StreamingEventHandlers):
    def on_transcript_partial(self, text):
        print(f"\r{text}", end="", flush=True)
 
    def on_transcript_final(self, text, metadata):
        print(f"\n{text}")
        print(metadata.get("timestamps", []))
 
async def main():
    config = StreamingConfig(
        language="hausa",
        sample_rate=16000,
        return_timestamps=True,
    )
 
    async with AsyncStreamingClient(
        api_key=os.environ["ORBITALSAI_API_KEY"],
        config=config,
    ) as client:
        await client.connect(Handlers())
        with open("audio.pcm", "rb") as audio:
            while chunk := audio.read(16000):
                await client.send_audio(chunk)
                await asyncio.sleep(0.5)
        await client.flush()
 
asyncio.run(main())

Endpoint and audio format

Connection lifecycle

Configure the session

Events

Python async SDK

Next steps

On this page