diff --git a/CLAUDE.md b/CLAUDE.md index f739d6f..e4656dc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -59,6 +59,11 @@ aai.settings.api_key = "your-key" - `aai.TTSConfig` — Text-to-Speech options: `voice_id` (a library voice such as `aai-jane`, or a cloned voice by UUID or slug), `model_id` (`assemblyai-tts-1`), `language`, `sample_rate`, `encoding` (`aai.TTSEncoding`: `pcm_s16le` default | `pcm_mulaw` | `pcm_alaw` | `mp3`), `container` (`aai.TTSContainer`: `raw` default | `wav`), `bit_rate`, `extend_biometric_consent` (owner-only consent renewal of a cloned voice). Rejects unknown fields - `aai.TTSResponse` — Text-to-Speech result: `.audio` (bytes) plus the response headers: `.request_id`, `.region`, `.model`, `.voice_id`, `.language`, `.encoding`, `.sample_rate`, `.container`, `.bit_rate`, `.content_type`, `.voice_expires_at`, `.billed_characters`, `.audio_duration_ms`. `TTSStream.info` carries the same fields without `audio`; `audio_duration_ms` is `None` on a stream with audio (`0` when the text had nothing to speak) - `aai.TTSError` — Raised on any Text-to-Speech refusal: `.status_code`, `.error_code` (stable API code; `biometric_terms_not_accepted` 403 until the account accepts the biometric data terms in the dashboard, `auth_unavailable` 503 retryable; on a session these arrive as close 3006 and 1011, with `status_code` None, the close code in `.body["close_code"]` and `.retryable` from the API's Error frame), `.param`, `.request_id`, `.retryable`, `.retry_after`, `.errors`, `.body` (the whole envelope) +- `aai.Diarizer` — Diarization API: speaker labels for one audio file per request. `diarize(audio, transcript=None, config=None, *, content_type=None)`: `audio` is a path, bytes or binary file object; `transcript` is a `SyncTranscriptResponse` (request it with `timestamps=True`), a dict with `words`, or a list of words (`text`, `start`/`end` ms, optional `confidence`). Omit `transcript` for segments-only mode (`words`/`utterances` empty). Content-Type from the extension (`audio/wav` default, `audio/pcm` when `sample_rate`/`channels` set, `audio/mpeg`, `audio/flac`, `audio/ogg`, `audio/mp4`, `audio/webm`) unless `content_type=` is given. Host from `aai.settings.diarization_base_url` (`https://diarization.assemblyai.com`; `https://diarization.us.assemblyai.com` / `https://diarization.eu.assemblyai.com` for data residency) +- `aai.AsyncDiarizer` — Asyncio counterpart of `Diarizer`; `diarize()` is a coroutine. Owns an HTTP pool: use `async with` or `await aclose()` +- `aai.DiarizationConfig` — Diarization options: `sample_rate`, `channels` (raw PCM only), `language_code` (default `en`). Rejects unknown fields +- `aai.DiarizationResponse` — Diarization result: `.words` (`DiarizedWord`: `text`, `start`, `end`, `confidence`, `speaker`, `speaker_confidence`), `.utterances` (`DiarizationUtterance`: `speaker`, `text`, `start`, `end`, `confidence`, `speaker_confidence`, `words`), `.segments` (`DiarizationSegment`: `start`, `end`, `speaker`, `speaker_confidence`), `.speakers`, `.audio_duration_ms`, `.session_id`, `.request_time_ms` +- `aai.DiarizationError` — Raised on any Diarization API refusal: `.status_code` (401 bad key, 400 validation, 411/413/415, 5xx), `.error_code` (snake_cased problem title, e.g. `unauthorized`, `bad_request`), `.retry_after` - `assemblyai.streaming.v3.RealTimeTranscriber` — Real-time streaming with event-based API (threaded) - `assemblyai.streaming.v3.AsyncRealTimeTranscriber` — Asyncio-native counterpart; same options/events - `aai.LLMGateway` — LLM Gateway client. Resources: `models.list()`, `chat.completions.create()` (incl. `stream=True`), `understanding.create()`/`.validate()`, `decisions.create()` diff --git a/README.md b/README.md index 105d5c5..04d55b2 100644 --- a/README.md +++ b/README.md @@ -1098,6 +1098,81 @@ print(response.voice_expires_at) # Unix seconds +### **Diarization Examples** + +`aai.Diarizer` labels the speakers in an audio file with one request to the Diarization API (`POST /v1/diarize`). Pass the audio with its transcript to get each word's speaker and the utterances; leave the transcript out to get only the speaker turns, so diarization can run alongside transcription instead of after it. Speakers are labelled `A`, `B`, and so on, up to 8. + +The audio is a local path, bytes or a binary file object (not a URL). Its Content-Type, which picks the decoder, comes from the file extension: `audio/wav`, `audio/mpeg`, `audio/flac`, `audio/ogg`, `audio/mp4`, `audio/webm`, or `audio/pcm` for `.pcm`/`.raw` and whenever `sample_rate`/`channels` are set on the `DiarizationConfig`. Audio with no known extension is sent as WAV; pass `content_type=` to set it yourself. `DiarizationConfig` takes `sample_rate` and `channels` (raw PCM only) and `language_code` (default `en`), and rejects unknown fields. + +Requests go to `aai.settings.diarization_base_url`, `https://diarization.assemblyai.com` by default; set it to `https://diarization.us.assemblyai.com` or `https://diarization.eu.assemblyai.com` to keep them in the US or EU data zone. + +
+ Label the words of a sync transcript + +```python +import assemblyai as aai + +aai.settings.api_key = "" + +# Word timestamps are needed to place each word: request them. +transcript = aai.SyncTranscriber().transcribe( + "./call.wav", config=aai.SyncTranscriptionConfig(timestamps=True) +) + +result = aai.Diarizer().diarize("./call.wav", transcript=transcript) + +for utterance in result.utterances: + print(f"Speaker {utterance.speaker}: {utterance.text}") + +for word in result.words: + print(word.text, word.start, word.end, word.speaker, word.speaker_confidence) +``` + +`transcript` also takes a dict with a `words` list, or the list of words alone, each with `text`, `start` and `end` in milliseconds and an optional `confidence`; other fields are ignored. A word without timings gets them from the words next to it. An empty list returns empty results. + +
+ +
+ Speaker turns only (no transcript) + +```python +result = aai.Diarizer().diarize( + pcm_bytes, + config=aai.DiarizationConfig(sample_rate=16000, channels=1), +) + +print(result.speakers) # ["A", "B"] +for segment in result.segments: + print(segment.speaker, segment.start, segment.end, segment.speaker_confidence) +``` + +Without a transcript, `words` and `utterances` are empty and `segments` and `speakers` are filled. + +
+ +
+ Asyncio and errors + +```python +import asyncio +import assemblyai as aai + +async def main(): + async with aai.AsyncDiarizer() as diarizer: + try: + result = await diarizer.diarize("./call.mp3") + except aai.DiarizationError as error: + print(error.status_code, error.error_code, error) + return + print(result.speakers, result.audio_duration_ms) + +asyncio.run(main()) +``` + +`aai.AsyncDiarizer` owns an HTTP pool: use `async with` or `await aclose()`, or pass an `aai.AsyncClient` to share one. Refusals raise `aai.DiarizationError` with the HTTP `status_code`, the snake_cased problem `title` as `error_code` (`unauthorized` for a missing or invalid key, `bad_request` for an unknown config field or a transcript without `words`, `audio_too_large`, `unsupported_media_type`, `capacity_exceeded`, `inference_timeout`), and `retry_after` when the API sends `Retry-After`. Requests wait up to `aai.settings.diarization_http_timeout` (330 s by default). + +
+ ### **Asyncio Examples** `aai.AsyncTranscriber` is the asyncio counterpart of `aai.Transcriber`. Every method @@ -2224,6 +2299,7 @@ All custom SDK exceptions inherit from `aai.AssemblyAIError`, except the streami | `aai.TranscriptError` | Raised when a prerecorded transcript API call fails at the HTTP level or polling times out. | `status_code: Optional[int]` | | `aai.SyncTranscriptError` | Raised when synchronous transcription fails (`aai.SyncTranscriber`). | `status_code: Optional[int]`, `error_code: Optional[str]`, `retry_after: Optional[int]` | | `aai.TTSError` | Raised when a Text-to-Speech request fails (`aai.TextToSpeech`) or a session is refused or fails (`aai.TTSSession`, where `status_code` is `None`, `request_id` is the session id and `body["close_code"]` is the WebSocket close code). | `status_code: Optional[int]`, `error_code: Optional[str]`, `param: Optional[str]`, `request_id: Optional[str]`, `retryable: Optional[bool]`, `retry_after: Optional[int]`, `errors: Optional[List[Dict[str, Optional[str]]]]`, `body: Optional[dict]` | +| `aai.DiarizationError` | Raised when a Diarization API request fails (`aai.Diarizer`, `aai.AsyncDiarizer`). | `status_code: Optional[int]`, `error_code: Optional[str]`, `retry_after: Optional[int]` | | `assemblyai.types.RedactedAudioIncompleteError` | Raised when requesting redacted audio before processing completes. | `status_code: Optional[int]` | | `assemblyai.types.RedactedAudioExpiredError` | Raised when requesting redacted audio that has expired and is no longer available. | `status_code: Optional[int]` | | `assemblyai.types.RedactedAudioUnavailableError` | Raised when requesting redacted audio that is unavailable at the given URL. | `status_code: Optional[int]` | diff --git a/assemblyai/__init__.py b/assemblyai/__init__.py index d36a862..b536e06 100644 --- a/assemblyai/__init__.py +++ b/assemblyai/__init__.py @@ -1,6 +1,16 @@ from .__version__ import __version__ from .async_client import AsyncClient from .client import Client +from .diarization.v1 import ( + AsyncDiarizer, + DiarizationConfig, + DiarizationError, + DiarizationResponse, + DiarizationSegment, + DiarizationUtterance, + DiarizedWord, + Diarizer, +) from .dictation.v1 import ( AsyncDictationTranscriber, DictationConfig, @@ -156,6 +166,7 @@ def __getattr__(name: str): "ActionItemsResponse", "AssemblyAIError", "AsyncClient", + "AsyncDiarizer", "AsyncDictationTranscriber", "AsyncLLMGateway", "AsyncSyncTranscriber", @@ -174,6 +185,13 @@ def __getattr__(name: str): "ContentSafetySeverityScore", "CustomFormattingRequest", "CustomFormattingResponse", + "DiarizationConfig", + "DiarizationError", + "DiarizationResponse", + "DiarizationSegment", + "DiarizationUtterance", + "DiarizedWord", + "Diarizer", "DictationConfig", "DictationError", "DictationResponse", diff --git a/assemblyai/__version__.py b/assemblyai/__version__.py index d6a282f..f84c53b 100644 --- a/assemblyai/__version__.py +++ b/assemblyai/__version__.py @@ -1 +1 @@ -__version__ = "1.10.12" +__version__ = "1.11.0" diff --git a/assemblyai/diarization/__init__.py b/assemblyai/diarization/__init__.py new file mode 100644 index 0000000..36fbee0 --- /dev/null +++ b/assemblyai/diarization/__init__.py @@ -0,0 +1,31 @@ +"""The Diarization API: audio (and optionally its transcript) in, speaker labels out. + +The implementation lives in ``diarization/v1/``, mirroring the ``tts/v1/`` and +``dictation/v1/`` layout. This ``__init__`` re-exports the public surface so +``from assemblyai.diarization import Diarizer`` works alongside the versioned +path. +""" + +from .v1 import ( + AsyncDiarizer, + DiarizationConfig, + DiarizationError, + DiarizationResponse, + DiarizationSegment, + DiarizationUtterance, + DiarizedWord, + Diarizer, + TranscriptInput, +) + +__all__ = [ + "AsyncDiarizer", + "DiarizationConfig", + "DiarizationError", + "DiarizationResponse", + "DiarizationSegment", + "DiarizationUtterance", + "DiarizedWord", + "Diarizer", + "TranscriptInput", +] diff --git a/assemblyai/diarization/v1/__init__.py b/assemblyai/diarization/v1/__init__.py new file mode 100644 index 0000000..91d9dcd --- /dev/null +++ b/assemblyai/diarization/v1/__init__.py @@ -0,0 +1,23 @@ +from ._base import TranscriptInput +from .async_client import AsyncDiarizer +from .client import Diarizer +from .models import ( + DiarizationConfig, + DiarizationError, + DiarizationResponse, + DiarizationSegment, + DiarizationUtterance, + DiarizedWord, +) + +__all__ = [ + "AsyncDiarizer", + "DiarizationConfig", + "DiarizationError", + "DiarizationResponse", + "DiarizationSegment", + "DiarizationUtterance", + "DiarizedWord", + "Diarizer", + "TranscriptInput", +] diff --git a/assemblyai/diarization/v1/_base.py b/assemblyai/diarization/v1/_base.py new file mode 100644 index 0000000..df75cf7 --- /dev/null +++ b/assemblyai/diarization/v1/_base.py @@ -0,0 +1,91 @@ +from __future__ import annotations + +from typing import Any, Dict, Mapping, Optional, Sequence, Tuple, Union + +from ... import _audio, types +from ..._audio import AudioInput +from ...dictation.v1._base import _CONTENT_TYPES +from .models import DiarizationConfig + +__all__ = [ + "AudioInput", + "TranscriptInput", + "check_config", + "resolve_request", +] + +# A transcript to label: the sync API's response (request it with +# `timestamps=True`), a dict with a `words` list, or the list of words alone. +# Each word is a `SyncWord` or a dict with `text`, `start` and `end` in +# milliseconds and an optional `confidence`; other fields are ignored. +TranscriptInput = Union[ + types.SyncTranscriptResponse, + Mapping[str, Any], + Sequence[Union[types.SyncWord, Mapping[str, Any]]], +] + + +def check_config(owner: str, config: Optional[DiarizationConfig]) -> None: + """Raises unless `config` is a `DiarizationConfig` or `None`.""" + + _audio.check_config(owner, config, DiarizationConfig) + + +def _dump(model: Any) -> Any: + if hasattr(model, "model_dump"): + return model.model_dump(exclude_none=True) + if hasattr(model, "dict"): + return model.dict(exclude_none=True) + return model + + +def _transcript_json(transcript: Optional[TranscriptInput]) -> Optional[Dict[str, Any]]: + """The JSON `transcript` part, or `None` to leave the part out.""" + + if transcript is None: + return None + if isinstance(transcript, Mapping): + return dict(transcript) + words: Any = getattr(transcript, "words", transcript) + if isinstance(words, (str, bytes, bytearray)) or not isinstance(words, Sequence): + raise TypeError( + "transcript must be a SyncTranscriptResponse, a dict with `words`, " + f"or a list of words, not {type(transcript).__name__}" + ) + return {"words": [_dump(w) for w in words]} + + +def resolve_request( + owner: str, + audio: AudioInput, + transcript: Optional[TranscriptInput], + config: Optional[DiarizationConfig], + content_type: Optional[str], +) -> Tuple[bytes, str, str, Optional[dict], Optional[dict]]: + """ + Reads the audio and builds the parts of a diarize request. + + The audio's Content-Type comes from `content_type` when given, else from + the file extension (`.mp3` -> `audio/mpeg`, ...), else `audio/pcm` when + `sample_rate`/`channels` are set, else `audio/wav`. + + Returns: `(audio_bytes, filename, content_type, transcript_json, config_json)`. + """ + + check_config(owner, config) + config = config or DiarizationConfig() + data, filename, inferred = _audio._resolve_audio( + audio, + sample_rate=config.sample_rate, + channels=config.channels, + owner=owner, + config_name="DiarizationConfig", + content_types=_CONTENT_TYPES, + ) + return ( + data, + filename, + content_type or inferred, + _transcript_json(transcript), + _audio._config_to_json(config), + ) diff --git a/assemblyai/diarization/v1/api.py b/assemblyai/diarization/v1/api.py new file mode 100644 index 0000000..8a7bc64 --- /dev/null +++ b/assemblyai/diarization/v1/api.py @@ -0,0 +1,98 @@ +import json +from typing import Any, List, Optional, Tuple + +import httpx + +from ... import types +from ...sync.v1.api import _error_from_response as _shared_error_from_response +from .models import DiarizationError, DiarizationResponse + +ENDPOINT_DIARIZE = "/v1/diarize" + + +def _error_from_response(response: httpx.Response) -> types.AssemblyAIError: + """ + Builds a `DiarizationError` from a non-200 response. + + The Diarization API answers with the same RFC 9457 problem-details body + (`{"status", "title", "detail"}`) as the sync API, so the parsing is + shared and only the exception class differs. + """ + + return _shared_error_from_response(response, DiarizationError, "diarization") + + +def _files( + *, + audio: bytes, + filename: str, + audio_content_type: str, + transcript: Optional[dict], + config: Optional[dict], +) -> List[Tuple[str, Tuple[Optional[str], Any, str]]]: + """ + The multipart parts of a diarize request. + + Buffered, so httpx sends `Content-Length`, which the API requires (411). + An absent `transcript` leaves its part out: segments-only mode. + """ + + files: List[Tuple[str, Tuple[Optional[str], Any, str]]] = [] + if config is not None: + files.append( + ("config", (None, json.dumps(config).encode(), "application/json")) + ) + if transcript is not None: + files.append( + ("transcript", (None, json.dumps(transcript).encode(), "application/json")) + ) + files.append(("audio", (filename, audio, audio_content_type))) + return files + + +def _parse(response: httpx.Response) -> DiarizationResponse: + if response.status_code != httpx.codes.OK: + raise _error_from_response(response) + + return DiarizationResponse.parse_obj(response.json()) + + +def diarize( + client: httpx.Client, + *, + base_url: str, + audio: bytes, + filename: str, + audio_content_type: str, + transcript: Optional[dict], + config: Optional[dict], + timeout: float, +) -> DiarizationResponse: + """ + Posts a diarize request. + + Args: + client: the HTTP client (carries the `Authorization` header). + base_url: the Diarization API base URL, e.g. `https://diarization.assemblyai.com`. + audio: the audio bytes. + filename: name for the audio multipart part. + audio_content_type: the audio part's Content-Type; selects the decoder. + transcript: the JSON `transcript` part, or None to leave it out. + config: the JSON `config` part, or None to leave it out. + timeout: the httpx timeout in seconds. + + Raises: `DiarizationError` on any non-200 response. + """ + + response = client.post( + base_url.rstrip("/") + ENDPOINT_DIARIZE, + files=_files( + audio=audio, + filename=filename, + audio_content_type=audio_content_type, + transcript=transcript, + config=config, + ), + timeout=timeout, + ) + return _parse(response) diff --git a/assemblyai/diarization/v1/async_api.py b/assemblyai/diarization/v1/async_api.py new file mode 100644 index 0000000..7e00fe5 --- /dev/null +++ b/assemblyai/diarization/v1/async_api.py @@ -0,0 +1,37 @@ +"""The asyncio counterpart of `api.py`: same endpoint, parts and errors.""" + +from typing import Optional + +import httpx + +from .api import ENDPOINT_DIARIZE, _files, _parse +from .models import DiarizationResponse + +__all__ = ["diarize"] + + +async def diarize( + client: httpx.AsyncClient, + *, + base_url: str, + audio: bytes, + filename: str, + audio_content_type: str, + transcript: Optional[dict], + config: Optional[dict], + timeout: float, +) -> DiarizationResponse: + """Posts a diarize request. The asyncio counterpart of `api.diarize`.""" + + response = await client.post( + base_url.rstrip("/") + ENDPOINT_DIARIZE, + files=_files( + audio=audio, + filename=filename, + audio_content_type=audio_content_type, + transcript=transcript, + config=config, + ), + timeout=timeout, + ) + return _parse(response) diff --git a/assemblyai/diarization/v1/async_client.py b/assemblyai/diarization/v1/async_client.py new file mode 100644 index 0000000..4d6380c --- /dev/null +++ b/assemblyai/diarization/v1/async_client.py @@ -0,0 +1,139 @@ +import asyncio +import functools +from typing import Optional + +from ... import async_client as _async_client +from . import async_api +from ._base import AudioInput, TranscriptInput, check_config, resolve_request +from .models import DiarizationConfig, DiarizationResponse + +__all__ = ["AsyncDiarizer"] + + +class AsyncDiarizer: + """ + Speaker labels for audio, for asyncio: the counterpart of `Diarizer`. + + Same options, result and errors; `diarize()` is a coroutine, and a path + or file object is read on a worker thread. Owns an HTTP pool: use + `async with` or `await aclose()`, or pass an `aai.AsyncClient` to share + one. + + Example: + ```python + import asyncio + import assemblyai as aai + + aai.settings.api_key = "your-key" + + async def main(): + async with aai.AsyncDiarizer() as diarizer: + result = await diarizer.diarize("call.wav") + for segment in result.segments: + print(segment.speaker, segment.start, segment.end) + + asyncio.run(main()) + ``` + """ + + def __init__( + self, + *, + client: Optional[_async_client.AsyncClient] = None, + config: Optional[DiarizationConfig] = None, + api_key: Optional[str] = None, + ) -> None: + """ + Creates an `AsyncDiarizer`. + + Args: + client: The `AsyncClient` to use. If `None`, one is created from + the global `settings` and closed on `aclose()`. Pass a client + to share one pool between instances. + config: Default options. A per-call `config` replaces it whole. + api_key: The API key to authenticate with. Builds and owns an + `AsyncClient` from it. Given alongside `client`, it takes + precedence and the given client is left untouched. + + Raises: + TypeError: if `config` is not a `DiarizationConfig`. + """ + check_config(type(self).__name__, config) + + self._owns_client = client is None or api_key is not None + self._client = _async_client._resolve_client(client, api_key) + self.config = config or DiarizationConfig() + + @property + def config(self) -> DiarizationConfig: + """The default configuration of the `AsyncDiarizer`.""" + return self._config + + @config.setter + def config(self, config: DiarizationConfig) -> None: + check_config(type(self).__name__, config) + + self._config = config or DiarizationConfig() + + @property + def client(self) -> _async_client.AsyncClient: + """The `AsyncClient` this instance sends requests with.""" + + return self._client + + async def diarize( + self, + audio: AudioInput, + transcript: Optional[TranscriptInput] = None, + config: Optional[DiarizationConfig] = None, + *, + content_type: Optional[str] = None, + ) -> DiarizationResponse: + """ + Labels the speakers in `audio`. + + The asyncio counterpart of `Diarizer.diarize`; same arguments. + + Raises: + DiarizationError: on any API refusal. + """ + ( + data, + filename, + audio_content_type, + transcript_json, + config_json, + ) = await asyncio.get_running_loop().run_in_executor( + None, + functools.partial( + resolve_request, + type(self).__name__, + audio, + transcript, + config or self._config, + content_type, + ), + ) + + return await async_api.diarize( + self._client.http_client, + base_url=self._client.settings.diarization_base_url, + audio=data, + filename=filename, + audio_content_type=audio_content_type, + transcript=transcript_json, + config=config_json, + timeout=self._client.settings.diarization_http_timeout, + ) + + async def aclose(self) -> None: + """Closes the HTTP pool this instance owns. A shared `client` is left open.""" + + if self._owns_client: + await self._client.aclose() + + async def __aenter__(self) -> "AsyncDiarizer": + return self + + async def __aexit__(self, *exc: object) -> None: + await self.aclose() diff --git a/assemblyai/diarization/v1/client.py b/assemblyai/diarization/v1/client.py new file mode 100644 index 0000000..bbbb437 --- /dev/null +++ b/assemblyai/diarization/v1/client.py @@ -0,0 +1,157 @@ +from typing import Optional + +from ... import client as _client +from . import api +from ._base import AudioInput, TranscriptInput, check_config, resolve_request +from .models import DiarizationConfig, DiarizationResponse + +__all__ = ["Diarizer"] + + +class Diarizer: + """ + Speaker labels for audio: the Diarization API, one file per request. + + Pass the audio with a transcript, such as a `SyncTranscriber` result + requested with `timestamps=True`, to get each word's speaker and the + utterances. Leave the transcript out to get only the speaker turns + (`segments`) and `speakers`, so diarization can run alongside + transcription instead of after it. + + Requests go to `settings.diarization_base_url`, + `https://diarization.assemblyai.com` by default; set + `https://diarization.us.assemblyai.com` or + `https://diarization.eu.assemblyai.com` to keep them in the US or EU. + + Example: + ```python + import assemblyai as aai + + aai.settings.api_key = "your-key" + + transcript = aai.SyncTranscriber().transcribe( + "call.wav", config=aai.SyncTranscriptionConfig(timestamps=True) + ) + result = aai.Diarizer().diarize("call.wav", transcript=transcript) + for utterance in result.utterances: + print(f"{utterance.speaker}: {utterance.text}") + ``` + """ + + def __init__( + self, + *, + client: Optional[_client.Client] = None, + config: Optional[DiarizationConfig] = None, + api_key: Optional[str] = None, + ) -> None: + """ + Creates a `Diarizer`. + + Args: + client: The HTTP client to use. Defaults to the shared default + client. A client you pass stays yours to close. + config: Default options. A per-call `config` replaces it whole. + api_key: The API key to authenticate with. Builds a `Client` for + this instance. Given alongside `client`, it takes precedence: + a client is built from a copy of that client's settings with + the key replaced, and the given client is left untouched. + + Raises: + TypeError: if `config` is not a `DiarizationConfig`. + """ + check_config(type(self).__name__, config) + + # Only a client built from `api_key` is owned; `client=None` is the + # shared default client, which stays open. + self._owns_client = api_key is not None + self._client = _client._resolve_client(client, api_key) + self.config = config or DiarizationConfig() + + @property + def config(self) -> DiarizationConfig: + """The default configuration of the `Diarizer`.""" + return self._config + + @config.setter + def config(self, config: DiarizationConfig) -> None: + check_config(type(self).__name__, config) + + self._config = config or DiarizationConfig() + + @property + def client(self) -> _client.Client: + """The `Client` this instance sends requests with.""" + + return self._client + + def diarize( + self, + audio: AudioInput, + transcript: Optional[TranscriptInput] = None, + config: Optional[DiarizationConfig] = None, + *, + content_type: Optional[str] = None, + ) -> DiarizationResponse: + """ + Labels the speakers in `audio`. + + Args: + audio: a local file path, raw bytes, or a binary file object. Not + a URL. + transcript: the words to label: a `SyncTranscriptResponse` + (requested with `timestamps=True`), a dict with a `words` + list, or a list of words, each with `text`, `start` and + `end` in milliseconds. `None` runs segments-only mode: + `words` and `utterances` come back empty. + config: Options for this request. Replaces (does not merge with) + the instance's default `config`. + content_type: the audio's Content-Type, which selects the + decoder. Inferred from the file extension when absent: + `audio/wav`, `audio/pcm` (`.pcm`/`.raw`, or whenever + `sample_rate`/`channels` are set), `audio/mpeg`, + `audio/flac`, `audio/ogg`, `audio/mp4`, `audio/webm`; WAV + when there is no known extension. + + Returns: a `DiarizationResponse`. + + Raises: + DiarizationError: on any API refusal. + ValueError: for a URL, or raw PCM missing `sample_rate` or `channels`. + TypeError: for an unsupported audio or transcript type. + """ + data, filename, audio_content_type, transcript_json, config_json = ( + resolve_request( + type(self).__name__, + audio, + transcript, + config or self._config, + content_type, + ) + ) + + return api.diarize( + self._client.http_client, + base_url=self._client.settings.diarization_base_url, + audio=data, + filename=filename, + audio_content_type=audio_content_type, + transcript=transcript_json, + config=config_json, + timeout=self._client.settings.diarization_http_timeout, + ) + + def close(self) -> None: + """ + Closes the HTTP pool this instance owns. A `client` you passed is + left open. + """ + + if self._owns_client: + self._client.close() + + def __enter__(self) -> "Diarizer": + return self + + def __exit__(self, *exc: object) -> None: + self.close() diff --git a/assemblyai/diarization/v1/models.py b/assemblyai/diarization/v1/models.py new file mode 100644 index 0000000..9961645 --- /dev/null +++ b/assemblyai/diarization/v1/models.py @@ -0,0 +1,169 @@ +"""Models for the Diarization API. + +The request options, the result and the error of `/v1/diarize` on +`diarization.assemblyai.com`, alongside the client that uses them. +""" + +from typing import List, Optional + +from ...types import AssemblyAIError, BaseModel, ConfigDict, Field, pydantic_v2 + +__all__ = [ + "DiarizationConfig", + "DiarizationError", + "DiarizationResponse", + "DiarizationSegment", + "DiarizationUtterance", + "DiarizedWord", +] + + +class DiarizationError(AssemblyAIError): + """ + Error raised when a Diarization API request fails. + + Carries a machine-readable `error_code`, the snake_cased problem-details + `title` from the server (e.g. `unauthorized`, `bad_request`, + `audio_too_large`), when present, and `retry_after` (seconds) for 429/503 + responses that include a `Retry-After` header. `status_code` is `401` for + a missing or invalid key and `400` for a request the API rejects + (an unknown config field, a transcript without `words`). + """ + + def __init__( + self, + message: str, + status_code: Optional[int] = None, + error_code: Optional[str] = None, + retry_after: Optional[int] = None, + ): + super().__init__(message, status_code) + self.error_code = error_code + self.retry_after = retry_after + + +class DiarizationConfig(BaseModel): + """ + Options for a Diarization API request. + + `sample_rate` and `channels` are required only for raw PCM audio; + container formats carry them in their own headers. + + Unknown fields are rejected rather than silently dropped: the API + accepts this exact set and answers `400` to anything else. + """ + + sample_rate: Optional[int] = None + """Source sample rate in Hz. Setting either this or `channels` marks the + audio as raw 16-bit PCM, and both are then required.""" + + channels: Optional[int] = None + """Channel count (1 mono, 2 stereo). Setting either this or `sample_rate` + marks the audio as raw 16-bit PCM, and both are then required.""" + + language_code: Optional[str] = None + """A bare language code such as `en` or `es` (default `en`). Decides + whether the words of one sentence are voted onto one speaker. Unused + without a transcript.""" + + if pydantic_v2: + model_config = ConfigDict(extra="forbid") + else: + + class Config: + extra = "forbid" + + +class DiarizedWord(BaseModel): + """A transcript word with the speaker who said it.""" + + text: str + "The text of the word." + + start: int + "Word start in milliseconds." + + end: int + "Word end in milliseconds." + + confidence: Optional[float] = None + "The word's transcription confidence, when the transcript carried one." + + speaker: str + "The speaker label: `A`, `B`, and so on." + + speaker_confidence: Optional[float] = None + "Confidence in the speaker label, 0-1. `None` when unavailable." + + +class DiarizationUtterance(BaseModel): + """A run of consecutive words by one speaker.""" + + speaker: str + "The speaker label." + + start: int + "Start of the first word in milliseconds." + + end: int + "End of the last word in milliseconds." + + text: str + "The words' text, joined." + + confidence: Optional[float] = None + "Mean word confidence." + + speaker_confidence: Optional[float] = None + "Mean word speaker confidence. `None` unless every word carries one." + + words: List[DiarizedWord] = Field(default_factory=list) + "The utterance's words." + + +class DiarizationSegment(BaseModel): + """One of the model's speaker turns.""" + + start: int + "Segment start in milliseconds." + + end: int + "Segment end in milliseconds." + + speaker: str + "The speaker label, the same speaker as in `words`." + + speaker_confidence: Optional[float] = None + "The segment's calibrated confidence. `None` when unavailable." + + +class DiarizationResponse(BaseModel): + """ + The result of a Diarization API request. + + Without a transcript, `words` and `utterances` are empty and `segments` + and `speakers` are filled. `speakers` lists only the speakers words went + to when there are words; a speaker no word went to appears in `segments` + alone. + """ + + words: List[DiarizedWord] = Field(default_factory=list) + "The transcript's words, each with a speaker." + + utterances: List[DiarizationUtterance] = Field(default_factory=list) + "Runs of consecutive words by one speaker." + + segments: List[DiarizationSegment] = Field(default_factory=list) + "The model's speaker turns, sorted by start." + + speakers: List[str] = Field(default_factory=list) + "The sorted speaker labels." + + audio_duration_ms: int + "Total audio duration in milliseconds." + + session_id: str + "Server-generated UUID for this request. Record it to correlate with support." + + request_time_ms: Optional[float] = None + "End-to-end server-side request time in milliseconds." diff --git a/assemblyai/types.py b/assemblyai/types.py index 4c36780..e01e244 100644 --- a/assemblyai/types.py +++ b/assemblyai/types.py @@ -156,6 +156,12 @@ class Settings(BaseSettings): producing audio is not counted. Sized to outlast the final segment's inference plus the LLM pass over the transcript.""" + diarization_base_url: str = "https://diarization.assemblyai.com" + "The base URL for the Diarization API (used by `Diarizer`/`AsyncDiarizer`). Set `https://diarization.us.assemblyai.com` or `https://diarization.eu.assemblyai.com` to keep requests in the US or EU data zone." + + diarization_http_timeout: float = 330.0 + "The HTTP timeout for Diarization API requests. Above the API's own 300-second inference limit plus its queue wait, so a request that reaches it gets the API's `504` as a `DiarizationError`, not a client timeout." + llm_gateway_base_url: str = "https://llm-gateway.assemblyai.com" "The base URL for the LLM Gateway API (used by `LLMGateway`/`AsyncLLMGateway`)" diff --git a/docs/check_api_docs.py b/docs/check_api_docs.py index b9a0f58..7ce56ea 100644 --- a/docs/check_api_docs.py +++ b/docs/check_api_docs.py @@ -17,6 +17,7 @@ "assemblyai/prerecorded/v2.html", "assemblyai/sync/v1.html", "assemblyai/dictation/v1.html", + "assemblyai/diarization/v1.html", "assemblyai/llm_gateway/v1.html", "assemblyai/streaming/v3.html", "assemblyai/tts/v1.html", @@ -26,6 +27,7 @@ "Transcriber", "SyncTranscriber", "DictationTranscriber", + "Diarizer", "LLMGateway", "RealTimeTranscriber", "TTSSession", @@ -35,6 +37,7 @@ "Transcriber.transcribe", "SyncTranscriber.transcribe", "DictationTranscriber.transcribe_live", + "Diarizer.diarize", "LLMGateway.chat", "RealTimeTranscriber.stream", "TTSSession.speak", diff --git a/scripts/build_api_docs.sh b/scripts/build_api_docs.sh index 16024b3..6372ff5 100755 --- a/scripts/build_api_docs.sh +++ b/scripts/build_api_docs.sh @@ -8,5 +8,6 @@ pdoc -o docs/api \ assemblyai.prerecorded.v2 \ assemblyai.sync.v1 \ assemblyai.dictation.v1 \ + assemblyai.diarization.v1 \ assemblyai.llm_gateway.v1 \ assemblyai.tts.v1 diff --git a/tests/unit/test_diarization.py b/tests/unit/test_diarization.py new file mode 100644 index 0000000..e646c16 --- /dev/null +++ b/tests/unit/test_diarization.py @@ -0,0 +1,437 @@ +"""Tests for the Diarization API client. + +Every call posts one buffered multipart body (`config`, `transcript`, +`audio`) to `/v1/diarize` on the diarization host and parses the JSON result. +""" + +import email +import io +import json +from typing import Any, Dict, List + +import httpx +import pytest +from pytest_httpx import HTTPXMock + +import assemblyai as aai + +aai.settings.api_key = "test" + +DIARIZE_URL = f"{aai.settings.diarization_base_url}/v1/diarize" + +_WORDS: List[Dict[str, Any]] = [ + {"text": "hello", "start": 0, "end": 400, "confidence": 0.9}, + {"text": "hi", "start": 4400, "end": 4700, "confidence": 0.95}, +] + +_OK_RESPONSE = { + "words": [ + {**_WORDS[0], "speaker": "A", "speaker_confidence": 0.93}, + {**_WORDS[1], "speaker": "B"}, + ], + "utterances": [ + { + "speaker": "A", + "start": 0, + "end": 400, + "text": "hello", + "confidence": 0.9, + "speaker_confidence": 0.93, + "words": [{**_WORDS[0], "speaker": "A", "speaker_confidence": 0.93}], + }, + { + "speaker": "B", + "start": 4400, + "end": 4700, + "text": "hi", + "confidence": 0.95, + "words": [{**_WORDS[1], "speaker": "B"}], + }, + ], + "segments": [ + {"start": 0, "end": 4200, "speaker": "A", "speaker_confidence": 0.93}, + {"start": 4350, "end": 9100, "speaker": "B"}, + ], + "speakers": ["A", "B"], + "audio_duration_ms": 9500, + "session_id": "eb92c4ff-4bbb-429f-9b99-7279d7fe738f", + "request_time_ms": 312.4, +} + +_SEGMENTS_ONLY = {**_OK_RESPONSE, "words": [], "utterances": []} + + +def _mock_ok(httpx_mock: HTTPXMock, body: dict = _OK_RESPONSE, url: str = DIARIZE_URL): + httpx_mock.add_response( + url=url, method="POST", status_code=httpx.codes.OK, json=body + ) + + +def _parts(request: httpx.Request) -> dict: + """The recorded multipart body as {name: email part}, in order.""" + + raw = b"Content-Type: " + request.headers["content-type"].encode() + b"\r\n\r\n" + message = email.message_from_bytes(raw + request.read()) + return { + part.get_param("name", header="content-disposition"): part + for part in message.get_payload() + } + + +def _json_part(part) -> dict: + assert part.get_content_type() == "application/json" + return json.loads(part.get_payload(decode=True)) + + +def _sent(httpx_mock: HTTPXMock) -> dict: + requests = httpx_mock.get_requests() + assert len(requests) == 1 + return _parts(requests[0]) + + +def test_diarize_with_a_transcript(httpx_mock: HTTPXMock): + # GIVEN a diarization host that labels the words + _mock_ok(httpx_mock) + + # WHEN WAV audio is diarized with a word list + result = aai.Diarizer().diarize(b"RIFF....", transcript={"words": _WORDS}) + + # THEN one buffered request carried the raw key, the transcript and audio + request = httpx_mock.get_requests()[0] + assert str(request.url) == DIARIZE_URL + assert request.headers["authorization"] == "test" + assert "content-length" in request.headers + parts = _sent(httpx_mock) + assert list(parts) == ["transcript", "audio"] + assert _json_part(parts["transcript"]) == {"words": _WORDS} + assert parts["audio"].get_content_type() == "audio/wav" + assert parts["audio"].get_payload(decode=True) == b"RIFF...." + + # AND the result is parsed + assert isinstance(result, aai.DiarizationResponse) + assert [w.speaker for w in result.words] == ["A", "B"] + assert result.words[0].speaker_confidence == 0.93 + assert result.words[1].speaker_confidence is None + assert result.utterances[1].text == "hi" + assert result.utterances[0].words[0].text == "hello" + assert result.segments[1].speaker_confidence is None + assert result.speakers == ["A", "B"] + assert result.audio_duration_ms == 9500 + assert result.session_id == _OK_RESPONSE["session_id"] + + +def test_diarize_without_a_transcript_runs_segments_only(httpx_mock: HTTPXMock): + # GIVEN a host answering segments only + _mock_ok(httpx_mock, _SEGMENTS_ONLY) + + # WHEN audio is diarized alone + result = aai.Diarizer().diarize(b"RIFF....") + + # THEN neither a transcript nor a config part was sent + assert list(_sent(httpx_mock)) == ["audio"] + + # AND the segments and speakers come back with no words + assert result.words == [] and result.utterances == [] + assert [s.speaker for s in result.segments] == ["A", "B"] + assert result.speakers == ["A", "B"] + + +def test_diarize_sends_an_explicit_empty_word_list(httpx_mock: HTTPXMock): + # GIVEN a host answering empty lists + _mock_ok(httpx_mock, {**_SEGMENTS_ONLY, "segments": [], "speakers": []}) + + # WHEN an empty word list is passed + aai.Diarizer().diarize(b"RIFF", transcript=[]) + + # THEN it is sent, not mistaken for segments-only mode + assert _json_part(_sent(httpx_mock)["transcript"]) == {"words": []} + + +def test_diarize_accepts_a_sync_transcript_response(httpx_mock: HTTPXMock): + # GIVEN a sync transcription result with timestamps + _mock_ok(httpx_mock) + transcript = aai.SyncTranscriptResponse( + text="hello hi", + words=[aai.SyncWord(**w) for w in _WORDS], + confidence=0.92, + audio_duration_ms=9500, + session_id="sync-session", + ) + + # WHEN it is passed as the transcript + aai.Diarizer().diarize(b"RIFF", transcript=transcript) + + # THEN its words are sent + assert _json_part(_sent(httpx_mock)["transcript"]) == {"words": _WORDS} + + +def test_diarize_accepts_a_list_of_words(httpx_mock: HTTPXMock): + # GIVEN a mix of SyncWord and dict words, one without timestamps + _mock_ok(httpx_mock) + words: List[Any] = [aai.SyncWord(text="hello", confidence=0.9), _WORDS[1]] + + # WHEN the list is passed + aai.Diarizer().diarize(b"RIFF", transcript=words) + + # THEN the unset timings are left out for the API to fill + assert _json_part(_sent(httpx_mock)["transcript"]) == { + "words": [{"text": "hello", "confidence": 0.9}, _WORDS[1]] + } + + +@pytest.mark.parametrize("transcript", ["hello hi", 42]) +def test_diarize_rejects_other_transcript_types(transcript): + with pytest.raises(TypeError, match="transcript must be"): + aai.Diarizer().diarize(b"RIFF", transcript=transcript) + + +def test_diarize_pcm_sends_config_and_pcm_content_type(httpx_mock: HTTPXMock): + # GIVEN raw PCM settings + _mock_ok(httpx_mock, _SEGMENTS_ONLY) + config = aai.DiarizationConfig(sample_rate=16000, channels=1, language_code="es") + + # WHEN raw bytes are diarized + aai.Diarizer().diarize(b"\x00\x01" * 160, config=config) + + # THEN the config precedes the audio, which is labelled audio/pcm + parts = _sent(httpx_mock) + assert list(parts) == ["config", "audio"] + assert _json_part(parts["config"]) == { + "sample_rate": 16000, + "channels": 1, + "language_code": "es", + } + assert parts["audio"].get_content_type() == "audio/pcm" + assert parts["audio"].get_filename() == "audio.pcm" + + +def test_diarize_pcm_requires_rate_and_channels(tmp_path): + path = tmp_path / "call.pcm" + path.write_bytes(b"\x00\x01") + + with pytest.raises(ValueError, match="sample_rate and channels"): + aai.Diarizer().diarize(path) + + +@pytest.mark.parametrize( + "name, content_type", + [ + ("call.mp3", "audio/mpeg"), + ("call.flac", "audio/flac"), + ("call.ogg", "audio/ogg"), + ("call.mp4", "audio/mp4"), + ("call.webm", "audio/webm"), + ("call.wav", "audio/wav"), + ("call.unknown", "audio/wav"), + ], +) +def test_diarize_infers_the_content_type_from_the_extension( + httpx_mock: HTTPXMock, tmp_path, name, content_type +): + _mock_ok(httpx_mock, _SEGMENTS_ONLY) + path = tmp_path / name + path.write_bytes(b"audio") + + aai.Diarizer().diarize(str(path)) + + audio = _sent(httpx_mock)["audio"] + assert audio.get_content_type() == content_type + assert audio.get_filename() == name + + +def test_diarize_names_a_file_object(httpx_mock: HTTPXMock, tmp_path): + _mock_ok(httpx_mock, _SEGMENTS_ONLY) + path = tmp_path / "call.mp3" + path.write_bytes(b"ID3") + + with open(path, "rb") as f: + aai.Diarizer().diarize(f) + + assert _sent(httpx_mock)["audio"].get_content_type() == "audio/mpeg" + + +def test_diarize_content_type_override_wins(httpx_mock: HTTPXMock): + _mock_ok(httpx_mock, _SEGMENTS_ONLY) + + aai.Diarizer().diarize(io.BytesIO(b"OggS"), content_type="audio/ogg") + + assert _sent(httpx_mock)["audio"].get_content_type() == "audio/ogg" + + +def test_diarize_rejects_a_url(): + with pytest.raises(ValueError, match="does not accept URLs"): + aai.Diarizer().diarize("https://example.com/call.wav") + + +def test_config_rejects_unknown_fields(): + with pytest.raises(ValueError): + aai.DiarizationConfig(speakers_expected=2) + + +def test_rejects_other_products_configs(): + with pytest.raises(TypeError, match="expects DiarizationConfig"): + aai.Diarizer(config=aai.SyncTranscriptionConfig()) + with pytest.raises(TypeError, match="expects DiarizationConfig"): + aai.Diarizer().diarize(b"RIFF", config=aai.DictationConfig()) + + +def test_default_config_and_per_call_override(httpx_mock: HTTPXMock): + # GIVEN a diarizer with a default config + _mock_ok(httpx_mock, _SEGMENTS_ONLY) + _mock_ok(httpx_mock, _SEGMENTS_ONLY) + diarizer = aai.Diarizer(config=aai.DiarizationConfig(language_code="de")) + + # WHEN one call uses it and one overrides it + diarizer.diarize(b"RIFF") + diarizer.diarize(b"RIFF", config=aai.DiarizationConfig(language_code="fr")) + + # THEN the override replaces the default + first, second = httpx_mock.get_requests() + assert _json_part(_parts(first)["config"]) == {"language_code": "de"} + assert _json_part(_parts(second)["config"]) == {"language_code": "fr"} + + +def test_unauthorized_maps_to_diarization_error(httpx_mock: HTTPXMock): + # GIVEN a missing key, which the API answers with a problem+json 401 + httpx_mock.add_response( + url=DIARIZE_URL, + method="POST", + status_code=401, + json={ + "status": 401, + "title": "Unauthorized", + "detail": "Missing Authorization header", + }, + headers={"content-type": "application/problem+json"}, + ) + + # WHEN diarizing, THEN a DiarizationError carries status, code and detail + with pytest.raises(aai.DiarizationError) as exc_info: + aai.Diarizer().diarize(b"RIFF") + + error = exc_info.value + assert error.status_code == 401 + assert error.error_code == "unauthorized" + assert "Missing Authorization header" in str(error) + assert isinstance(error, aai.AssemblyAIError) + assert not isinstance(error, aai.SyncTranscriptError) + + +@pytest.mark.parametrize( + "status, title, code", + [ + (400, "Bad Request", "bad_request"), + (411, "Length Required", "length_required"), + (413, "Audio Too Large", "audio_too_large"), + (415, "Unsupported Media Type", "unsupported_media_type"), + (504, "Inference Timeout", "inference_timeout"), + ], +) +def test_problem_details_map_to_diarization_error( + httpx_mock: HTTPXMock, status, title, code +): + httpx_mock.add_response( + url=DIARIZE_URL, + method="POST", + status_code=status, + json={"status": status, "title": title, "detail": "nope"}, + headers={"content-type": "application/problem+json"}, + ) + + with pytest.raises(aai.DiarizationError) as exc_info: + aai.Diarizer().diarize(b"RIFF", transcript={"words": _WORDS}) + + assert exc_info.value.status_code == status + assert exc_info.value.error_code == code + assert "nope" in str(exc_info.value) + + +def test_capacity_error_surfaces_retry_after(httpx_mock: HTTPXMock): + httpx_mock.add_response( + url=DIARIZE_URL, + method="POST", + status_code=503, + json={"status": 503, "title": "Capacity Exceeded", "detail": "busy"}, + headers={"Retry-After": "2"}, + ) + + with pytest.raises(aai.DiarizationError) as exc_info: + aai.Diarizer().diarize(b"RIFF") + + assert exc_info.value.error_code == "capacity_exceeded" + assert exc_info.value.retry_after == 2 + + +def test_non_json_error_keeps_the_status(httpx_mock: HTTPXMock): + httpx_mock.add_response( + url=DIARIZE_URL, method="POST", status_code=502, text="Bad Gateway" + ) + + with pytest.raises(aai.DiarizationError) as exc_info: + aai.Diarizer().diarize(b"RIFF") + + assert exc_info.value.status_code == 502 + assert "Bad Gateway" in str(exc_info.value) + + +def test_custom_base_url(httpx_mock: HTTPXMock): + # GIVEN a client pointed at the EU host + eu = "https://diarization.eu.assemblyai.com/" + _mock_ok( + httpx_mock, + _SEGMENTS_ONLY, + url="https://diarization.eu.assemblyai.com/v1/diarize", + ) + settings = aai.Settings(api_key="eu-key", diarization_base_url=eu) + + # WHEN diarizing through it + client = aai.Client(settings=settings) + aai.Diarizer(client=client).diarize(b"RIFF") + client.close() + + # THEN the request went to that host with its key + request = httpx_mock.get_requests()[0] + assert request.url.host == "diarization.eu.assemblyai.com" + assert request.headers["authorization"] == "eu-key" + + +def test_uses_the_diarization_timeout(httpx_mock: HTTPXMock): + _mock_ok(httpx_mock, _SEGMENTS_ONLY) + + aai.Diarizer().diarize(b"RIFF") + + timeout = httpx_mock.get_requests()[0].extensions["timeout"] + assert timeout["read"] == aai.settings.diarization_http_timeout + + +def test_api_key_constructor_builds_own_client(httpx_mock: HTTPXMock): + _mock_ok(httpx_mock, _SEGMENTS_ONLY) + + with aai.Diarizer(api_key="per-call-key") as diarizer: + diarizer.diarize(b"RIFF") + + assert httpx_mock.get_requests()[0].headers["authorization"] == "per-call-key" + + +def test_response_ignores_unknown_fields(httpx_mock: HTTPXMock): + _mock_ok(httpx_mock, {**_SEGMENTS_ONLY, "new_field": 1}) + + assert aai.Diarizer().diarize(b"RIFF").audio_duration_ms == 9500 + + +def test_diarization_settings_defaults(): + settings = aai.Settings() + + assert settings.diarization_base_url == "https://diarization.assemblyai.com" + assert settings.diarization_http_timeout == 330.0 + + +def test_public_names_are_exported(): + from assemblyai import diarization + from assemblyai.diarization import v1 + + for name in v1.__all__: + assert getattr(diarization, name) is getattr(v1, name) + assert aai.Diarizer is v1.Diarizer + assert aai.AsyncDiarizer is v1.AsyncDiarizer + assert aai.DiarizationError is v1.DiarizationError diff --git a/tests/unit/test_diarization_async.py b/tests/unit/test_diarization_async.py new file mode 100644 index 0000000..1ab2304 --- /dev/null +++ b/tests/unit/test_diarization_async.py @@ -0,0 +1,125 @@ +"""Tests for the asyncio Diarization API client. + +The request shape is covered by `test_diarization.py`; these pin the asyncio +twin: same route, same parts, same parsing, same errors, and its pool. +""" + +import json + +import pytest +from pytest_httpx import HTTPXMock + +import assemblyai as aai +from tests.unit.test_diarization import ( + _OK_RESPONSE, + _SEGMENTS_ONLY, + _WORDS, + DIARIZE_URL, + _json_part, + _mock_ok, + _sent, +) + +pytestmark = pytest.mark.asyncio + +aai.settings.api_key = "test" + + +async def test_diarize_with_a_sync_transcript(httpx_mock: HTTPXMock): + # GIVEN a sync transcription result + _mock_ok(httpx_mock) + transcript = aai.SyncTranscriptResponse( + text="hello hi", + words=[aai.SyncWord(**w) for w in _WORDS], + confidence=0.92, + audio_duration_ms=9500, + session_id="sync-session", + ) + + # WHEN it is diarized asynchronously + async with aai.AsyncDiarizer() as diarizer: + result = await diarizer.diarize(b"RIFF", transcript=transcript) + + # THEN the same parts were sent and the result parsed + parts = _sent(httpx_mock) + assert list(parts) == ["transcript", "audio"] + assert _json_part(parts["transcript"]) == {"words": _WORDS} + assert httpx_mock.get_requests()[0].headers["authorization"] == "test" + assert [u.speaker for u in result.utterances] == ["A", "B"] + assert result.session_id == _OK_RESPONSE["session_id"] + + +async def test_diarize_segments_only_with_pcm(httpx_mock: HTTPXMock, tmp_path): + # GIVEN a raw PCM file + _mock_ok(httpx_mock, _SEGMENTS_ONLY) + path = tmp_path / "call.raw" + path.write_bytes(b"\x00\x01" * 160) + config = aai.DiarizationConfig(sample_rate=8000, channels=2) + + # WHEN it is diarized without a transcript + async with aai.AsyncDiarizer(config=config) as diarizer: + result = await diarizer.diarize(path) + + # THEN config and PCM audio were sent, and segments came back + parts = _sent(httpx_mock) + assert list(parts) == ["config", "audio"] + assert json.loads(parts["config"].get_payload(decode=True)) == { + "sample_rate": 8000, + "channels": 2, + } + assert parts["audio"].get_content_type() == "audio/pcm" + assert result.words == [] and len(result.segments) == 2 + + +async def test_unauthorized_maps_to_diarization_error(httpx_mock: HTTPXMock): + httpx_mock.add_response( + url=DIARIZE_URL, + method="POST", + status_code=401, + json={"status": 401, "title": "Unauthorized", "detail": "Invalid key"}, + headers={"content-type": "application/problem+json"}, + ) + + async with aai.AsyncDiarizer() as diarizer: + with pytest.raises(aai.DiarizationError) as exc_info: + await diarizer.diarize(b"RIFF") + + assert exc_info.value.status_code == 401 + assert exc_info.value.error_code == "unauthorized" + + +async def test_custom_base_url_on_a_shared_client(httpx_mock: HTTPXMock): + # GIVEN a shared client pointed at the US host + _mock_ok( + httpx_mock, + _SEGMENTS_ONLY, + url="https://diarization.us.assemblyai.com/v1/diarize", + ) + settings = aai.Settings( + api_key="us-key", diarization_base_url="https://diarization.us.assemblyai.com" + ) + + async with aai.AsyncClient(settings=settings) as client: + diarizer = aai.AsyncDiarizer(client=client) + await diarizer.diarize(b"RIFF") + # WHEN the diarizer is closed, THEN the shared client stays open + await diarizer.aclose() + assert not client.http_client.is_closed + + assert httpx_mock.get_requests()[0].headers["authorization"] == "us-key" + + +async def test_rejects_other_products_configs(): + with pytest.raises(TypeError, match="expects DiarizationConfig"): + aai.AsyncDiarizer(config=aai.TTSConfig()) + + async with aai.AsyncDiarizer() as diarizer: + with pytest.raises(TypeError, match="expects DiarizationConfig"): + await diarizer.diarize(b"RIFF", config=aai.SyncTranscriptionConfig()) + + +async def test_owned_client_is_closed(): + diarizer = aai.AsyncDiarizer() + await diarizer.aclose() + + assert diarizer.client.http_client.is_closed