Skip to content

feat(diarization): add client.diarization for the Diarization API - #227

Draft
mez171 wants to merge 1 commit into
mainfrom
mez/diarization-api
Draft

mez171 wants to merge 1 commit into
mainfrom
mez/diarization-api

Conversation

@mez171

@mez171 mez171 commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Adds client.diarization for the standalone Diarization API (POST /v1/diarize), which labels the speakers in an audio file.

What's added

  • client.diarization.diarize({ audio, transcript?, config?, contentType? }, { timeout?, signal? }) returns a DiarizationResponse. The layout follows the Dictation (feat(dictation): add client.dictation for the Dictation API #179) and TTS (feat(tts): Text-to-Speech HTTP client and WebSocket session #200) services.
  • Two ways to call it:
    • With a transcript: pass a SyncTranscriptResponse from client.sync.transcribe(..., { timestamps: true }). Only words is sent. Each word comes back with a speaker and the words are grouped into utterances.
    • Audio only: omit transcript to get speaker turns (segments) and speakers. Diarization can then run in parallel with transcription.
  • diarizationBaseUrl client option. It defaults to https://diarization.assemblyai.com; use https://diarization.us.assemblyai.com or https://diarization.eu.assemblyai.com to keep requests in that data zone.
  • DiarizationError (status, errorCode, retryAfter) is built by the existing problem+json mapper.
  • Audio: a path, data URL, Uint8Array/ArrayBuffer, Blob/File, a web stream or a Node stream; URLs are rejected. Content type comes from the extension, audio/pcm when sample_rate/channels are set, and contentType overrides it. PCM without both fields throws before sending. The body is buffered so Content-Length is set; the API returns 411 without it.
  • Docs and release: a README section, CLAUDE.md, and a CHANGELOG entry. Version 4.43.4 → 4.44.0, a minor bump for a new product, like TTS.

Testing

  • jest tests/unit/diarization.test.ts: 14 passed. They cover:
    • both modes and an explicit empty words;
    • a sync response passed straight through;
    • the PCM config, a missing PCM field, and PCM forced by override;
    • extension inference and the override, and a stream named from .path;
    • URL rejection;
    • 401, 400 and 503 (Retry-After) mapping;
    • a custom and the default base URL.
  • pnpm build and pnpm lint (eslint, tsc, prettier, publint) are clean.
  • pnpm test:unit: 594 passed, 3 failed. The 3 failures are pre-existing user-agent tests in tests/unit/utils.test.ts. They break on Node 22, where navigator.userAgent exists; CI runs Node 18 and 20, and this PR doesn't touch that code.
  • None of the tests call the real API.

Notes for review

  • Default host: diarization.assemblyai.com. TTS defaults to tts.us, so say if you'd rather default to the US host.
  • No default timeout: sync defaults to 180 s and dictation to 300 s. Happy to add one.
  • Blob content type: a Blob's own type isn't used for inference; the extension or contentType decides. No new sample was added.

The API itself is live in us-west-2 and eu-west-1. Docs: AssemblyAI/assemblyai-docs#584 (in review; its samples will use this client).

🤖 Generated with Claude Code

client.diarization.diarize({ audio, transcript?, config?, contentType? })
posts multipart audio, an optional transcript with word timings (a sync
transcription response passes straight through) and config to
/v1/diarize. Without a transcript only segments and speakers come back.
Problem+json failures throw DiarizationError. New client option
diarizationBaseUrl (default https://diarization.assemblyai.com; US/EU
data-zone hosts documented). Bump to 4.44.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mez171
mez171 requested a review from ccampbell-aai November 19, 2026 17:50

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant