v3.5b1: Volume timing fixes, TTS cache improvements, diagnostics

## Bug Fixes

### Volume Restoration Timing
- Fixed volume being restored too early when using chime or normalize features
- Volume restoration now correctly waits for full playback duration
- Improved detection of non-streaming audio mode (chime/normalize enabled)
- Added platform-specific timing buffers (Sonos: 500ms, Cast: 700ms)

### Chime Configuration
- Fixed chime settings not being applied from entity configuration
- Service now reads chime/normalize settings from TTS entity subentry config
- Settings from service call properly override entity defaults

### Voice Change Bug
- Added `default_options` property to TTS entity
- Voice/model/speed changes in config now properly invalidate HA's TTS cache
- HA's cache key now includes current voice configuration

## New Features

### Duration Metadata with Mutagen
- Added reliable MP3 metadata embedding using mutagen library
- Duration stored in ID3 TXXX:duration_ms tag
- Works across streaming and non-streaming modes
- Survives HA's TTS cache operations

### In-Memory Duration Cache
- Added MESSAGE_DURATIONS_KEY for fast duration lookups
- Shared cache across all TTS entities
- Reduces ffprobe calls for repeated messages

### Diagnostics Support
- New diagnostics.py for troubleshooting
- Exports config entry data (API key redacted)
- Shows subentry configurations
- Lists TTS entity states

## Code Quality

- Fixed deprecated `asyncio.get_event_loop()` calls
- Replaced with `asyncio.get_running_loop()`
- Fixed bare `except:` clauses
- Removed duplicate CONF_PROFILE_NAME definitions
- Added ConfigEntryAuthFailed and ConfigEntryNotReady imports
- Added type annotations to config flow classes

Author: sfortis

custom_components/openai_tts/__init__.py

@@ -12,6 +12,7 @@
 from homeassistant.const import Platform, ATTR_ENTITY_ID
 from homeassistant.core import HomeAssistant, ServiceCall
 from homeassistant.config_entries import ConfigEntry, ConfigSubentry
+from homeassistant.exceptions import ConfigEntryAuthFailed, ConfigEntryNotReady
 from homeassistant.helpers import config_validation as cv, device_registry as dr, entity_registry as er
 from homeassistant.components.media_player import DOMAIN as MP_DOMAIN
 
@@ -41,7 +42,6 @@
 PLATFORMS: list[str] = [Platform.TTS]
 SERVICE_NAME = "say"
 SUBENTRY_TYPE_PROFILE = "profile"
-CONF_PROFILE_NAME = "profile_name"
 
 # Service Schema
 SAY_SCHEMA = vol.Schema(
@@ -445,21 +445,58 @@ async def _handle_say(call: ServiceCall) -> None:
 
             # Validate TTS entity
             tts_entity = data["tts_entity"]
-            if not hass.states.get(tts_entity):
+            tts_state = hass.states.get(tts_entity)
+            if not tts_state:
                 raise ValueError(f"TTS entity {tts_entity} not found")
-            
-            # Get service data (excluding entity_id)
+
+            # Get TTS entity's default options from its config
+            # Look up the entity to get its default_options property
+            entity_defaults = {}
+            entity_reg = er.async_get(hass)
+            entity_entry = entity_reg.async_get(tts_entity)
+            if entity_entry and entity_entry.config_subentry_id:
+                # This is a subentry-based entity - find the parent and subentry
+                for entry in hass.config_entries.async_entries(DOMAIN):
+                    if hasattr(entry, 'subentries') and entry.subentries:
+                        for subentry_id, subentry in entry.subentries.items():
+                            if subentry_id == entity_entry.config_subentry_id:
+                                entity_defaults = {
+                                    "chime": subentry.data.get(CONF_CHIME_ENABLE, False),
+                                    "chime_sound": subentry.data.get(CONF_CHIME_SOUND, "threetone.mp3"),
+                                    "normalize_audio": subentry.data.get(CONF_NORMALIZE_AUDIO, False),
+                                }
+                                _LOGGER.debug("Found entity defaults from subentry: %s", entity_defaults)
+                                break
+            elif entity_entry and entity_entry.config_entry_id:
+                # Legacy entry - get from config entry options
+                config_entry = hass.config_entries.async_get_entry(entity_entry.config_entry_id)
+                if config_entry:
+                    entity_defaults = {
+                        "chime": config_entry.options.get(CONF_CHIME_ENABLE, config_entry.data.get(CONF_CHIME_ENABLE, False)),
+                        "chime_sound": config_entry.options.get(CONF_CHIME_SOUND, config_entry.data.get(CONF_CHIME_SOUND, "threetone.mp3")),
+                        "normalize_audio": config_entry.options.get(CONF_NORMALIZE_AUDIO, config_entry.data.get(CONF_NORMALIZE_AUDIO, False)),
+                    }
+                    _LOGGER.debug("Found entity defaults from config entry: %s", entity_defaults)
+
+            # Get service data - use entity defaults for options not explicitly set
             message = data["message"]
             language = data.get("language", "en")
+
+            # For chime/normalize_audio: use service call value if provided, else entity default
+            # Note: data.get("chime") returns None if not in call, False if explicitly set to False
+            chime_value = data.get("chime") if "chime" in data else entity_defaults.get("chime", False)
+            normalize_value = data.get("normalize_audio") if "normalize_audio" in data else entity_defaults.get("normalize_audio", False)
+            chime_sound_value = data.get("chime_sound") if "chime_sound" in data else entity_defaults.get("chime_sound")
+
             options = {
                 "voice": data.get("voice"),
                 "speed": data.get("speed"),
                 "instructions": data.get("instructions"),
-                "chime": data.get("chime", False),
-                "chime_sound": data.get("chime_sound"),
-                "normalize_audio": data.get("normalize_audio", False),
+                "chime": chime_value,
+                "chime_sound": chime_sound_value,
+                "normalize_audio": normalize_value,
             }
-            
+
             # Remove None values
             options = {k: v for k, v in options.items() if v is not None}
 

custom_components/openai_tts/config_flow.py

@@ -9,6 +9,7 @@
 import logging
 from urllib.parse import urlparse
 import uuid
+import aiohttp
 
 from homeassistant import data_entry_flow
 from homeassistant.config_entries import (
@@ -20,7 +21,7 @@
     SubentryFlowResult,
 )
 from homeassistant.helpers.selector import selector, TextSelector, TextSelectorConfig, TextSelectorType, TemplateSelector
-from homeassistant.exceptions import HomeAssistantError
+from homeassistant.exceptions import HomeAssistantError, ConfigEntryAuthFailed
 from homeassistant.core import callback
 
 from .const import (
@@ -39,17 +40,82 @@
     CONF_INSTRUCTIONS,
     CONF_VOLUME_RESTORE,
     CONF_PAUSE_PLAYBACK,
+    CONF_PROFILE_NAME,
 )
 
-CONF_PROFILE_NAME = "profile_name"
 SUBENTRY_TYPE_PROFILE = "profile"
 
 _LOGGER = logging.getLogger(__name__)
 
+# Custom exceptions for API validation
+class InvalidAPIKey(HomeAssistantError):
+    """Error to indicate invalid API key."""
+
+class CannotConnect(HomeAssistantError):
+    """Error to indicate connection failure."""
+
 def generate_entry_id() -> str:
     return str(uuid.uuid4())
 
-async def validate_user_input(user_input: dict):
+async def async_validate_api_key(api_key: str, url: str) -> bool:
+    """Validate the API key by making a minimal test request.
+
+    Args:
+        api_key: The OpenAI API key to validate
+        url: The API endpoint URL
+
+    Returns:
+        True if validation succeeds
+
+    Raises:
+        InvalidAPIKey: If the API key is invalid (401/403)
+        CannotConnect: If unable to connect to the API
+    """
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {api_key}"
+    }
+
+    # Make a minimal TTS request to validate the API key
+    # Using minimal text to reduce cost
+    payload = {
+        "model": "tts-1",
+        "input": ".",
+        "voice": "alloy",
+        "response_format": "mp3",
+    }
+
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                url,
+                json=payload,
+                headers=headers,
+                timeout=aiohttp.ClientTimeout(total=10)
+            ) as response:
+                if response.status == 401:
+                    _LOGGER.error("API key validation failed: Unauthorized (401)")
+                    raise InvalidAPIKey("Invalid API key")
+                elif response.status == 403:
+                    _LOGGER.error("API key validation failed: Forbidden (403)")
+                    raise InvalidAPIKey("API key does not have required permissions")
+                elif response.status >= 400:
+                    _LOGGER.error("API validation failed with status %d", response.status)
+                    raise CannotConnect(f"API returned status {response.status}")
+
+                # Success - we got audio data back
+                _LOGGER.debug("API key validation successful")
+                return True
+
+    except aiohttp.ClientError as err:
+        _LOGGER.error("Connection error during API validation: %s", err)
+        raise CannotConnect(f"Cannot connect to API: {err}") from err
+    except TimeoutError as err:
+        _LOGGER.error("Timeout during API validation")
+        raise CannotConnect("Connection timed out") from err
+
+async def validate_user_input(user_input: dict) -> None:
+    """Validate user input for config flow."""
     if user_input.get(CONF_API_KEY) is None:
         raise ValueError("API key is required")
 
