feat(dictation): add the Dictation API with the live upload as its only connection

[ccampbell-aai]

Adds the Dictation API (dictation.assemblyai.com) to the SDK as assemblyai.dictation.v1, with top-level shortcuts under aai.*.

What's new

A dictation client for short spoken notes. Audio is uploaded as it is spoken over a single connection to POST /v1/transcribe/live, the service transcribes each speech segment as it lands, and the result comes back as one transcript with an optional LLM rewrite. There is no job id and no polling.

import assemblyai as aai

config = aai.DictationConfig(sample_rate=16000, channels=1, llm_instruction="Format as a SOAP note.")

with aai.DictationTranscriber() as transcriber:
    with transcriber.open_live(config) as session:
        start_capture(on_audio=session.write)   # any callback: sounddevice, WebRTC, telephony
        wait_until_done()
    print(session.result().final_text)

Clients

• DictationTranscriber(*, client=None, config=None, max_workers=None, api_key=None)
  • open_live(config=None) -> DictationLiveSession — push-style session for callback-driven audio. The request starts on a worker thread the moment the session opens. write() is thread-safe and never blocks; close() ends the audio; result() waits for the transcript; abort() drops the request. As a context manager it closes on a clean exit and aborts if the block raised.
  • transcribe_live(data, config=None) — pull-style. Takes an iterable of chunks, a binary file object read as it fills, raw bytes, or a local path. Complete audio is sent as a single chunk over the same connection.
  • warm() opens the connection ahead of time; close() shuts the worker pool; context manager; config property.
• AsyncDictationTranscriber(*, client=None, config=None, api_key=None) — the asyncio counterpart. transcribe_live() also accepts async iterables; open_live() -> AsyncDictationLiveSession runs the request as a task on the running loop, with write()/close() as plain functions and result()/abort() as coroutines. warm(), aclose(), async context manager.

Models

• DictationConfig — sample_rate, channels (both required only for raw PCM; WAV carries them in its header), language_codes, keyterms_prompt (≤2048 chars total), llm_instruction (≤2048 chars). Unknown fields are rejected.
• DictationResponse — text, words (DictationWord: text, confidence), confidence, llm_response, llm_error, audio_duration_ms, session_id, request_time_ms, sync_time_ms, plus final_text, which returns the LLM rewrite when there is one and the raw transcript otherwise. Unknown response fields are ignored.
• DictationError — status_code, error_code (snake_cased problem-details title, e.g. audio_too_large), retry_after on 429/503. Raised for any non-200, including rejections the server sends while the upload is still in flight.
• AudioSource / AsyncAudioSource — the accepted input types.

Wire behaviour

• multipart/form-data with chunked transfer encoding, the config part always ahead of the audio part (an empty object when nothing is set).
• Content-Type chosen from the extension or the PCM fields: audio/pcm for .pcm/.raw or when sample_rate/channels are set, audio/wav by default, and the true container type for other known extensions.
• Auth is the raw API key. No X-AAI-Model header; the service picks the model. URLs are not accepted.

Settings

• dictation_base_url (default https://dictation.assemblyai.com, overridable via ASSEMBLYAI_DICTATION_BASE_URL).
• dictation_http_timeout (default 300 s, per socket operation like every httpx timeout).

Shared helpers

• assemblyai/_multipart.py — the streaming multipart encoder and chunk iterators, used by both the dictation and sync live clients.
• assemblyai/_audio.py — shared audio-input reading, format resolution and config serialization for the single-request products.

Docs

• README: two rows in "Choosing a transcriber", a "Dictation Examples" section (microphone via open_live(), iterator/file/bytes/path via transcribe_live(), LLM rewrite, config, warm(), asyncio, errors), and the dictation settings in the defaults block.
• CLAUDE.md class list updated.

Validation

• Unit tests for both clients, the sessions, the multipart framing and the shared helpers; the suite passes on Python 3.9–3.12 and on the httpx 0.22/0.24 and pydantic 1.10 floors. Ruff and mypy clean.
• Verified against prod: transcribe_live(path), a threaded open_live() session paced at real time, and an asyncio session all return the expected transcript with llm_response populated.

Version bumps to 1.5.0. Draft until the Dictation API is public.

🤖 Generated with Claude Code