Cartesia TTS v1.1.2

v1.1.2

Fixed

• A Cartesia request that timed out (as opposed to failing to connect) escaped the API client's error handling. During startup this prevented the automatic setup retry, and during speech synthesis it produced an unhandled-exception traceback instead of a proper service call error. Timeouts are now handled the same way as connection failures.
• Minimum Home Assistant version in hacs.json corrected from 2024.1.0 to 2025.1.0. The code requires features introduced after 2024.1, so HACS previously allowed installs on HA versions where the integration could not load.

Maintenance (internal only — no change to behaviour or configuration)

• Extracted /voices response-page parsing from the pagination loop into a _parse_voice_page helper.
• The model-selection form is now rendered by one shared _show_model helper instead of four identical blocks across the setup and options flows.
• Unified the tts.speak option-validation helpers so both log their own warnings, and an empty voice option now warns and falls back like an empty voice_id instead of being silently ignored.
• Removed a redundant default-voice injection in async_get_tts_audio (the validator already applies the configured default) and an unused stored API-key attribute on the client.
• Renamed the navigation radio on the settings step from voice_action to nav_action (its label is unchanged).
• Trimmed usage examples from the tts.py module docstring that duplicated this README.
• Sorted imports and added a Ruff lint job to CI.

Docs

• Documented the voice option (set by the HA voice picker) and the voice resolution order in the Options Reference.

Tests

• Added timeout coverage for all three Cartesia API methods and a regression test for the empty voice option warning.

v1.1.1

v1.1.1

Maintenance (internal only — no change to behaviour or configuration)

• Deduplicated the setup and options flows: the shared settings/voice form rendering now lives in a single _CartesiaStepsMixin, and entry-option assembly is centralised in one _build_options helper.
• Centralised the voice/language matching rules (lang_matches, voice_supports_language) in voice_cache.py so the voice browser and the Configure dialog can no longer drift apart.
• Simplified tts.speak option validation with shared _resolve_choice/_resolve_clamped helpers, replacing six near-identical validation blocks.
• Removed an unused lazy-load path (VoiceCache.async_ensure_loaded) and its tests; tightened type hints and a misleading migration log line.

Optimization

• The Configure dialog now fetches the voice list from the Cartesia API once per session (on first reaching the voice step) instead of on every form render and back-navigation.
• Setup now validates the API key and loads voices in a single request instead of two.

[Doc]

• Added mesa_profile.json

v1.1.0

Changelog

v1.1.0

New

• Added Sonic 3.5 support and made it the new recommended default model (42 languages, ~100ms latency).
• API key can now be changed without reinstalling the integration: use Reconfigure from the three-dot menu, or respond to the automatic repair prompt if the key is rejected mid-session.
• Voice browser in HA (used by Assist pipelines and the voice picker) now works immediately after an HA restart - the voice list is populated during entry setup.
• Configure dialog always fetches a fresh voice list from the Cartesia API, so newly added voices appear without restarting HA.

Fixed

• language: field in tts.speak (e.g. language: fr) was silently ignored; it now correctly overrides the default language.
• Voice selection via the HA voice picker was silently ignored; it now takes priority over the configured default voice.
• Passing a non-string value for model, language, or emotion (e.g. a list) would raise an unhandled TypeError; it now falls back gracefully with a warning.
• Language was previously validated only against the sonic-3 language set regardless of which model was selected; it is now validated against the resolved model's supported languages.
• An expired or revoked API key detected during speech synthesis now triggers HA's standard repair UI instead of logging silently.
• A network error when loading voices during Configure would crash the dialog with a generic error; it now shows a "cannot connect" message and returns to the settings step.
• Going back from the settings step to the model step discarded any values the user had just entered; form values are now preserved on back navigation.
• Voice dropdown in Configure was case-sensitive when sorting, causing voices with lowercase names to sort after "Z"; sorting is now case-insensitive.
• MP3 output_format payload updated to match the current Cartesia API spec (removed non-standard encoding field, added bit_rate).
• Manifest version field corrected from 1.0.2 to 1.1.0.
• Errors during synthesis now surface as proper HA service call errors with descriptive messages rather than silent no-audio failures.

Updated

• Cartesia API version header updated to 2026-03-01.
• Added single_config_entry: true and integration_type: service to manifest.
• Redundant all_voices dict merge removed from the setup flow voice step.

v1.0.2

General bug fixes plus documentation improvements

v1.0.1

v1.0.1

Minor improvements and bug squashing

• Voice name fallback - voice name now falls back to the stored name, then the voice ID, never an empty string
• Language matching - improved from startswith("en") to == "en" or startswith("en-") to prevent potential false matches like "eng"
• Option validation - added _validate_options() in tts.py that validates all six tts.speak options before the API call, logging clear warnings with valid values on bad input
• Schema migration - added async_migrate_entry() in __init__.py and MINOR_VERSION = 1 in the config flow for future-safe schema upgrades
• Structured error handling - added CartesiaQuotaError, CartesiaConcurrencyError, CartesiaPlanError in api.py with a _parse_error() helper, giving distinct log messages per error type
• README.md - overall improvements for clarity

v1.0

Initial release

• Fully supports all Cartesia Sonic 3 languages and voices

v1.0.0

Initial release. Fully supports all Cartesia Sonic languages and voices.