API Guides

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

EventDirectionPayload
audio_fileSendBinary packet below.
audio_file_upload_successReceive{ id }. A receipt only: a format or duration error can still follow.
transcription_resultReceiveid, seq, transcription, words (start_time, end_time, word), is_final.
errorReceiveStructured error.

Send the whole file as raw bytes, not JSON or base64. Length fields are unsigned 16-bit little-endian.

audio_file packet
FieldBytesValue / meaning
UUID0–15Request ID.
Language160 ar, 1 en, 2 codeswitch, 255 auto.
ASR key length17–18Length N of the model key; 0 selects the language default.
ASR keyN bytesUTF-8 model key, such as bayan_cs_ar_en.
Reserved keys19+N–24+NDiarization, ITN, and redaction key lengths. Send 6 zero bytes.
Audio25+N–endThe 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

EventDirectionPayload
audio_streamSendBinary frame below; returns transcription_result.
diarization_streamSendSame frame; returns diarization_result only.
transcription_resultReceiveid, seq, transcription, words, is_final, is_speech_final.
diarization_resultReceiveid, final_segments, active_segments (start_time, end_time, speaker), is_final.
errorReceiveStructured error.

The obsolete speaker_id event returns METHOD_NOT_ALLOWED.

audio_stream and diarization_stream frame
FieldBytesValue / meaning
UUID0–15Same UUID for every frame of one stream.
Flags16Bit 0 start, bit 1 final, bit 2 diarization tee; other bits 0.
Language170 ar, 1 en, 2 codeswitch, 255 auto. Diarization accepts any of these values and ignores it.
PCM18–endPCM16 little-endian, 16 kHz, mono; even, non-zero length.
Frameaudio_stream flagsWith diarization tee
First15
Middle04
Last26
Only frame37

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

EventDirectionPayload
ttsSendJSON request below.
tts_audioReceiveBinary frame below.
errorReceiveStructured error.
FieldRequiredValue
idYesRequest UUID.
textYesPlain text, not SSML, with at least one letter or number. Length limits.
modelNo (send nebula)nebula. Omitted, the deployment's default applies.
voice_idOne of these twoA profile id from the voice list.
voice_referencesOne of these twoOne item, { audio, text }: mono PCM16 WAV in standard base64 (no line breaks, not URL-safe) and its transcript.
tts_audio frame
FieldBytesValue / meaning
UUID0–15The request id.
Header16Bit 0 set on the last frame; other bits 0.
PCM17–endPCM16 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.

WorkflowWhen your client disconnects
Fast transcriptionThere is no resume, replay or idempotency contract. Don't resend blindly; if you do, use a fresh UUID.
Realtime transcription, live diarizationThe stream ends. Keep committed results and start a new stream with a fresh UUID.
Text to speechThe 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:

ErrorTrigger
PAYLOAD_TOO_LARGEA fast upload over 64 MiB, or a realtime frame over 16 MiB.
CREDITS_EXHAUSTEDThe account ran out of credit mid-stream.
BILLING_AUTHORIZATION_UNAVAILABLEBilling couldn't authorize the stream mid-stream.

A Socket.IO disconnect carries no application close code; treat the error event as the signal.

Next steps

On this page