v1.3.2

Release 1.3.2 (Bugfix)

Maintenance release focused on stability and SSML handling.

Main fixes

• Improved streaming reliability with long texts.
• Fixed raw_ssml behavior: non-SSML text is now handled correctly in streaming mode.
• Reduced cases where XML tags could be spoken out loud.
• Improved resilience for imperfect SSML input (light sanitization + safe fallback).

User impact

• Better reliability in voice automations.
• Improved compatibility with multi-voice SSML scripts.
• Fewer regressions with mixed plain-text and markup messages.

v1.3.1

Release Notes

Overview

This release focuses on reliability and advanced SSML support for personal Home Assistant setups.

Changes

1. Home Assistant compatibility aligned with streaming support.
   • manifest.json now requires 2024.2.0+.
2. Streaming reliability improved.
   • Added retry for transient Azure errors (429, 500, 502, 503, 504).
   • Added forced buffer flush for long text without sentence-ending punctuation.
   • Added fallback to request.message when message_gen is unavailable.
3. New advanced option: allow_raw_ssml.
   • Added to integration options flow.
   • Default is false (safe behavior, message is escaped).
   • When enabled, raw SSML is accepted with XML validation.
   • Invalid SSML automatically falls back to escaped plain text to avoid Azure failures.
4. Per-call SSML override for tts.speak.
   • Added options.raw_ssml to force enable/disable raw SSML on a single request.
   • Priority: options.raw_ssml > global allow_raw_ssml > default false.
5. Language compatibility fix for service calls.
   • supported_languages now exposes both original and lowercase locale formats (for example it-IT and it-it).

New Option

• Name: allow_raw_ssml
• Location: Integration Options -> Voice step
• Type: Boolean
• Default: false

Per-Call Override

• Name: raw_ssml
• Location: options field in tts.speak
• Type: Boolean
• Default: not set (falls back to global allow_raw_ssml)

Behavior Matrix

1. options.raw_ssml is set in request
   • Per-call value is used.
2. options.raw_ssml not set + allow_raw_ssml = false
   • Input is always escaped.
   • Safest mode.
3. options.raw_ssml not set + allow_raw_ssml = true + message starts with <speak
   • Full SSML document is sent as-is.
4. options.raw_ssml not set + allow_raw_ssml = true + message does not start with <speak
   • Message is treated as SSML fragment inside integration wrapper.
5. Raw SSML invalid XML
   • Automatic fallback to escaped plain text.

Usage Examples

1. Standard plain text (default and recommended)

speech:
  type: plain
  text: "It's play time!"

2. Full SSML document (requires allow_raw_ssml: true)

speech:
  type: plain
  text: "<speak version='1.0' xml:lang='en-US'><voice name='en-US-JennyNeural'><prosody rate='+5%'>It's play time!</prosody></voice></speak>"

3. SSML fragment (requires allow_raw_ssml: true)

speech:
  type: plain
  text: "<break time='300ms'/>It's <emphasis level='moderate'>play time</emphasis>!"

Notes

1. If you pass full <speak>...</speak>, voice/prosody in that SSML may override integration-level defaults.
2. Keep allow_raw_ssml disabled unless you need direct SSML control.
3. You can set options.raw_ssml: true on a single service call without changing global settings.
4. Use either locale format in service calls (it-IT or it-it, en-US or en-us).
5. This integration is intended as a personal replacement for the legacy official Microsoft TTS integration.

Service Call Example (tts.speak)

action: tts.speak
target:
  entity_id: tts.microsoft_text_to_speech_tts
data:
  media_player_entity_id: media_player.soggiorno
  language: it-IT
  message: "<speak version='1.0' xml:lang='it-IT'><voice name='it-IT-ElsaNeural'><prosody rate='+5%'>Test SSML.</prosody></voice></speak>"
  options:
    raw_ssml: true

---

Full Changelog: 1.3.0...1.3.1

v1.3.0

Release Notes (v1.3.0)

v1.3.0 - Audio Format Handling Improvements

🐛 Bug Fixes

• Fixed hardcoded MP3 file extension that ignored user-configured output format
• Audio files now correctly use extension matching the configured Azure output format (e.g., .ogg for Opus, .g722 for G.722)
• Fixed missing auto-reload when changing integration options

✨ Enhancements

• Replaced free-text audio format field with categorized dropdown menu
• Added 12 pre-configured streaming audio formats with user-friendly labels
• Formats organized by use case: Recommended, Standard quality, VoIP/Telephony
• Integration now automatically reloads when options are changed (no manual restart required)
• Added debug logging for format detection and extension mapping

🎯 New Features

