$ show sfortis/openai_tts
This repository is a Home Assistant custom component that adds OpenAI-compatible text-to-speech to a HA instance. It is distributed as an integration for HACS and registered as a config-flow service integration. In production it exposes TTS entities, an `openai_tts.say` service that announces text to media players with automatic volume save/restore and optional chimes, and an `openai_tts.set_api_key` service for credential rotation. The architecture is a HA integration split into focused modules: config flow and profile subentries, a streaming TTS engine, a sentence-level audio pipelining layer, an ffmpeg-based loudness pipeline, push-driven API health tracking, cache and validation logic, repairs, diagnostics, and a large announcement orchestration module. Provider support is driven by declarative presets for OpenAI, Mistral, Groq, Lemonfox, Kokoro, Chatterbox, and custom OpenAI-compatible endpoints, and the code intentionally modern-targets HA's streaming TTS contract rather than retaining legacy fallback paths.
The LLM identified 5 files worth highlighting for reuse:
A pure, HA-free helper that keeps saved selector values selectable in both mapping-style and string-list option formats without mixing shapes. It is isolated enough to be unit-tested outside Home Assistant and reusable in any config UI that must reconcile saved values with dynamically generated options.
A streaming loudness normalization pipeline that feeds audio into ffmpeg and applies empirically selected filters (dynaudnorm plus a compressor) without buffering the whole clip. It demonstrates careful async hygiene, proper stream closure, and cancellation cleanup, making it a strong reusable pattern for audio post-processing in stream-oriented integrations.
A push-driven health tracker built on Home Assistant's DataUpdateCoordinator that classifies API failures into auth, quota, rate-limit, and network/server categories, then blocks requests during persistent outages with timed retry windows. This is a well-scoped, reusable pattern for third-party API integrations that need graceful degradation and status exposure.
Implements sentence-level pipelining of TTS audio so the first audio chunk can be emitted before the full message is generated, with MP3/WAV/PCM join logic and a single-request collapse optimization. It solves a nontrivial latency problem in TTS orchestration and is a genuinely instructive streaming architecture pattern.
The PROVIDER_PRESETS dictionary is a declarative capability model describing each supported provider's formats, voice listing behavior, speeds, extra request payload, and UI field constraints. Other modules branch on the presets rather than raw provider names, making the provider abstraction data-driven and easy to extend, which is a clean design worth emulating in integrations that support multiple API backends.