Models, languages, and voices
Look up every HUMAIN Voice language value, speech-to-text model, diarization level, text-to-speech model, and voice, with the matching SDK 0.18.1 constants.
Each workflow takes a different set of selectors. Language applies to every speech-to-text workflow except live diarization. An automatic speech recognition (ASR) model applies to batch and fast transcription only. Diarization levels apply to batch. Text-to-speech takes a model and a voice. To choose the workflow itself, see Concepts.
Languages
The JavaScript and Python SDKs export the same Language members.
| Wire value | JavaScript | Python | Language byte | Speech |
|---|---|---|---|---|
ar | Language.Ar | stt.Language.Ar | 0 | Arabic |
en | Language.En | stt.Language.En | 1 | English |
codeswitch | Language.ArEn | stt.Language.ArEn | 2 | Arabic and English mixed in one recording |
auto | — | — | 255 | Service default |
The wire value goes in the batch URL path and in fast and HTTP streaming query parameters. The language byte is byte 17 of realtime frame headers (byte 16 of a direct Socket.IO fast packet). Diarization frames validate it but ignore it.
auto resolves to the default configured for the environment, which is currently the
code-switching model. SDK 0.18.1 has no constant for it, so send it only from a direct API
integration. On fast and HTTP streaming routes, omitting the language has the same effect. If you
don't know which language the audio is in, use codeswitch; it handles Arabic, English, and both.
Speech-to-text models
Batch and fast transcription accept an ASR model key. Realtime transcription and live diarization
take no model: startStream() / start_stream() accepts a language only, and the service picks
the recognizer.
| Key | Enum member (BatchTranscriptionModel / FastTranscriptionModel) | Languages | Batch | Fast | Status |
|---|---|---|---|---|---|
bayan_cs_ar_en | BayanArEn | Arabic, English, code-switch | Yes | Yes | Recommended; follows the latest release |
bayan_cs_ar_en_v2 | BayanArEnV2 | Arabic, English, code-switch | Yes | Yes | Pinned to the current release |
bayan_ar | BayanAr | Arabic | Yes | Yes | Current |
nida_8k_ar | NidaArTelephony | Arabic, 8 kHz telephony | Yes | No | Current; batch only |
bayan_auto | — | Any | Yes | Yes | Default for auto; no SDK constant, pass the string |
nida_ar | NidaAr | — | Yes | Yes | Supported |
fast_en | FastEn | — | Yes | Yes | Supported |
Use the pipeline-specific enums: BatchTranscriptionModel for batch and FastTranscriptionModel
for fast, for example BatchTranscriptionModel.BayanArEn (Python:
stt.BatchTranscriptionModel.BayanArEn). Both are exported from humain_voice.stt in Python.
The asr and asr_model parameters also accept a plain key string. FastTranscriptionModel leaves
out NidaArTelephony because it is a batch-only telephony model. The older ASRModel enum
holds all seven SDK members and is kept for compatibility.
| Workflow | Model parameter |
|---|---|
| Batch | Optional asr. When omitted, the service uses the configured default for the language. |
| Fast (SDK) | Required: transcribe() takes a language and a model. |
| Fast (direct API) | Optional. HTTP takes asr (alias model); a direct Socket.IO packet takes an asr_model_key field. When omitted or empty, the service uses the language default. |
| Realtime, live diarization | None. |
An unknown key, or no default configured for the language or for auto, returns 400 ASR_MODEL_NOT_FOUND. An
SDK constant doesn't guarantee that a model is provisioned for your key; handle that error. See
Error codes.
Choosing a model by use case
| Use case | Language | Model |
|---|---|---|
| Arabic, English, or mixed speech (default) | codeswitch | bayan_cs_ar_en |
| Results must not change when a new release ships | codeswitch | bayan_cs_ar_en_v2 |
| Arabic-only recordings | ar | bayan_ar |
| 8 kHz phone-call recordings in Arabic | ar | nida_8k_ar (batch) |
| Live audio | codeswitch | None; realtime picks the model |
ITN and redaction are batch options; see Batch REST API.
Speaker diarization levels
Set the diarization parameter on a batch job to label who spoke when. Live diarization has no
level: the service picks the model.
| Value | SDK 0.18.1 constant | Meaning |
|---|---|---|
0 or false | BatchDiarization.Off | Off. Omitting the parameter also turns diarization off. |
1 or true | BatchDiarization.On | On with the default level, currently d1. |
d1 | BatchDiarization.D1 | Balanced accuracy and speed. |
d2 | BatchDiarization.D2 | Recordings with more than 4 speakers. Slowest. |
d3 | — | Up to 4 speakers. Fastest. Audio shorter than 1 s returns no segments. |
Each level has its own maximum audio duration; see Batch transcription limits.
SDK 0.18.1 has no d3 constant and accepts only BatchDiarization members. Use
BatchDiarization.On, which resolves to d1 today, or send diarization=d3 through the
Batch REST API to pin it. In Python, import BatchDiarization from
humain_voice.stt.batchtranscription.
Speaker labels are relative to one result; see speaker timelines in Concepts.
Text-to-speech
Text-to-speech has one model, nebula (TtsModel.Nebula in both SDKs). SDK 0.18.1 sends it when
you omit model; on a direct Socket.IO integration, send model: "nebula" explicitly. Output is
raw PCM16 audio; sample rates per route are in Concepts.
Each request needs exactly one voice selector:
| Selector | Value |
|---|---|
voice_id | The id of a voice from the voice list. |
voice_references | One base64 mono PCM16 WAV clip and its transcript, to adapt the voice to a speaker. Limits are in Text to speech limits. |
Voice list
listVoices() / list_voices() returns multilingual voice profiles. Without the SDK, emit the
Socket.IO tts_voice_list event; see Voice list. There is no
HTTP voice-list route, so HTTP text-to-speech integrations get IDs the same way. Each item has:
| Field | Meaning |
|---|---|
id | Profile UUID. Send it as voice_id. The service rejects internal physical-variant IDs. |
label | Human-readable name, such as mul_youssef. Display it; don't match on it. |
profile.speaker.gender | male or female. |
profile.speaker.dialect | BCP-47 tag for the speaker's base dialect, such as arz. |
profile.languages | BCP-47 tags the voice can speak, such as ["ar", "en"]. |
profile.emotions | Emotions the voice can speak, neutral first. Absent where emotion and speaking style aren't enabled. SDK 0.18.1, or 0.19.0-beta.3 or later (Python: 0.18.1, or 0.19.0b3 or later). |
profile.styles | Speaking styles the voice can use, such as ["news"]. Absent where they aren't enabled or the voice has none. SDK 0.18.1, or 0.19.0-beta.3 or later (Python: 0.18.1, or 0.19.0b3 or later). |
Voices available at the time of writing, all speaking Arabic and English:
| Label | Dialect |
|---|---|
mul_nourah, mul_abdullah, mul_sara, mul_abdulaziz | ars (Saudi Arabic) |
mul_fadi | apc (Levantine Arabic) |
mul_yassin | ary (Moroccan Arabic) |
mul_youssef | arz (Egyptian Arabic) |
IDs and the list can differ per environment, so look them up with the example below instead of hard-coding them. An empty list is a valid result; don't fall back to a guessed ID.
import { TTSClient } from '@humain-voice/sdk';
function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
const value = process.env[name];
if (!value) throw new Error(`${name} is required`);
return value;
}
function socketPath(): { api_path?: string } {
const value = process.env.API_PATH;
return value ? { api_path: value } : {};
}
async function main(): Promise<void> {
const client = new TTSClient({
api_url: requiredEnv('API_URL'),
api_key: requiredEnv('API_KEY'),
...socketPath(),
});
try {
for (const voice of await client.listVoices({ timeoutSeconds: 5 })) {
const dialect = voice.profile?.speaker.dialect ?? '';
const languages = voice.profile?.languages.join(',') ?? '';
console.info(voice.id, voice.label, dialect, languages);
}
} finally {
await client.close();
}
}
void main().catch((error: unknown) => {
console.error(error);
process.exitCode = 1;
});
Expected output (illustrative; IDs vary by environment):
42e38a63-849a-481a-b5bf-3c1b7a985de3 mul_nourah ars ar,en
2f66da2d-eb4d-4376-b2fe-5631cebe1db7 mul_fadi apc ar,en
af52a907-1086-46f7-8f5d-72317875d7bd mul_youssef arz ar,enLanguage selection in a voice
You don't pass a language to text-to-speech. If text contains any Arabic-script letter, the voice
speaks Arabic; otherwise it speaks English. Numbers, punctuation, emoji, whitespace, and letters
from other scripts don't select Arabic.