@@ -89,9 +155,11 @@ async def async_step_user(self, user_input: dict[str, Any] | None = None) -> Con
         if user_input is not None:
             try:
                 await validate_user_input(user_input)
-                
+
                 # Check for duplicate API key
                 api_key = user_input.get(CONF_API_KEY)
+                api_url = user_input.get(CONF_URL, "https://api.openai.com/v1/audio/speech")
+
                 for entry in self._async_current_entries():
                     if entry.data.get(CONF_API_KEY) == api_key:
                         _LOGGER.error("An entry with this API key already exists: %s", entry.title)
@@ -102,7 +170,10 @@ async def async_step_user(self, user_input: dict[str, Any] | None = None) -> Con
                             data_schema=self.data_schema,
                             errors=errors,
                         )
-                
+
+                # Validate API key by making a test request
+                await async_validate_api_key(api_key, api_url)
+
                 # Use API key as the unique identifier (hashed for privacy)
                 import hashlib
                 api_key_hash = hashlib.sha256(api_key.encode()).hexdigest()[:16]
@@ -116,6 +187,10 @@ async def async_step_user(self, user_input: dict[str, Any] | None = None) -> Con
                 )
             except data_entry_flow.AbortFlow:
                 return self.async_abort(reason="already_configured")
+            except InvalidAPIKey:
+                errors["base"] = "invalid_api_key"
+            except CannotConnect:
+                errors["base"] = "cannot_connect"
             except HomeAssistantError as e:
                 _LOGGER.exception(str(e))
                 errors["base"] = str(e)
@@ -171,7 +246,53 @@ def async_supports_options_flow(cls, config_entry: ConfigEntry) -> bool:
         is_legacy = has_model_voice and not has_subentries
 
         return is_legacy
