Socket.IO API
Connect to HUMAIN Voice over Socket.IO and exchange the raw events and binary frames for fast transcription, realtime transcription, live diarization, voice lookup, and text to speech.
Use this protocol directly when your runtime has no HUMAIN Voice SDK. The JavaScript and Python SDKs build these frames for you.
Connect
One connection serves every workflow. Send x-api-key and Origin as HTTP headers on the WebSocket
upgrade request, and use the WebSocket transport; polling isn't supported. Details and the legacy
path: Authentication.
import { io } from "socket.io-client";
const API_URL = process.env.API_URL!;
const socket = io(API_URL, {
path: process.env.API_PATH ?? "/socket.io",
transports: ["websocket"],
extraHeaders: {
"x-api-key": process.env.API_KEY!,
Origin: new URL(API_URL).origin,
},
});
// Binary frames carry the request UUID as 16 raw bytes.
const uuidBytes = (id: string) => Buffer.from(id.replaceAll("-", ""), "hex");
socket.on("error", (err) => console.error("error:", err));
await new Promise((resolve, reject) => {
socket.once("connect", resolve);
socket.once("connect_error", reject);
});The server speaks Socket.IO protocol v5 (Engine.IO v4, so socket.io-client 3.x or 4.x) on the
default / namespace. Binary frames carry UUIDs as 16 bytes in RFC 4122 order, the same order
as the hex string.
Give every request or stream its own UUID; responses echo it as id, so route by it. Failures
arrive on the error event with code, retryable, and id when parseable; see
Errors and limits.
Fast transcription events
| Event | Direction | Payload |
|---|---|---|
audio_file | Send | Binary packet below. |
audio_file_upload_success | Receive | { id }. A receipt only: a format or duration error can still follow. |
transcription_result | Receive | id, seq, transcription, words (start_time, end_time, word), is_final. |
error | Receive | Structured error. |
Send the whole file as raw bytes, not JSON or base64. Length fields are unsigned 16-bit little-endian.
| Field | Bytes | Value / meaning |
|---|---|---|
| UUID | 0–15 | Request ID. |
| Language | 16 | 0 ar, 1 en, 2 codeswitch, 255 auto. |
| ASR key length | 17–18 | Length N of the model key; 0 selects the language default. |
| ASR key | N bytes | UTF-8 model key, such as bayan_cs_ar_en. |
| Reserved keys | 19+N–24+N | Diarization, ITN, and redaction key lengths. Send 6 zero bytes. |
| Audio | 25+N–end | The complete AAC, FLAC, MP3, MP4, or WAV file. |
Put an MP4 file's moov atom at the front: the upload is read forward-only, so a trailing moov
fails to decode. Language values and model keys are in Models.
import { randomUUID } from "node:crypto";
import { readFileSync } from "node:fs";
const key = Buffer.from("bayan_cs_ar_en");
const len = (n: number) => { const b = Buffer.alloc(2); b.writeUInt16LE(n); return b; };
const fastId = randomUUID();
socket.on("transcription_result", (r) => {
if (r.id === fastId && r.is_final) console.log("final:", r.transcription);
});
socket.emit("audio_file", Buffer.concat([
uuidBytes(fastId), Buffer.of(2), len(key.length), key,
len(0), len(0), len(0), readFileSync("recording.wav"),
]));The request is done at the transcription_result with is_final: true. Full schemas:
Fast transcription events.
Realtime transcription events
| Event | Direction | Payload |
|---|---|---|
audio_stream | Send | Binary frame below; returns transcription_result. |
diarization_stream | Send | Same frame; returns diarization_result only. |
transcription_result | Receive | id, seq, transcription, words, is_final, is_speech_final. |
diarization_result | Receive | id, final_segments, active_segments (start_time, end_time, speaker), is_final. |
error | Receive | Structured error. |
The obsolete speaker_id event returns METHOD_NOT_ALLOWED.
| Field | Bytes | Value / meaning |
|---|---|---|
| UUID | 0–15 | Same UUID for every frame of one stream. |
| Flags | 16 | Bit 0 start, bit 1 final, bit 2 diarization tee; other bits 0. |
| Language | 17 | 0 ar, 1 en, 2 codeswitch, 255 auto. Diarization accepts any of these values and ignores it. |
| PCM | 18–end | PCM16 little-endian, 16 kHz, mono; even, non-zero length. |
| Frame | audio_stream flags | With diarization tee |
|---|---|---|
| First | 1 | 5 |
| Middle | 0 | 4 |
| Last | 2 | 6 |
| Only frame | 3 | 7 |
Bit 2 sends that frame's audio to diarization, and diarization_result events arrive on the same
connection with the same id. Set it on every frame of the stream: frames without it never reach
diarization, and a partly teed stream gets no diarization final and ends in DIARIZATION_FAILED.
On diarization_stream, use bits 0 and 1 only. Send 3,200 bytes
(100 ms) per frame at real-time pace. The server rejects a frame shorter than 18 bytes, with an
all-zero UUID, an undefined flag bit, an unknown language byte, or empty or odd-length audio.
const streamId = randomUUID();
socket.on("transcription_result", (r) => {
if (r.id === streamId) console.log(r.is_final ? "final:" : "partial:", r.transcription);
});
const pcm = readFileSync("recording.pcm");
for (let off = 0; off < pcm.length; off += 3200) {
const flags = (off === 0 ? 1 : 0) | (off + 3200 >= pcm.length ? 2 : 0);
socket.emit("audio_stream", Buffer.concat([uuidBytes(streamId), Buffer.of(flags, 2 /* codeswitch */), pcm.subarray(off, off + 3200)]));
await new Promise((r) => setTimeout(r, 100));
}After the last frame, keep listening until a result with is_final: true arrives. With the tee,
transcription_result and diarization_result each send their own is_final: true, and the
diarization one can arrive later, so wait for both. To apply
provisional and final results and merge speaker segments, see
Concepts. Full schemas:
Realtime events.
Text-to-speech events
| Event | Direction | Payload |
|---|---|---|
tts | Send | JSON request below. |
tts_audio | Receive | Binary frame below. |
error | Receive | Structured error. |
| Field | Required | Value |
|---|---|---|
id | Yes | Request UUID. |
text | Yes | Plain text, not SSML, with at least one letter or number. Length limits. |
model | No (send nebula) | nebula. Omitted, the deployment's default applies. |
voice_id | One of these two | A profile id from the voice list. |
voice_references | One of these two | One item, { audio, text }: mono PCM16 WAV in standard base64 (no line breaks, not URL-safe) and its transcript. |
| Field | Bytes | Value / meaning |
|---|---|---|
| UUID | 0–15 | The request id. |
| Header | 16 | Bit 0 set on the last frame; other bits 0. |
| PCM | 17–end | PCM16 little-endian, 24 kHz, mono, no WAV header. |
Append bytes 17 onward from every frame for your id, including the last one. voiceId comes from
the voice list.
const ttsId = randomUUID();
const chunks: Buffer[] = [];
socket.on("tts_audio", (data: ArrayBuffer) => {
const frame = Buffer.from(data);
if (!frame.subarray(0, 16).equals(uuidBytes(ttsId))) return;
chunks.push(frame.subarray(17));
if (frame[16] & 1) console.log("done:", Buffer.concat(chunks).length, "bytes");
});
socket.emit("tts", { id: ttsId, text: "Hello from HUMAIN Voice", model: "nebula", voice_id: voiceId });Synthesis that runs past 25 seconds ends with retryable TTS_DEADLINE_EXCEEDED; discard the
partial audio. To make the PCM playable, see
Text to speech: save or stream. Full schemas:
TTS events.
Voice list
Emit tts_voice_list with {}; the server answers with one tts_voice_list_result event
carrying an array of voice profiles. Every item has id, label, and profile:
[
{
"id": "42e38a63-849a-481a-b5bf-3c1b7a985de3",
"label": "mul_nourah",
"profile": { "speaker": { "gender": "female", "dialect": "ars" }, "languages": ["ar", "en"] }
}
]const voices = await new Promise<{ id: string; label: string }[]>((resolve) => {
socket.once("tts_voice_list_result", resolve);
socket.emit("tts_voice_list", {});
});
const voiceId = voices[0]?.id;A failed lookup emits TTS_VOICE_LIST_FAILED on error with no id, so bound the wait with a
timeout. IDs differ per environment, and an empty array is a valid answer. Field meanings and the current
voices are in Models.
Disconnects
Results go only to the connection that sent the request. Nothing resumes after a reconnect; there is no replay contract.
| Workflow | When your client disconnects |
|---|---|
| Fast transcription | There is no resume, replay or idempotency contract. Don't resend blindly; if you do, use a fresh UUID. |
| Realtime transcription, live diarization | The stream ends. Keep committed results and start a new stream with a fresh UUID. |
| Text to speech | The server cancels that connection's syntheses and sends no further audio or errors for them. Other connections are unaffected. |
The server disconnects you after these errors, always emitting the error event first:
| Error | Trigger |
|---|---|
PAYLOAD_TOO_LARGE | A fast upload over 64 MiB, or a realtime frame over 16 MiB. |
CREDITS_EXHAUSTED | The account ran out of credit mid-stream. |
BILLING_AUTHORIZATION_UNAVAILABLE | Billing couldn't authorize the stream mid-stream. |
A Socket.IO disconnect carries no application close code; treat the error event as the signal.