WebSocket Connection

Connect to WebSocket for real-time audio streaming and transcription.

Connection URLs

For Microphone Input:

wss://realtime.scriptix.io/v2/realtime?token={token}&type={modelType}&language={language}

For Stream Input:

wss://realtime.scriptix.io/v2/client/{token}?url={streamUrl}&language={language}&type={modelType}

Query Parameters

Parameter	Required	Description
token	Yes	Authentication token
type	Yes	Model type: "fast" or "quality"
language	No	Language code (e.g., "en", "nl", "fr", "de")
url	Conditional	Stream URL (required for stream mode)

Connection Timeout

The WebSocket connection has a 15-second timeout. If the connection is not established within this time, it will be closed with a timeout error.

Sending Data

Start Command (Microphone Mode)

After establishing the connection, send a start command:

{
  "action": "start"
}

Audio Data

Send raw audio data as binary (ArrayBuffer) directly through the WebSocket.

Receiving Messages

State Messages

Loading State:

{
  "state": "loading"
}

Listening State:

{
  "state": "listening"
}

Transcription Messages

Partial Result:

{
  "text": "partial transcription text",
  "is_final": false,
  "offset_ms": 1500,
  "stability": 0.85
}

Final Result:

{
  "text": "complete transcription text",
  "is_final": true,
  "offset_ms": 2500,
  "words": [
    ["word1", 0, 500, 0.95],
    ["word2", 600, 800, 0.92]
  ],
  "speaker": "Speaker 1"
}

Words array format: [word, start_ms, end_ms, confidence]

Error Messages

{
  "error": "error description"
}

Connection States

The connection progresses through these states:

• disconnected - Not connected
• connecting - Establishing connection
• loading - Connection established, loading model
• listening - Ready to receive audio (stream mode)
• connected - Actively transcribing
• error - Connection error occurred

WebSocket Close Codes

Code	Description
1000	Normal closure
1006	Abnormal closure - connection failed before establishment

Error Scenarios

Common connection errors:

• Missing Token: Configuration requires authentication token
• Missing Stream URL: Stream mode requires streamUrl parameter
• Connection Timeout: Server unable to connect within 15 seconds (code will close connection)
• Invalid Stream: Stream URL invalid, expired, or inaccessible
• CORS Restrictions: Stream doesn't allow cross-origin requests
• Unsupported Format: Stream format not supported by server
• Authentication Required: Stream requires authentication

Audio Source Modes

Microphone Mode

Connect using /v2/realtime endpoint with token, type, and optional language parameters. After connection, send the start command, then stream binary audio data.

Stream Mode

Connect using /v2/client/{token} endpoint with url, type, and optional language parameters. The server fetches and processes audio from the provided stream URL.

Supported Stream Types:

• Direct MP3/M3U8 file URLs
• Azure Blob Storage URLs

Note: Icecast/Shoutcast live streams may have compatibility issues due to CORS restrictions and persistent connection requirements.

Next Steps

• Message Protocol - Complete protocol reference
• Audio Formats - Audio specifications