• Support for VoIP/telephony codecs: µ-law, A-law, G.722, AMR-WB
• Support for modern compressed formats: OGG Opus (24/48 kHz), WebM Opus
• Dynamic file extension mapping based on Azure format specification
• Auto-reload integration on options update via async_update_options() listener

🔧 Technical Changes

• Added _get_file_extension_from_format() helper function in tts.py
• Added AUDIO_FORMATS constant dictionary in const.py
• Modified config_flow.py to use vol.In() validator for format selection
• Added async_update_options() in init.py with entry update listener
• All supported formats are streaming-compatible (RIFF/non-streaming formats excluded)
• Debug logs added for initialization and format mapping

📋 Supported Formats

• MP3: 16/24/48 kHz (32-192 kbps)
• OGG Opus: 24/48 kHz
• WebM Opus: 24 kHz
• VoIP: µ-law, A-law (8 kHz), G.722 (16 kHz), AMR-WB (16 kHz)

⚠️ Notes

• Home Assistant TTS proxy may normalize file extensions to .mp3 for media player compatibility
• Audio quality and codec parameters are correctly applied regardless of file extension

Full Changelog: 1.2.0...1.3.0

v1.2.0

🎨 Improvements

Region Configuration

• Hybrid region selection: Choose from a dropdown of 37 predefined Azure regions or enter a custom region manually
• Better validation: Clear error messages when region is not specified
• Future-proof: Support for new Azure regions without code updates

Code Quality

• Centralized constants: All hardcoded URLs and values moved to const.py for easier maintenance
• Cleaned imports: Removed unused imports across all integration files
• Added translations: New strings.json file for proper internationalization support

Technical Details

• Azure TTS/Voices endpoints now use centralized constants
• All 37 current Azure Speech Service regions included in dropdown
• Backward compatible with existing configurations

v1.1.0

╔═════════════════════════════╗
║ MICROSOFT AZURE TTS STREAMING - IMPLEMENTATION
║ Version 1.1.0
╚═════════════════════════════╝

📊 CODE STATISTICS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
New methods implemented: 4
• async_stream_tts_audio() - Main streaming method
• _build_ssml() - SSML construction helper
• _resolve_voice_and_language() - Voice resolution helper
• _normalize_prosody_options() - Options normalization helper

✨ KEY FEATURES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Sentence-by-sentence streaming synthesis
✓ Multi-language sentence detection (140+ languages)
✓ 50-70% latency reduction for LLM voice assistants
✓ Full SSML support (voice, rate, pitch, volume, style, role)
✓ SSML input sanitization (special characters handling)
✓ Graceful error handling per sentence
✓ Backward compatible with non-streaming mode
✓ Modern Python async/await patterns
✓ Type hints and comprehensive docstrings

🌍 SUPPORTED LANGUAGES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• Latin scripts: . ! ?
• CJK languages: 。！？｡
• Arabic/Urdu: ؟ ۔
• Indic scripts: । ॥

🏗️ ARCHITECTURE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[LLM] → text chunks → [Buffer] → sentence detection → [Azure TTS]
↓
[Home Assistant] ← audio chunks (8KB) ← HTTP streaming ← [MP3]

🔧 TECHNICAL DETAILS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• Regex Pattern: Unicode-aware sentence boundaries
• Chunk Size: 8KB (AUDIO_CHUNK_SIZE = 8192)
• API Endpoint: Azure REST API v1 (streaming response)
• Response Format: Chunked Transfer Encoding via aiohttp
• Error Handling: Per-sentence isolation (failures don't stop stream)
• SSML Escaping: & < > " sanitization for spec compliance

📦 REQUIREMENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• Home Assistant 2024.2+ (for streaming support)
• Azure Cognitive Services Speech API key
• aiohttp (included in Home Assistant)

🚀 INSTALLATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Via HACS: Click the badge in README
Manual: Copy custom_components/microsoft/ to config directory

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Developed by @pajeronda | MIT License

1.0.1

Bugfix

Full Changelog: 1.0.0...1.0.1

v1.0.0

---

Microsoft Text-to-Speech (TTS) - Custom Component v1.0.0

This custom component replaces the official Home Assistant Microsoft TTS integration, which is no longer maintained and has become legacy.

Key Features:

• Modern config flow UI (no more YAML configuration)
• Full compatibility with Home Assistant 2023.10.0+
• Easy migration from the legacy integration

Migration Notes:
If you're upgrading from the legacy YAML-based integration, remove the old configuration from configuration.yaml (save your API key and region first), then install this component and configure it through the UI.

---

Full Changelog: https://github.com/pajeronda/microsoft/commits/1.0.0