Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

HUMAIN Voice Python SDK

The official Python SDK for HUMAIN Voice services. It supports:

  • Fast Transcription (file-based, async and sync)
  • Realtime STT (streaming audio over Socket.IO)
  • Batch Transcription (HTTP polling)
  • Live Diarization
  • ASR subtitle helpers for SRT and WebVTT
  • Text-to-Speech

Installation

pip install humain-voice

Requires Python >= 3.10.

Import path

Use humain_voice for new code:

from humain_voice import stt

The legacy import path still works for now, but emits a deprecation warning.

Configuration

Set the following environment variables provided by HUMAIN Voice:

  • API_URL: Base URL of the ASR service (e.g. https://api.example.com)
  • API_PATH: Socket.IO path. Optional — defaults to /socket.io, the single path that serves every subsystem (realtime, fast transcription, TTS, diarization) on consolidated platform endpoints. Endpoints that have not consolidated yet require an explicit path — in particular, sautech.humain.com serves /realtime/socket.io, not the unprefixed default. Also set it to override for a self-hosted or proxied deployment.
  • API_KEY: Your API key

You can export these in your shell:

export API_URL="https://api.example.com"
export API_PATH="/socket.io"
export API_KEY="<your_api_key>"

Fast Transcription (sync)

Context manager

import os
from pathlib import Path
from humain_voice import stt

audio_path = Path("samples/king_fahad_test.wav")

with stt.FastTranscriptionClient(
    api_url=os.getenv("API_URL"),
    api_key=os.getenv("API_KEY"),
    api_path=os.getenv("API_PATH"),
) as client:
    with audio_path.open("rb") as f:
        result = client.transcribe_sync(
            f,  # file-like object or bytes via f.read()
            stt.Language.ArEn,
            stt.ASRModel.BayanArEn,
        )
        print(result)

Manual (no context manager)

import os
from pathlib import Path
from humain_voice import stt

audio_path = Path("samples/king_fahad_test.wav")

client = stt.FastTranscriptionClient(
    api_url=os.getenv("API_URL"),
    api_key=os.getenv("API_KEY"),
    api_path=os.getenv("API_PATH"),
)

with audio_path.open("rb") as f:
    result1 = client.transcribe_sync(
        f,
        stt.Language.ArEn,
        stt.ASRModel.BayanArEn,
    )
    print(result1)

with audio_path.open("rb") as f:
    result2 = client.transcribe_sync(
        f.read(),
        stt.Language.ArEn,
        stt.ASRModel.BayanArEn,
    )
    print(result2)

client.close_sync()

Fast Transcription (async)

Context manager

import os
import asyncio
from pathlib import Path
from humain_voice import stt

async def main():
    audio_bytes = Path("samples/king_fahad_test.wav").read_bytes()
    async with stt.FastTranscriptionClient(
        api_url=os.getenv("API_URL"),
        api_key=os.getenv("API_KEY"),
        api_path=os.getenv("API_PATH"),
    ) as client:
        result = await client.transcribe(
            audio_bytes,
            stt.Language.ArEn,
            stt.ASRModel.BayanArEn,
        )
        print(result)

asyncio.run(main())

Manual (no context manager)

import os
import asyncio
from pathlib import Path
from humain_voice import stt

async def main():
    audio_bytes = Path("samples/king_fahad_test.wav").read_bytes()

    client = stt.FastTranscriptionClient(
        api_url=os.getenv("API_URL"),
        api_key=os.getenv("API_KEY"),
        api_path=os.getenv("API_PATH"),
    )

    result1 = await client.transcribe(
        audio_bytes,
        stt.Language.ArEn,
        stt.ASRModel.BayanArEn,
    )
    print(result1)

    result2 = await client.transcribe(
        audio_bytes,
        stt.Language.ArEn,
        stt.ASRModel.BayanArEn,
    )
    print(result2)

    await client.close()

asyncio.run(main())

You can also pass on_response, on_file_upload, and on_error callbacks to receive intermediate updates and handle lifecycle events during processing.

Realtime Streaming

import asyncio
import os
import wave
from humain_voice import stt

async def run():
    client = stt.RealtimeClient(
        api_url=os.getenv("API_URL"),
        api_key=os.getenv("API_KEY"),
        api_path=os.getenv("API_PATH"),
    )

    stream = await client.start_stream(
        language=stt.Language.ArEn,
        on_connect=lambda: print("connected"),
        on_disconnect=lambda: print("disconnected"),
        on_response=lambda t: print("response:", t),
        on_error=lambda e: print("error:", e),
    )

    with wave.open("samples/king_fahad_test.wav", "rb") as f:
        audio_bytes = f.readframes(f.getnframes())

    chunk_duration_s = 0.1
    sample_rate = 16000
    bytes_per_sample = 2  # 16-bit PCM
    chunk_size = int(sample_rate * bytes_per_sample * chunk_duration_s)

    for start in range(0, len(audio_bytes), chunk_size):
        end = min(start + chunk_size, len(audio_bytes))
        await stream.send(audio_bytes[start:end])
        await asyncio.sleep(chunk_duration_s)

    await stream.close(timeout_seconds=1)

asyncio.run(run())

Parallel streams (single client)

import asyncio
import os
import wave
from humain_voice import stt

async def stream_audio(stream, audio_bytes: bytes):
    chunk_duration_s = 0.1
    sample_rate = 16000
    bytes_per_sample = 2
    chunk_size = int(sample_rate * bytes_per_sample * chunk_duration_s)

    for start in range(0, len(audio_bytes), chunk_size):
        end = min(start + chunk_size, len(audio_bytes))
        await stream.send(audio_bytes[start:end])
        await asyncio.sleep(chunk_duration_s)

    await stream.close(timeout_seconds=1)

async def run():
    client = stt.RealtimeClient(
        api_url=os.getenv("API_URL"),
        api_key=os.getenv("API_KEY"),
        api_path=os.getenv("API_PATH"),
    )

    stream_a = await client.start_stream(
        language=stt.Language.ArEn,
        on_response=lambda t: print("stream A:", t),
    )
    stream_b = await client.start_stream(
        language=stt.Language.ArEn,
        on_response=lambda t: print("stream B:", t),
    )

    with wave.open("samples/king_fahad_test.wav", "rb") as f:
        audio_bytes = f.readframes(f.getnframes())

    await asyncio.gather(
        stream_audio(stream_a, audio_bytes),
        stream_audio(stream_b, audio_bytes),
    )

asyncio.run(run())

Live Diarization

A standalone RealtimeDiarizationClient identifies speakers in real time over the same realtime socket, accumulating a full per-speaker timeline as audio arrives.

import asyncio
import os
import wave
from humain_voice.stt import RealtimeDiarizationClient
from humain_voice.stt.constants import DIARIZATION_RECOMMENDED_CHUNK_BYTES

async def run():
    client = RealtimeDiarizationClient(
        api_url=os.getenv("API_URL"),
        api_key=os.getenv("API_KEY"),
    )

    stream = await client.start_stream(
        on_error=lambda err: print("stream error:", err),
    )

    async def feed():
        with wave.open("samples/king_fahad_test.wav") as w:
            pcm = w.readframes(w.getnframes())
        for off in range(0, len(pcm), DIARIZATION_RECOMMENDED_CHUNK_BYTES):
            await stream.send(pcm[off : off + DIARIZATION_RECOMMENDED_CHUNK_BYTES])
            await asyncio.sleep(0.48)  # 480 ms real-time pace
        timeline = await stream.close()
        print("final timeline:", timeline)

    feeder = asyncio.create_task(feed())
    async for update in stream:
        print(
            f"segments={len(update.segments)} "
            f"newly_finalized={len(update.newly_finalized)} "
            f"actives={len(update.active_segments)} final={update.is_final}"
        )
    await feeder

asyncio.run(run())

Notes:

  • Stream raw PCM16LE mono 16 kHz. The recommended chunk size is 15360 bytes (480 ms = one model inference step). Other sizes are accepted but produce a less steady result cadence.
  • final_segments arrive as per-response deltas; the SDK accumulates them. update.segments is the full best-known timeline; update.newly_finalized is the per-response delta.
  • Active segments may be revised on any update and may overlap (simultaneous speakers).
  • stream.close() sends the terminator frame, waits up to 5 s, and returns the best-known timeline instead of throwing on timeout.

Text-to-Speech (TTS)

List the available voices, then synthesize with one of them:

import os
from humain_voice.tts import TTSClient
from humain_voice.tts.constants import TtsModel

with TTSClient(
    api_url=os.getenv("API_URL"),
    api_key=os.getenv("API_KEY"),
) as client:
    voices = client.list_voices_sync(timeout_seconds=5)
    if not voices:
        raise RuntimeError("No voices available")
    print("voices:", [(v["id"], v["label"]) for v in voices])
    if profile := voices[0].get("profile"):
        print("languages:", profile["languages"])
        print("dialect:", profile["speaker"]["dialect"])
        # Only when the deployment enables emotion control; "neutral" comes first.
        print("emotions:", profile.get("emotions"), "styles:", profile.get("styles"))

    audio = client.synthesize_sync(
        "Hello from HUMAIN Voice TTS",
        voice_id=voices[0]["id"],
        model=TtsModel.Nebula,
        timeout_seconds=30,
    )
    with open("out.pcm", "wb") as f:
        f.write(audio)

Async variants (list_voices, synthesize, synthesize_stream) are available on the same client; synthesize_stream yields audio chunks as they arrive.

Voice Agent sessions

Start a Voice Agent call on your server and return token_response() to the browser, where @humain-voice/agent joins it:

import os
from humain_voice.agent import AgentClient, AgentError

with AgentClient(api_url=os.environ["API_URL"], api_key=os.environ["API_KEY"]) as agent:
    try:
        session = agent.create_session_sync(
            participant={"identity": "user-123"},
            agent={"prompt": "You help {{name}} with their orders.", "intro": "Hi {{name}}!"},
            variables={"name": "Sara"},
        )
    except AgentError as err:
        print(err.status_code, err.code, err.data)
        raise
    print(session.session_id, session.expires_at, session.limits)
    body = session.token_response()

create_session is the async variant. AgentAuthError (401) and AgentRateLimitError (429) subclass AgentError; limits fields are None when there is no limit.

Subtitles (SRT / VTT)

Fast, realtime, and batch ASR responses include timed word offsets. The subtitle helpers group those words into readable cues and render SRT or WebVTT without adding speaker labels.

Fast and batch responses expose subtitles() directly:

result = await ft_client.transcribe(...)
srt = result.subtitles().to_srt()
vtt = result.subtitles().to_vtt()

batch_result = await batch_client.transcribe(...)
srt = batch_result.subtitles().to_srt()

For one-shot conversion, use the module-level helpers:

from humain_voice import stt

srt = stt.to_srt(result)
vtt = stt.to_vtt(batch_result)

Realtime streams can collect stable final responses automatically:

captions = stt.RealtimeSubtitles()
stream = await rt_client.start_stream(
    language=stt.Language.ArEn,
    subtitles=captions,
)

# send audio, then close the stream
await stream.close()
vtt = captions.to_vtt()

Lower-level helpers are available when you already have words or cues:

cues = stt.words_to_cues(result.words)
srt = stt.cues_to_srt(cues)
vtt = stt.cues_to_vtt(cues)

Speaker labels are never rendered. When batch offsets include speaker metadata, speaker changes are used only as cue boundaries.

Defaults follow common caption readability heuristics:

  • up to two lines per cue
  • 42 characters per line
  • splits on sentence endings, long pauses, long cues, and speaker changes
  • forgiving cleanup for common ASR timing issues

Use strict=True when you want validation errors instead of normalization:

captions = result.subtitles(strict=True)
vtt = captions.to_vtt(strict=True)

Strict validation applies to both SRT and VTT output.

Object render methods are intentionally named as conversions: to_srt() and to_vtt(). The lower-level helpers keep input-specific names such as cues_to_srt() and words_to_cues().

Error handling

The SDK exposes a structured error contract aligned with the platform's ErrorResponse. Its fields are all optional, including id, message, code, retryable, timestamp, retry_after_seconds, data, reason, and retry_scope. The error callback always fires; whether an in-flight context is terminated depends on the code's ownership (see ADR-0003).

Error code constants

from humain_voice.errors import (
    ASR_TRANSCRIPTION_FAILED,
    ASR_MODEL_UNAVAILABLE,
    RATE_LIMIT_EXCEEDED,
    TTS_VOICE_LIST_FAILED,
    SERVER_INTERNAL,
    is_asr_code,
    is_tts_code,
    is_request_scoped_code,
    is_realtime_owned,
    is_tts_owned,
)

Unknown future codes pass through as strings. Legacy aliases such as RATE_LIMITED, VALIDATION_FAILED, and INTERNAL_ERROR remain exported for older deployments.

These codes are not retryable unless noted:

  • TTS emotion markup: TTS_EMOTION_MARKUP_INVALID (malformed or unbalanced <emotion> tags), TTS_EMOTION_SEGMENT_COUNT_EXCEEDED and TTS_EMOTION_SEGMENT_TOO_SHORT (both carry the limit in data). They fail the matching synthesis request.
  • BILLING_IDEMPOTENCY_CONFLICT: a TTS request id was reused for a different request. Send a new id.
  • Voice Agent: AUTH_SCOPE_MISSING (the API key lacks a scope the operation needs) and AGENT_SESSION_NOT_FOUND.
  • Constants for the batch job failure reasons INPUT_CHUNK_COUNT_EXCEEDED, OUTPUT_BYTES_EXCEEDED, OUTPUT_TOKENS_EXCEEDED and MODEL_DEADLINE_EXCEEDED are included ahead of the platform returning them; batch jobs don't report a failure reason yet. When they do, only MODEL_DEADLINE_EXCEEDED is retryable.

Socket.IO errors (TTS / realtime STT / fast STT)

The on_error callback receives an ErrorResponse model. Branch on code to decide your policy:

from humain_voice.errors import ASR_TRANSCRIPTION_FAILED, ASR_MODEL_UNAVAILABLE

def on_error(err):
    # err is always non-None; any field can be None.
    print(f"code={err.code} retryable={err.retryable} msg={err.message}")
    if err.code == ASR_MODEL_UNAVAILABLE:
        # Tell the user the model is down; safe to retry later.
        ...
    elif err.code == ASR_TRANSCRIPTION_FAILED:
        # Final terminal error for this stream — no retry.
        ...

The realtime adapter only terminates an ASR stream context for ASR-shaped codes. A TTS_VOICE_LIST_FAILED arriving on the realtime socket fires the global on_error but does not kill the stream.

Batch transcription HTTP errors

BatchTranscribeError (and its subclasses) carry a structured payload plus per-field accessors:

from humain_voice.stt.batchtranscription import (
    BatchTranscribeClient,
    BatchTranscribeError,
    BatchTranscribeRateLimitError,
)

try:
    result = await client.submit(audio, "ar")
except BatchTranscribeRateLimitError as err:
    # Caller decides retry policy; SDK never retries internally.
    print(f"rate-limited; retry_after={err.retry_after}s capacity={err.capacity}")
except BatchTranscribeError as err:
    print(f"status={err.status_code}")
    print(f"code={err.code} retryable={err.retryable}")
    print(f"detail={err.detail} job_id={err.job_id}")
    print(f"raw_body={err.raw_body!r}")  # always preserved

User-facing message preference: detail → message → error → raw text. err.message already follows that order.

Note. The max_retries constructor argument is deprecated and is a no-op. The SDK never retries — callers decide policy based on err.retryable, err.code, and err.capacity.

LiveKit Agents plugin

humain-voice ships a LiveKit Agents STT/TTS plugin (livekit-agents 1.3.9 or later 1.x):

python -m pip install "humain-voice[livekit]"
import os

from livekit.agents import AgentSession
from livekit.plugins import humain, silero

stt = humain.STT.from_realtime(
    params=humain.RealTimeOptions(api_url=os.environ["API_URL"], api_key=os.environ["API_KEY"]),
)
tts = humain.TTS(
    params=humain.TTSOptions(
        api_url=os.environ["API_URL"],
        api_key=os.environ["API_KEY"],
        voice=os.environ["VOICE_ID"],
    ),
)
session = AgentSession(stt=stt, tts=tts, llm=your_llm, vad=silero.VAD.load())

Unset api_url, api_key, and api_path options fall back to HUMAIN_VOICE_API_URL, HUMAIN_VOICE_API_KEY, and HUMAIN_VOICE_API_PATH. The old SAUTECH_API_* names still work but raise a DeprecationWarning. livekit-plugins-sautech is replaced by this extra.

Types

Common enums are available under humain_voice.stt, for example Language and ASRModel.

Examples

See complete examples in python/examples/ft_client.py and python/examples/rt_client.py; both include subtitle output. The batch transcription example (python/examples/batch_transcribe_client.py) shows structured-error handling and SRT/VTT rendering end-to-end. python/examples/diarization_client.py demonstrates live diarization streaming (feeder + async-iterator pattern).


Changelog

All notable changes to the HUMAIN Voice SDK (Python humain-voice, JS @humain-voice/sdk, Go module) are documented here. The format follows Keep a Changelog, and the project adheres to Semantic Versioning.

Versions are shared across all three language packages; a release tags python/vX.Y.Z, javascript/vX.Y.Z, and golang/vX.Y.Z together. The Teams release notification posts the section matching the tag's version, so keep the top section here current before tagging.

[0.19.0-beta.4] - 2026-10-27

Deprecated

  • BayanArEnV1 (bayan_cs_ar_en_v1) on ASRModel, BatchTranscriptionModel, and FastTranscriptionModel in Python, JavaScript, and Go. The model is retired and no longer served; use BayanArEnV2. The constant will be removed in the next minor release.

[0.19.0-beta.3] - 2026-10-27

Added

  • TTS voice-list profiles can now include optional emotions and styles string lists (Emotions and Styles in Go) in Python, JavaScript, and Go. The platform sends them only when emotion control is enabled; emotions lists neutral first. Only non-empty string entries are kept, names are not checked against a fixed set, and a missing or malformed list is left out without dropping the voice.
  • Python, JavaScript, and Go now export TTS_EMOTION_MARKUP_INVALID, TTS_EMOTION_SEGMENT_COUNT_EXCEEDED, TTS_EMOTION_SEGMENT_TOO_SHORT, BILLING_IDEMPOTENCY_CONFLICT, AUTH_SCOPE_MISSING, AGENT_SESSION_NOT_FOUND, and the batch job failure codes INPUT_CHUNK_COUNT_EXCEEDED, OUTPUT_BYTES_EXCEEDED, OUTPUT_TOKENS_EXCEEDED, and MODEL_DEADLINE_EXCEEDED (CamelCase in Go errcodes, e.g. TTSEmotionMarkupInvalid).

Fixed

  • The three TTS emotion codes and BILLING_IDEMPOTENCY_CONFLICT are now classified as TTS-owned, so they terminate the matching synthesis request instead of leaving it pending until its timeout.

[0.19.0-beta.2] - 2026-10-13

Fixed

  • Python: the LiveKit TTS plugin now uses one request id per sentence in a SynthesizeStream (kept across that sentence's retries). A single id for the whole stream made the server reject every sentence after the first with fingerprint_mismatch, so they were skipped as "billing authorization unavailable". Python-only release; the JavaScript and Go packages stay at 0.19.0-beta.1.

[0.19.0-beta.1] - 2026-10-12

Added

  • Voice Agent sessions (beta). A server helper starts a call with POST /agent/sessions: AgentClient.createSession() from @humain-voice/sdk/agent, AgentClient.create_session() / create_session_sync() from humain_voice.agent, and agent.NewClient(...).CreateSession() in Go. Each returns the session credentials (server_url, participant_token, session_id, expires_at, effective, limits) and raises AgentError, AgentAuthError (401) or AgentRateLimitError (429); Go uses *agent.APIError, *agent.AuthError and *agent.RateLimitError.
  • @humain-voice/agent, a browser package on livekit-client that joins the call: AgentSession.start() with status, agent mode, transcripts, warnings, end reasons, client tools, sendText, interrupt, updateContext, setMicMuted, startAudio and end. It ships with the JavaScript release at the same version.
  • Python: the HUMAIN Voice LiveKit Agents plugin now ships in humain-voice as livekit.plugins.humain, installed with pip install "humain-voice[livekit]" (livekit-agents >=1.3.9,<2). It replaces livekit-plugins-sautech. Unset connection options fall back to HUMAIN_VOICE_API_URL, HUMAIN_VOICE_API_KEY, and HUMAIN_VOICE_API_PATH; SAUTECH_API_* still work with a DeprecationWarning. api_path is now optional (defaults to /socket.io).

Removed

  • Python: the deprecated sautech import path. Import humain_voice instead.

[0.19.0-beta.0] - 2026-09-23

Added

  • BatchDiarization.D3 (d3: 4 speakers or fewer, fastest) in the Python, JavaScript, and Go batch clients. BatchDiarization.On now resolves server-side to d3.
  • BayanAuto (bayan_auto) in the batch, fast, and compatibility ASR model enums in all three languages. It is the default the service uses when no ASR model is sent.

Deprecated

  • NidaAr (nida_ar) and FastEn (fast_en) in every ASR model enum. The API keeps accepting them until 2026-12-31 and then returns ASR_MODEL_NOT_FOUND; use BayanArEnV2 (bayan_cs_ar_en_v2), which serves the same model.

Changed

  • Examples use BayanArEnV2 instead of NidaAr.

[0.18.0] - 2026-08-30

Removed

  • The TTS latency-eagerness option is removed from Python, JavaScript, and Go synthesis APIs and is no longer included in TTS request payloads.

Migration

  • Remove the TTS latency-eagerness argument or option from synthesis calls. The platform owns synthesis latency behavior; no replacement option is required.

[0.17.3] - 2026-08-30

Added

  • Python, JavaScript, and Go now export TTS_INPUT_NOT_ALLOWED and TTS_MODERATION_UNAVAILABLE (TTSInputNotAllowed and TTSModerationUnavailable in Go).
  • Both codes are classified as TTS-owned so structured guardrail failures terminate the matching synthesis request instead of leaving it pending.

[0.17.2] - 2026-08-28

Added

  • TTS voice-list items can now include optional multilingual profile metadata in Python, JavaScript, and Go. A profile exposes its supported BCP-47 languages and shared speaker gender and dialect; physical voices remain the existing {id, label} shape.

Compatibility

  • Existing callers remain source-compatible because profile is optional. Invalid profile metadata is omitted without dropping the underlying voice.

[0.17.1] - 2026-08-26

Added

  • Socket.IO errors now preserve the platform's retry_after_seconds, data, reason, and retry_scope metadata in Python, JavaScript, and Go.
  • The SDK exports the current realtime and batch API error codes, including credit, concurrency, session-limit, stream-expiry, and TTS limit failures.

Fixed

  • Python Fast Transcription and TTS clients again accept the pre-0.17 positional order (api_url, api_path, api_key, ...). Keyword arguments remain recommended; legacy positional calls emit a deprecation warning.

[0.17.0] - 2026-08-09

Fixed

  • Realtime STT close() no longer loses the terminal transcript on long audio. All three clients (Python, JavaScript, Go) latched the session-final signal on the model's mid-utterance is_speech_final. On audio containing a natural pause followed by more speech, close() then treated the stream as already final, skipped the final-flag handshake, and the terminal consolidated transcript was silently lost while the server session was abandoned to disconnect teardown. The session-final latch is now gated on the protocol-level is_final (which the terminal response always carries), matching the diarization clients. Streams where the model endpointed early now pay one extra round-trip (~0.2 s measured) on close(); short conversational streams are unaffected.

Changed

  • Single Socket.IO path for every subsystem. All Socket.IO clients — Realtime STT, Fast Transcription STT, TTS, and Diarization — now default api_path to /socket.io, the one path the platform serves for all subsystems. api_path is now optional; pass it only to override for a self-hosted or proxied deployment. Constructing a client requires just api_url and api_key, and the missing-argument error is now "api_url and api_key are required". Mirrored across Python, JavaScript, and Go via a shared default (DEFAULT_API_PATH in Python/JS, DefaultAPIPath in Go). The per-service path concept (/fast-transcription/socket.io, /tts/socket.io) is removed from the public contract. This is a backward-compatible change: callers that still pass api_path continue to work unchanged.

Migration

  • Remove any hardcoded per-service api_path (e.g. /fast-transcription/socket.io or /tts/socket.io). The platform now serves every subsystem under /socket.io, which the SDK uses by default — callers pinning an old per-service path will fail to connect against the consolidated platform. Drop the api_path argument (recommended) or set it to /socket.io.
  • Endpoints that have not consolidated yet still require an explicit api_path. In particular, sautech.humain.com does not serve the unprefixed /socket.io route — callers targeting it must pass api_path="/realtime/socket.io". /realtime/socket.io also still routes on environments that keep the prefixed route, so callers pinning it are unaffected until that route is retired.

[0.16.1-beta.2] - 2026-06-18

Changed

  • Rebranded repository, package, and release documentation to HUMAIN Voice across the root, Python, JavaScript, and Go docs.
  • Python, JavaScript, and Go examples, comments, and release metadata now use HUMAIN Voice wording instead of the old product name.
  • The deprecated JavaScript compatibility package now emits HUMAIN_VOICE_COMPAT_PACKAGE_DEPRECATED and uses neutral compatibility wording in its warning message.
  • The legacy Python import path now emits HumainVoiceCompatibilityWarning with neutral compatibility wording.
  • Example package manifests now depend on the registry package names instead of local source paths that expose old package-directory names.
  • Archived live-diarization planning docs were condensed so the public docs no longer preserve obsolete package paths.

[0.16.1-beta.1] - 2026-06-18

Added

  • The Python SDK can now be imported as humain_voice, matching the humain-voice distribution name.
  • The deprecated JavaScript compatibility package now wraps @humain-voice/sdk.
  • PyPI and npm publish jobs now generate registry READMEs that append this root changelog, so package registry pages show release notes from the same source as the repository.
  • The Go module now includes a checked-in golang/CHANGELOG.md mirror so tagged Go source includes release notes for Go consumers and pkg.go.dev.

Changed

  • JavaScript examples now import @humain-voice/sdk.
  • Go dependencies were refreshed and the Go CI/container baseline moved to Go 1.25.
  • Go README and release notes no longer reference the non-existent pkg/fasttranscription compatibility wrapper.

Deprecated

  • The legacy Python import path remains available for compatibility, but now emits a deprecation warning. New code should import from humain_voice.
  • The legacy JavaScript compatibility package remains available, but now emits a deprecation warning. New code should import from @humain-voice/sdk.

[0.16.1] - 2026-06-15

Changed

  • We now recommend selecting the Arabic/English model with the unversioned BayanArEn constant instead of pinning to BayanArEnV1. The unversioned constant always maps to the current production model, so you automatically benefit from accuracy improvements without a code change. If you have a specific reason to stay on a fixed model version, the BayanArEnV1 and BayanArEnV2 constants remain available — nothing you ship today breaks.

[0.16.0] - 2026-06-11

⚠️ Breaking Changes

  • ASR and diarization model identifiers were renamed. The SDK constants used to select a model changed, so any code that selects a model must be updated before upgrading. Functionality is unchanged; these are the same models under new, brand-aligned names. Always select models through the SDK constants below rather than raw strings. Migration from 0.15.x:

    What you used (0.15.x) New constant
    ASRModel.Ar_1 ASRModel.NidaAr
    ASRModel.Ar_2 ASRModel.BayanAr
    ASRModel.Ar_8k_1 ASRModel.NidaArTelephony
    ASRModel.ArEn ASRModel.BayanArEn
    ASRModel.ArEn_1 ASRModel.BayanArEnV1
    ASRModel.ArEn_2 ASRModel.BayanArEnV2
    BatchDiarization.M1 BatchDiarization.D1
    BatchDiarization.M2 BatchDiarization.D2

    Go callers use the package-prefixed forms (e.g. ASRModelBayanArEnV1, BatchDiarizationD1). The old constants are no longer accepted — code using them will need to migrate to the new names.

  • The batch transcription client no longer retries failed requests automatically. Previous versions retried internally (via tenacity in Python and p-retry in JS). The client now makes exactly one HTTP call per operation and raises immediately on failure. The max_retries / maxRetries constructor option is kept for compatibility but is now a no-op; passing a non-zero value emits a deprecation warning. If you depend on retries, you must now implement your own policy — every raised error exposes retryable, retry_after, and capacity (for HTTP 429) so you can back off correctly.

  • Error handling moved to a structured, typed exception hierarchy. Errors are now routed by error code to the client that owns them, and failures raise a specific exception type instead of a generic error. For batch transcription: HTTP 401 raises an auth error, HTTP 429 raises a rate-limit error (carrying retry_after and capacity), and all other failures raise the base BatchTranscribeError. The full server payload is available on the exception (payload / raw_body) for inspection. If you currently catch a broad error type or parse error strings, switch to catching the typed exceptions and reading their attributes.

Added

  • Realtime speaker diarization over the streaming transport — receive per-speaker labels on transcripts as audio streams in.
  • SRT and VTT subtitle helpers in Python, JS, and Go to turn transcription results directly into ready-to-use subtitle files.

[0.15.1] - 2026-05-13

Added

  • Official Go SDK, at full feature parity with the Python and JavaScript packages: realtime speech-to-text, fast transcription, text-to-speech, and batch transcription, all over the same streaming transport. If you work in Go, you no longer need to call the platform API directly.

[0.15.0] - 2026-05-06

⚠️ Breaking Changes

  • Client imports, event names, and configuration shapes changed. Internally the STT and TTS clients were rebuilt on a shared connection layer, and that shifted parts of the public surface — some import paths, streaming event names, and configuration option shapes are different. Review your client setup and event handlers against the updated examples when upgrading from 0.14.x.
  • disconnect_socketio was removed. Connection teardown is now handled by the client itself; if you imported disconnect_socketio directly, drop the call — closing the client cleans up the connection for you.

Changed

  • STT and TTS clients now share a single connection and lifecycle, which makes connection handling more consistent and predictable across both. This is an internal change, but it is the reason for the surface adjustments noted above.

[0.14.5] - 2026-02-03

Added

  • Run multiple concurrent streams from a single RealtimeClient. You can now open several independent realtime sessions from one client instance instead of constructing a separate client per stream.

Changed

  • Invalid ASR and TTS request fields are now rejected up front. The SDK validates request fields — including voice-reference inputs for TTS — before sending, so mistakes surface immediately as a clear client-side error rather than failing partway through a request. Requests that previously appeared to start before failing server-side may now raise a validation error sooner; fix the flagged field and the request proceeds as normal.

Metadata

Release files for humain-voice 0.19.0b4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for humain-voice 0.19.0b4
File Size Uploaded Provenance Actions
humain_voice-0.19.0b4.tar.gz 99.4 kB Without provenance Details for humain_voice-0.19.0b4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for humain-voice 0.19.0b4
File Interpreter ABI Platform Actions
humain_voice-0.19.0b4-py3-none-any.whl Python 3 none any Details for humain_voice-0.19.0b4-py3-none-any.whl

Total release size: 225.6 kB

Release files / humain_voice-0.19.0b4.tar.gz

Download URL humain_voice-0.19.0b4.tar.gz
Size 99.4 kB
Tags Source
SHA-256 checksum
How to use checksums
411dd7b49e5fe5540cf254f563ec3e55734804ea4c0ec80cd92a8da1fb4c4628
BLAKE2b-256 checksum
How to use checksums
074f565a01872e4f18de119b115a7f993503327aa0adcd0426fd497517db3120
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.0

Release files / humain_voice-0.19.0b4-py3-none-any.whl

Download URL humain_voice-0.19.0b4-py3-none-any.whl
Size 126.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
48065fa1791dab9f8f26c29e8412b0dbdf9a6274e3b4f2d32c1a7c9506b73955
BLAKE2b-256 checksum
How to use checksums
b63d5d2b1325d009f513def6c9597cc8100f5521c586afd133343664b14b09c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.0

Security for humain-voice 0.19.0b4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page