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 valueJavaScriptPythonLanguage byteSpeech
arLanguage.Arstt.Language.Ar0Arabic
enLanguage.Enstt.Language.En1English
codeswitchLanguage.ArEnstt.Language.ArEn2Arabic and English mixed in one recording
auto——255Service 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.

KeyEnum member (BatchTranscriptionModel / FastTranscriptionModel)LanguagesBatchFastStatus
bayan_cs_ar_enBayanArEnArabic, English, code-switchYesYesRecommended; follows the latest release
bayan_cs_ar_en_v2BayanArEnV2Arabic, English, code-switchYesYesPinned to the current release
bayan_arBayanArArabicYesYesCurrent
nida_8k_arNidaArTelephonyArabic, 8 kHz telephonyYesNoCurrent; batch only
bayan_auto—AnyYesYesDefault for auto; no SDK constant, pass the string
nida_arNidaAr—YesYesSupported
fast_enFastEn—YesYesSupported

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.

WorkflowModel parameter
BatchOptional 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 diarizationNone.

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 caseLanguageModel
Arabic, English, or mixed speech (default)codeswitchbayan_cs_ar_en
Results must not change when a new release shipscodeswitchbayan_cs_ar_en_v2
Arabic-only recordingsarbayan_ar
8 kHz phone-call recordings in Arabicarnida_8k_ar (batch)
Live audiocodeswitchNone; 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.

ValueSDK 0.18.1 constantMeaning
0 or falseBatchDiarization.OffOff. Omitting the parameter also turns diarization off.
1 or trueBatchDiarization.OnOn with the default level, currently d1.
d1BatchDiarization.D1Balanced accuracy and speed.
d2BatchDiarization.D2Recordings 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:

SelectorValue
voice_idThe id of a voice from the voice list.
voice_referencesOne 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:

FieldMeaning
idProfile UUID. Send it as voice_id. The service rejects internal physical-variant IDs.
labelHuman-readable name, such as mul_youssef. Display it; don't match on it.
profile.speaker.gendermale or female.
profile.speaker.dialectBCP-47 tag for the speaker's base dialect, such as arz.
profile.languagesBCP-47 tags the voice can speak, such as ["ar", "en"].
profile.emotionsEmotions 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.stylesSpeaking 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:

LabelDialect
mul_nourah, mul_abdullah, mul_sara, mul_abdulazizars (Saudi Arabic)
mul_fadiapc (Levantine Arabic)
mul_yassinary (Moroccan Arabic)
mul_youssefarz (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.

list-voices.ts
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,en

Language 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.

Next steps

On this page