Add live transcription WebSocket client with microphone support

[arnavmehta7]

Summary

Adds camb.live_transcription — a typed, async WebSocket client wrapping the /apis/transcription/listen endpoint. End-to-end verified against the dev backend.

What ships

from camb.client import CambAI
from camb.live_transcription import Microphone, ServerMessageType

client = CambAI(api_key=...)
session = await client.live_transcription.connect(
    model="boli-v5",
    language="en-us",
    sample_rate=16000,
)

@session.on(ServerMessageType.RESULTS)
def _(msg):
    print(msg.transcript)   # cumulative interim — replace, don't concat

async with session:
    await session.stream_audio(Microphone(sample_rate=16000, chunk_size=1600))

• Typed events — Ready, Results, Final (reserved), Error, Closed. All defined via a single ServerMessageType enum + Pydantic models + PARSER_REGISTRY. Adding a new event = three edits in one file.
• Microphone helper — sounddevice-based capture, now a regular dependency.
• File source — FileAudioSource paces a WAV at real-time for tests / CI.
• Wildcard handler — session.on_any catches event types the SDK hasn't been updated for yet, so apps stay forward-compatible.
• Custom transport — pluggable Transport protocol so tests can inject mocks; default uses websockets.
• Error hierarchy — LiveTranscriptionError + …ConnectError / …ProtocolError subclasses.

Bugs found and fixed during integration testing

1. WebSocket race — server's Ready was being dropped when the handshake completed before the read loop attached.
2. waitUntilReady hang on auth failure — close before Ready left awaiters hanging; now wakes the event.
3. Double-open via async with — connect() already opens the session, so async with session: re-ran _open(), spawning a second reader task. Symptom: every event fired twice and the session wedged after a few frames. _open() is now idempotent.

Files

camb/live_transcription/
├── __init__.py          # public exports
├── client.py            # LiveTranscriptionClient (camb.live_transcription)
├── session.py           # LiveTranscriptionSession + module-level connect()
├── transport.py         # Transport protocol + WebsocketsTransport
├── events.py            # ServerMessageType + Pydantic models + PARSER_REGISTRY
├── options.py           # Encoding + ConnectOptions
├── audio_source.py      # AudioSource protocol + FileAudioSource
├── microphone.py        # Microphone (sounddevice)
└── errors.py            # LiveTranscriptionError hierarchy

examples/
├── live_transcription_microphone.py   # mic → session
└── live_transcription_file.py         # WAV → session at real-time pace

Test plan

• Smoke test of imports + model parsing in py3125 conda env.
• End-to-end: stream WAV → dev endpoint → received Ready + 9 cumulative Results + clean Closed(1000). Final transcript: " Welcome to our service. We're glad to have".
• Negative path: invalid key → Closed(1008, "Invalid/Expired API Key") surfaced cleanly, no hang.
• Post-fix verification: Ready fires exactly once, no late wedge under async with.
• Reviewer: run examples/live_transcription_file.py public_docs/audio/demo-accent-en-us.wav against staging once the route is healthy.

Related

• Docs PR: Camb-ai/public_docs#117
• Companion TS SDK PR: Camb-ai/cambai-typescript-sdk (filed in this same batch)

🤖 Generated with Claude Code