Imported from rafaalbelda/notifier_hub (AGENTS.md). Install upstream with npx skills add rafaalbelda/notifier_hub. Copyright stays with the author.

Notifier Hub Integration - AI Agent Guidelines

This is a Home Assistant custom integration that provides a centralized notification hub supporting multiple channels: text notifications, Alexa TTS, Google/Cast TTS, phone calls, Home Assistant lifecycle notices, persistent notifications, and Auto Volume controls.

Quick Architecture

NotifierHub (coordinator)
├── NotificationManager (text/persistent messages)
├── AlexaManager (TTS + media playback)
├── GoogleManager (TTS + media playback)
└── PhoneManager (voice calls)

Entry Point: init.py initializes the hub, registers services/events, creates runtime entities, installs the optional dashboard, and coordinates message dispatch.

Key Patterns & Conventions

Manager Pattern

• AlexaManager and GoogleManager use asyncio.Queue for sequential TTS processing (prevents overlapping playback)
• Worker Pattern: Each manager has an async task consuming queue items one at a time
• Volume Management: Saves current volume → plays TTS → restores original volume
• Task Cleanup: Always cancel tasks on unload with proper error handling

Text Processing

• Use helper functions from helpers.py:
  • check_bool() - Convert string/value to boolean
  • return_list() - Convert comma-separated strings/lists/tuples to list
  • remove_tags() - Strip HTML/SSML tags for TTS
  • has_numbers() - Detect time/large numbers for duration estimation
  • estimate_speech_duration() - Calculate TTS playback time (formula: words × 0.42 + adjustments)
• Service-specific cleanup: Telegram needs captions, Pushover needs URLs, Discord needs embeds

Configuration

• Merged Config: Combines entry.data (setup) + entry.options (runtime updates)
• Runtime Updates: notifier_hub.set_config and editable entities update config entry options
• Constants: All magic strings in const.py
• Validation: Voluptuous schemas with sensible defaults
• Config Flow: config_flow.py uses entity selectors for media players
• Dashboard Install: install_dashboard copies the bundled Lovelace YAML to /config/notifier_hub_dashboard.yaml

State-Based Routing

Messages are routed through state checks:

• Location: Prefer configured persons; fall back to location_tracker entity (can suppress text and speech notifications)
• Speech Home Only: Adds an implicit location: home check to speech channels when enabled
• DND: Blocks TTS and phone if dnd_entity is "on"
• Guest Mode: Overrides location check if enabled
• Priority: Bypasses all toggles if priority_message_entity is "on"
• Toggles: text_notifications, screen_notifications, speech_notifications, alexa_notifications, google_notifications, phone_notifications, ha_event_notifications, auto_volume

Auto Volume

• Auto Volume uses editable time.* period starts and number.* period volumes
• Period state is exposed by sensor.notifier_hub_day_period and sensor.notifier_hub_day_period_volume
• Explicit per-message alexa.volume / google.volume takes precedence over Auto Volume
• Respect auto_volume_exclude_players before changing player volumes

Common Development Tasks

Adding a New Notification Channel

1. Create a new manager class in custom_components/notifier_hub/ extending the manager pattern
2. Initialize it in init.py during setup
3. Add config options to const.py
4. Update config schema in init.py
5. Update services.yaml with new service fields
6. Add routing logic to NotifierHub.dispatch() method

Modifying TTS Processing

• Alexa: alexa_manager.py handles SSML generation with voice, prosody, language tagging, speechcons
• Google: google_manager.py routes to configurable tts.* service
• Player Resolution: Both managers support entity IDs, friendly names, groups, and sensor values
• Speech Duration: helpers.py estimate_speech_duration() used for timing

Updating Text Notification Services

• notification_manager.py handles dispatch to notify.* services
• Each service has a payload builder: Telegram (photos), Pushover (priority), Discord (embeds), mobile_app (TTS injection), generic
• Text substitution chains apply regex replacements before sending (see SUB_NOWRAP, SUB_WRAP)

Adding Entities

• Extend NotifierHubEntity from entity.py
• Sensors go in sensor.py (debug status, last message, presence, Auto Volume period)
• Binary sensors go in binary_sensor.py (Alexa/Google speaking states)
• Switches go in switch.py (channel toggles, DND, guest mode, priority, Auto Volume)
• Numbers go in number.py (Auto Volume period volumes)
• Times go in time.py (Auto Volume period starts)
• Buttons go in button.py (test/action buttons)
• Text entities go in text.py (editable text values)
• No polling needed (_attr_should_poll = False)
• Update via async_update_state() which calls async_write_ha_state()

File Structure & Purposes

Testing & Debugging

Debug Sensor: Enable debug mode in config to populate sensor.notifier_hub_debug with status and error details.

Event Listener: Integration listens to notifier events for AppDaemon compatibility:

event: notifier
event_data:
  title: "Example"
  message: "Message content"
  notify: true
  alexa: { media_player: ..., type: tts, volume: 0.35 }

Service Call: Primary interface is notifier_hub.send service with full payload options.

Runtime Config: notifier_hub.set_config updates in-memory/runtime options without requiring a reload.

Queue Processing: Both Alexa and Google managers process TTS sequentially—use binary sensors to monitor when playback is happening.

Important Notes

• Single Instance: Only one notifier_hub integration per Home Assistant instance (unique_id enforced)
• No External Dependencies: Uses only built-in HA services (notify., tts., media_player.*)
• Async-First: All I/O operations are async-safe
• Language Support: Configurable defaults (default_language: es-ES) with per-message overrides
• Volume Control: TTS automatically manages volume—never sends bare volume commands
• Auto Volume: Period-based volume is a global fallback; message-level volume always wins
• Timing: tts_wait_time config provides buffer for speech duration estimation

Common Pitfalls to Avoid

1. Blocking the Queue: Don't add long-running operations to manager queues—they block subsequent TTS
2. Missing Task Cleanup: Always cancel async tasks in unload methods
3. Hardcoded Strings: Use constants from const.py
4. Direct Entity Updates: Use async_update_state() instead of directly setting _attr_state
5. Ignoring Config Merging: Always check both entry.data and entry.options for settings
6. Service Resolution: Use helper functions instead of assuming entity_id format

References

• README.md - Full user documentation with examples
• example_automation.yaml - Real-world usage examples
• Home Assistant Integration Documentation