-    
+
+    async def async_step_reauth(self, entry_data: dict[str, Any]) -> ConfigFlowResult:
+        """Handle reauthorization flow triggered by auth failure."""
+        self._reauth_entry = self.hass.config_entries.async_get_entry(
+            self.context.get("entry_id")
+        )
+        return await self.async_step_reauth_confirm()
+
+    async def async_step_reauth_confirm(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
+        """Handle reauthorization confirmation."""
+        errors: dict[str, str] = {}
+
+        if user_input is not None:
+            try:
+                api_key = user_input.get(CONF_API_KEY)
+                api_url = self._reauth_entry.data.get(CONF_URL, "https://api.openai.com/v1/audio/speech")
+
+                # Validate the new API key
+                await async_validate_api_key(api_key, api_url)
+
+                # Update the entry with new credentials
+                self.hass.config_entries.async_update_entry(
+                    self._reauth_entry,
+                    data={**self._reauth_entry.data, CONF_API_KEY: api_key},
+                )
+                await self.hass.config_entries.async_reload(self._reauth_entry.entry_id)
+                return self.async_abort(reason="reauth_successful")
+
+            except InvalidAPIKey:
+                errors["base"] = "invalid_api_key"
+            except CannotConnect:
+                errors["base"] = "cannot_connect"
+            except Exception:
+                _LOGGER.exception("Unexpected error during reauth")
+                errors["base"] = "unknown_error"
+
+        return self.async_show_form(
+            step_id="reauth_confirm",
+            data_schema=vol.Schema({
+                vol.Required(CONF_API_KEY): str,
+            }),
+            errors=errors,
+            description_placeholders={
+                "title": self._reauth_entry.title if self._reauth_entry else "OpenAI TTS"
+            },
+        )
+
     async def async_step_reconfigure(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult:
         """Handle reconfiguration of the parent entry."""
         errors: dict[str, str] = {}
@@ -456,12 +577,12 @@ async def async_step_reconfigure(self, user_input: dict[str, Any] | None = None)
 
 class OpenAITTSOptionsFlow(OptionsFlow):
     """Handle options flow for OpenAI TTS."""
-    
-    def __init__(self, config_entry):
+
+    def __init__(self, config_entry: ConfigEntry) -> None:
         """Initialize options flow."""
         self._config_entry = config_entry
-    
-    async def async_step_init(self, user_input: dict | None = None):
+
+    async def async_step_init(self, user_input: dict | None = None) -> ConfigFlowResult:
         # Check if this is a profile (subentry) or main entry
         is_profile = hasattr(self._config_entry, 'subentry_type') and self._config_entry.subentry_type == SUBENTRY_TYPE_PROFILE
 

custom_components/openai_tts/const.py

@@ -26,4 +26,7 @@
 CONF_PAUSE_PLAYBACK = "pause_playback"
 
 # Profile name for sub-entries
-CONF_PROFILE_NAME = "profile_name"
+CONF_PROFILE_NAME = "profile_name"
+
+# Key for storing message-to-duration cache in hass.data
+MESSAGE_DURATIONS_KEY = "message_durations"

custom_components/openai_tts/diagnostics.py

@@ -0,0 +1,66 @@
+"""Diagnostics support for OpenAI TTS."""
+from __future__ import annotations
+
+from typing import Any
+
+from homeassistant.components.diagnostics import async_redact_data
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.core import HomeAssistant
+
+from .const import CONF_API_KEY, DOMAIN
+
+# Keys to redact from diagnostics
+TO_REDACT = {CONF_API_KEY}
+
+
+async def async_get_config_entry_diagnostics(
+    hass: HomeAssistant, entry: ConfigEntry
+) -> dict[str, Any]:
+    """Return diagnostics for a config entry."""
+    # Redact sensitive data from entry
+    data = {
+        "entry": {
+            "entry_id": entry.entry_id,
+            "version": f"{entry.version}.{entry.minor_version}",
+            "domain": entry.domain,
+            "title": entry.title,
+            "data": async_redact_data(dict(entry.data), TO_REDACT),
+            "options": async_redact_data(dict(entry.options), TO_REDACT),
+        },
+    }
+
+    # Add subentries info if present
+    if hasattr(entry, 'subentries') and entry.subentries:
+        data["subentries"] = []
+        for subentry_id, subentry in entry.subentries.items():
+            subentry_info = {
+                "subentry_id": subentry_id,
+                "title": subentry.title,
+                "subentry_type": getattr(subentry, 'subentry_type', None),
+                "data": async_redact_data(dict(subentry.data), TO_REDACT),
+            }
+            data["subentries"].append(subentry_info)
+
+    # Add TTS entity states
+    tts_entities = []
+    for state in hass.states.async_all("tts"):
+        if state.entity_id.startswith("tts.openai_tts"):
+            tts_entities.append({
+                "entity_id": state.entity_id,
+                "state": state.state,
+                "attributes": {
+                    k: v for k, v in state.attributes.items()
+                    if k not in TO_REDACT
+                },
+            })
+
+    data["tts_entities"] = tts_entities
+
+    # Add integration domain data (without sensitive info)
+    domain_data = hass.data.get(DOMAIN, {})
+    data["domain_data"] = {
+        "entry_count": len([k for k in domain_data.keys() if not k.startswith("_")]),
+        "has_main_entry": "main_entry" in domain_data,
+    }
+
+    return data

custom_components/openai_tts/manifest.json

@@ -9,6 +9,6 @@
   "documentation": "https://github.com/sfortis/openai_tts/",
   "iot_class": "cloud_polling",
   "issue_tracker": "https://github.com/sfortis/openai_tts/issues",
-  "requirements": [],
-  "version": "3.4b5"
+  "requirements": ["aiohttp>=3.9.0"],
+  "version": "3.5b1"
 }