v0.5.15: Audio settings persistence, Sendspin discovery refactor, tap detection fix

PROJECT_PLAN.md

@@ -1150,6 +1150,50 @@ def _optimize_microphone_settings(self) -> None:
 
 **Fix**: Prioritize 16kHz in Sendspin supported formats list to avoid unnecessary resampling
 
+---
+
+## 🔧 v0.5.15 Updates (2026-01-11)
+
+### Feature 1: Audio Settings Persistence
+
+**Problem**: AGC Enabled, AGC Max Gain, Noise Suppression settings lost after restart.
+
+**Solution**: 
+- `models.py`: Added `agc_enabled`, `agc_max_gain`, `noise_suppression` fields to `Preferences` dataclass (Optional, None = use default)
+- `entity_registry.py`: Entity setters now save to `preferences.json`
+- `voice_assistant.py`: `_optimize_microphone_settings()` now restores saved values from preferences on startup
+
+**Behavior**:
+- First startup: Use optimized defaults (AGC=ON, MaxGain=30dB, NoiseSuppression=15%)
+- After user changes via Home Assistant: Values persisted and restored on restart
+
+### Feature 2: Sendspin Discovery Refactoring
+
+**Problem**: Sendspin mDNS discovery code was in `audio_player.py`, mixing concerns.
+
+**Solution**:
+- `zeroconf.py`: Added `SendspinDiscovery` class for mDNS service discovery
+- `audio_player.py`: Simplified to use `SendspinDiscovery` via callback pattern
+- Better separation of concerns: zeroconf.py handles all mDNS, audio_player.py handles audio
+
+### Fix 1: Tap Detection During Emotion Playback
+
+**Problem**: Tap detection was re-enabled after emotion playback completes, even during active conversation.
+
+**Root Cause**: `_play_emotion()` and `_wait_for_move_completion()` always re-enabled tap detection without checking pipeline state.
+
+**Fix**:
+- `satellite.py`: Check `_pipeline_active` before re-enabling tap detection
+- Only re-enable tap detection if conversation has ended (pipeline not active)
+
+**Related Files**:
+- `models.py` - Preferences fields
+- `entity_registry.py` - Entity setters with persistence
+- `voice_assistant.py` - Settings restoration on startup
+- `zeroconf.py` - SendspinDiscovery class
+- `audio_player.py` - Simplified Sendspin integration
+- `satellite.py` - Tap detection fix
+
 
 ---
 

index.html

@@ -123,6 +123,15 @@
 			<h2>Changelog</h2>
 		</div>
 		<div class="changelog-grid">
+			<div class="changelog-card">
+				<div class="version-badge">v0.5.15</div>
+				<span class="date">2026-01-11</span>
+				<ul>
+					<li>New: Audio settings persistence (AGC, Noise Suppression, Tap Sensitivity)</li>
+					<li>Refactor: Move Sendspin mDNS discovery to zeroconf.py for better code organization</li>
+					<li>Fix: Tap detection not re-enabled during emotion playback in conversation</li>
+				</ul>
+			</div>
 			<div class="changelog-card">
 				<div class="version-badge">v0.5.14</div>
 				<span class="date">2026-01-11</span>

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reachy_mini_ha_voice"
-version = "0.5.14"
+version = "0.5.15"
 description = "Home Assistant Voice Assistant for Reachy Mini"
 readme = "README.md"
 requires-python = ">=3.10"

reachy_mini_ha_voice/__init__.py

@@ -11,7 +11,7 @@ Key features:
 - Reachy Mini motion control integration
 """
 
-__version__ = "0.5.14"
+__version__ = "0.5.15"
 __author__ = "Desmond Dong"
 
 # Don't import main module here to avoid runpy warning

reachy_mini_ha_voice/audio_player.py

@@ -31,19 +31,6 @@ except ImportError:
     SENDSPIN_AVAILABLE = False
     _LOGGER.debug("aiosendspin not installed, Sendspin support disabled")
 
-# Check if zeroconf is available for mDNS discovery
-try:
-    from zeroconf.asyncio import AsyncServiceBrowser, AsyncZeroconf
-    ZEROCONF_AVAILABLE = True
-except ImportError:
-    ZEROCONF_AVAILABLE = False
-    _LOGGER.debug("zeroconf not installed, Sendspin auto-discovery disabled")
-
-
-# Sendspin mDNS service type
-SENDSPIN_SERVICE_TYPE = "_sendspin-server._tcp.local."
-SENDSPIN_DEFAULT_PATH = "/sendspin"
-
 
 def _get_stable_client_id() -> str:
     """Generate a stable client ID based on machine identity.
@@ -93,10 +80,7 @@ class AudioPlayer:
         self._sendspin_client: Optional["SendspinClient"] = None
         self._sendspin_enabled = False
         self._sendspin_url: Optional[str] = None
-        self._sendspin_loop: Optional[asyncio.AbstractEventLoop] = None
-        self._sendspin_discovery_task: Optional[asyncio.Task] = None
-        self._sendspin_zeroconf: Optional["AsyncZeroconf"] = None
-        self._sendspin_browser: Optional["AsyncServiceBrowser"] = None
+        self._sendspin_discovery: Optional["SendspinDiscovery"] = None
         self._sendspin_unsubscribers: List[Callable] = []
         
         # Audio buffer for Sendspin playback
@@ -113,7 +97,7 @@ class AudioPlayer:
     @property
     def sendspin_available(self) -> bool:
         """Check if Sendspin library is available."""
-        return SENDSPIN_AVAILABLE and ZEROCONF_AVAILABLE
+        return SENDSPIN_AVAILABLE
 
     @property
     def sendspin_enabled(self) -> bool:
@@ -157,53 +141,24 @@ class AudioPlayer:
             _LOGGER.debug("aiosendspin not installed, skipping Sendspin discovery")
             return
         
-        if not ZEROCONF_AVAILABLE:
-            _LOGGER.debug("zeroconf not installed, skipping Sendspin discovery")
-            return
-        
-        if self._sendspin_discovery_task is not None:
+        if self._sendspin_discovery is not None and self._sendspin_discovery.is_running:
             _LOGGER.debug("Sendspin discovery already running")
             return
         
+        # Import here to avoid circular imports
+        from .zeroconf import SendspinDiscovery
+        
         _LOGGER.info("Starting Sendspin server discovery...")
-        self._sendspin_loop = asyncio.get_running_loop()
-        self._sendspin_discovery_task = asyncio.create_task(self._discover_and_connect())
+        self._sendspin_discovery = SendspinDiscovery(self._on_sendspin_server_found)
+        await self._sendspin_discovery.start()
 
-    async def _discover_and_connect(self) -> None:
-        """Background task to discover and connect to Sendspin servers."""
-        try:
-            self._sendspin_zeroconf = AsyncZeroconf()
-            await self._sendspin_zeroconf.__aenter__()
-            
-            # Create a listener for Sendspin services
-            listener = _SendspinServiceListener(self)
-            self._sendspin_browser = AsyncServiceBrowser(
-                self._sendspin_zeroconf.zeroconf,
-                SENDSPIN_SERVICE_TYPE,
-                listener,
-            )
-            
-            _LOGGER.info("Sendspin discovery started, waiting for servers...")
-            
-            # Keep running until stopped
-            while True:
-                await asyncio.sleep(60)  # Check periodically
-                
-        except asyncio.CancelledError:
-            _LOGGER.debug("Sendspin discovery cancelled")
-        except Exception as e:
-            _LOGGER.error("Sendspin discovery error: %s", e)
-        finally:
-            await self._cleanup_discovery()
-
-    async def _cleanup_discovery(self) -> None:
-        """Clean up discovery resources."""
-        if self._sendspin_browser:
-            await self._sendspin_browser.async_cancel()
-            self._sendspin_browser = None
-        if self._sendspin_zeroconf:
-            await self._sendspin_zeroconf.__aexit__(None, None, None)
-            self._sendspin_zeroconf = None
+    async def _on_sendspin_server_found(self, server_url: str) -> None:
+        """Callback when a Sendspin server is discovered via mDNS.
+        
+        Args:
+            server_url: WebSocket URL of the discovered server.
+        """
+        await self._connect_to_server(server_url)
 
     async def _connect_to_server(self, server_url: str) -> bool:
         """Connect to a discovered Sendspin server as PLAYER.
@@ -408,18 +363,13 @@ class AudioPlayer:
 
     async def stop_sendspin(self) -> None:
         """Stop Sendspin discovery and disconnect from server."""
-        # Cancel discovery task
-        if self._sendspin_discovery_task is not None:
-            self._sendspin_discovery_task.cancel()
-            try:
-                await self._sendspin_discovery_task
-            except asyncio.CancelledError:
-                pass
-            self._sendspin_discovery_task = None
+        # Stop discovery
+        if self._sendspin_discovery is not None:
+            await self._sendspin_discovery.stop()
+            self._sendspin_discovery = None
         
         # Disconnect from server
         await self._disconnect_sendspin()
-        self._sendspin_loop = None
         
         _LOGGER.info("Sendspin stopped")
 
@@ -587,68 +537,3 @@ class AudioPlayer:
         self._unduck_volume = volume / 100.0
         self._duck_volume = self._unduck_volume / 2
         self._current_volume = self._unduck_volume
-
-
-# ========== Sendspin mDNS Service Listener ==========
-
-class _SendspinServiceListener:
-    """Listener for Sendspin server mDNS advertisements."""
-
-    def __init__(self, audio_player: AudioPlayer) -> None:
-        self._audio_player = audio_player
-        self._loop = audio_player._sendspin_loop
-
-    def _build_url(self, host: str, port: int, properties: dict) -> str:
-        """Build WebSocket URL from service info."""
-        path_raw = properties.get(b"path")
-        path = path_raw.decode("utf-8", "ignore") if isinstance(path_raw, bytes) else SENDSPIN_DEFAULT_PATH
-        if not path:
-            path = SENDSPIN_DEFAULT_PATH
-        if not path.startswith("/"):
-            path = "/" + path
-        host_fmt = f"[{host}]" if ":" in host else host
-        return f"ws://{host_fmt}:{port}{path}"
-
-    def add_service(self, zeroconf, service_type: str, name: str) -> None:
-        """Called when a Sendspin server is discovered."""
-        if self._loop is None:
-            return
-        asyncio.run_coroutine_threadsafe(
-            self._process_service(zeroconf, service_type, name),
-            self._loop,
-        )
-
-    def update_service(self, zeroconf, service_type: str, name: str) -> None:
-        """Called when a Sendspin server is updated."""
-        self.add_service(zeroconf, service_type, name)
-
-    def remove_service(self, zeroconf, service_type: str, name: str) -> None:
-        """Called when a Sendspin server goes offline."""
-        _LOGGER.info("Sendspin server removed: %s", name)
-
-    async def _process_service(self, zeroconf, service_type: str, name: str) -> None:
-        """Process discovered service and connect."""
-        try:
-            from zeroconf.asyncio import AsyncZeroconf
-            
-            # Get service info
-            azc = AsyncZeroconf(zc=zeroconf)
-            info = await azc.async_get_service_info(service_type, name)
-            
-            if info is None or info.port is None:
-                return
-            
-            addresses = info.parsed_addresses()
-            if not addresses:
-                return
-            
-            host = addresses[0]
-            url = self._build_url(host, info.port, info.properties)
-            
-            _LOGGER.info("Discovered Sendspin server: %s at %s", name, url)
-            
-            # Auto-connect to the server
-            await self._audio_player._connect_to_server(url)
-            
-        except Exception as e:
-            _LOGGER.warning("Error processing Sendspin service %s: %s", name, e)

reachy_mini_ha_voice/entity_registry.py

@@ -763,6 +763,30 @@ class EntityRegistry:
         """Setup Phase 12 entities: Audio processing parameters (via local SDK)."""
         rc = self.reachy_controller
 
+        def set_agc_enabled_with_save(enabled: bool) -> None:
+            """Set AGC enabled and save to preferences."""
+            rc.set_agc_enabled(enabled)
+            if hasattr(self.server, 'state') and self.server.state:
+                self.server.state.preferences.agc_enabled = enabled
+                self.server.state.save_preferences()
+                _LOGGER.debug("AGC enabled saved to preferences: %s", enabled)
+
+        def set_agc_max_gain_with_save(gain: float) -> None:
+            """Set AGC max gain and save to preferences."""
+            rc.set_agc_max_gain(gain)
+            if hasattr(self.server, 'state') and self.server.state:
+                self.server.state.preferences.agc_max_gain = gain
+                self.server.state.save_preferences()
+                _LOGGER.debug("AGC max gain saved to preferences: %.1f dB", gain)
+
+        def set_noise_suppression_with_save(level: float) -> None:
+            """Set noise suppression and save to preferences."""
+            rc.set_noise_suppression(level)
+            if hasattr(self.server, 'state') and self.server.state:
+                self.server.state.preferences.noise_suppression = level
+                self.server.state.save_preferences()
+                _LOGGER.debug("Noise suppression saved to preferences: %.1f%%", level)
+
         entities.append(SwitchEntity(
             server=self.server,
             key=get_entity_key("agc_enabled"),
@@ -772,7 +796,7 @@ class EntityRegistry:
             device_class="switch",
             entity_category=1,  # config
             value_getter=rc.get_agc_enabled,
-            value_setter=rc.set_agc_enabled,
+            value_setter=set_agc_enabled_with_save,
         ))
 
         entities.append(NumberEntity(
@@ -788,7 +812,7 @@ class EntityRegistry:
             mode=2,
             entity_category=1,  # config
             value_getter=rc.get_agc_max_gain,
-            value_setter=rc.set_agc_max_gain,
+            value_setter=set_agc_max_gain_with_save,
         ))
 
         entities.append(NumberEntity(
@@ -804,7 +828,7 @@ class EntityRegistry:
             mode=2,
             entity_category=1,  # config
             value_getter=rc.get_noise_suppression,
-            value_setter=rc.set_noise_suppression,
+            value_setter=set_noise_suppression_with_save,
         ))
 
         entities.append(BinarySensorEntity(

reachy_mini_ha_voice/models.py

@@ -49,6 +49,10 @@ class AvailableWakeWord:
 class Preferences:
     active_wake_words: List[str] = field(default_factory=list)
     tap_sensitivity: float = 0.5  # Tap detection threshold in g (0.5 = most sensitive)
+    # Audio processing settings (persisted from Home Assistant)
+    agc_enabled: Optional[bool] = None  # None = use hardware default
+    agc_max_gain: Optional[float] = None  # None = use hardware default
+    noise_suppression: Optional[float] = None  # None = use hardware default
 
 
 @dataclass

reachy_mini_ha_voice/satellite.py

@@ -918,24 +918,26 @@ class VoiceSatelliteProtocol(APIServer):
                         self._wait_for_move_completion(wlan_ip, move_uuid, tap_detector)
                     threading.Thread(target=wait_for_completion, daemon=True).start()
                 elif tap_detector:
-                    # Fallback: re-enable after 5 seconds if no UUID
+                    # Fallback: re-enable after 5 seconds if no UUID (only if pipeline not active)
                     def reenable_tap_fallback():
                         time.sleep(5.0)
-                        if tap_detector:
+                        if tap_detector and not self._pipeline_active:
                             tap_detector.set_enabled(True)
                             _LOGGER.debug("Tap detection re-enabled (fallback timeout)")
+                        elif self._pipeline_active:
+                            _LOGGER.debug("Pipeline active, tap detection stays disabled (fallback)")
                     threading.Thread(target=reenable_tap_fallback, daemon=True).start()
             else:
                 _LOGGER.warning(f"Failed to play emotion {emotion_name}: HTTP {response.status_code}")
-                # Re-enable tap detection on failure
-                if tap_detector:
+                # Re-enable tap detection on failure (only if pipeline not active)
+                if tap_detector and not self._pipeline_active:
                     tap_detector.set_enabled(True)
 
         except Exception as e:
             _LOGGER.error(f"Error playing emotion {emotion_name}: {e}")
-            # Re-enable tap detection on error
+            # Re-enable tap detection on error (only if pipeline not active)
             tap_detector = getattr(self.state, 'tap_detector', None)
-            if tap_detector:
+            if tap_detector and not self._pipeline_active:
                 tap_detector.set_enabled(True)
 
     def _wait_for_move_completion(self, wlan_ip: str, move_uuid: str, tap_detector) -> None:
@@ -974,7 +976,10 @@ class VoiceSatelliteProtocol(APIServer):
             else:
                 _LOGGER.warning(f"Move {move_uuid} did not complete within {MAX_WAIT_SECONDS}s")
         finally:
-            # Always re-enable tap detection
-            if tap_detector:
+            # Only re-enable tap detection if pipeline is NOT active
+            # This prevents re-enabling during conversation when emotion was triggered
+            if tap_detector and not self._pipeline_active:
                 tap_detector.set_enabled(True)
                 _LOGGER.debug("Tap detection re-enabled after move completion")
+            elif self._pipeline_active:
+                _LOGGER.debug("Pipeline active, tap detection stays disabled after move")

reachy_mini_ha_voice/voice_assistant.py

@@ -236,6 +236,9 @@ class VoiceAssistantService:
         This method configures the XMOS XVF3800 audio processor for optimal
         voice command recognition at distances up to 2-3 meters.
         
+        If user has previously set values via Home Assistant, those values are
+        restored from preferences. Otherwise, default optimized values are used.
+        
         Key optimizations:
         1. Enable AGC with higher max gain for distant speech
         2. Reduce noise suppression to preserve quiet speech
@@ -260,20 +263,28 @@ class VoiceAssistantService:
                 _LOGGER.debug("ReSpeaker device not found")
                 return
             
+            # Get saved preferences (if any)
+            prefs = self._state.preferences if self._state else None
+            
             # ========== 1. AGC (Automatic Gain Control) Settings ==========
-            # Enable AGC for automatic volume normalization
+            # Use saved value if available, otherwise use default (enabled)
+            agc_enabled = prefs.agc_enabled if (prefs and prefs.agc_enabled is not None) else True
             try:
-                respeaker.write("PP_AGCONOFF", [1])
-                _LOGGER.info("AGC enabled (PP_AGCONOFF=1)")
+                respeaker.write("PP_AGCONOFF", [1 if agc_enabled else 0])
+                _LOGGER.info("AGC %s (PP_AGCONOFF=%d)%s", 
+                            "enabled" if agc_enabled else "disabled",
+                            1 if agc_enabled else 0,
+                            " [from preferences]" if (prefs and prefs.agc_enabled is not None) else " [default]")
             except Exception as e:
-                _LOGGER.debug("Could not enable AGC: %s", e)
+                _LOGGER.debug("Could not set AGC: %s", e)
             
-            # Increase AGC max gain for better distant speech pickup
-            # Default is ~15dB, increase to 30dB for voice commands at distance
-            # Range: 0-40 dB (float)
+            # Use saved value if available, otherwise use default (30dB)
+            agc_max_gain = prefs.agc_max_gain if (prefs and prefs.agc_max_gain is not None) else 30.0
             try:
-                respeaker.write("PP_AGCMAXGAIN", [30.0])
-                _LOGGER.info("AGC max gain increased (PP_AGCMAXGAIN=30.0dB)")
+                respeaker.write("PP_AGCMAXGAIN", [agc_max_gain])
+                _LOGGER.info("AGC max gain set (PP_AGCMAXGAIN=%.1fdB)%s",
+                            agc_max_gain,
+                            " [from preferences]" if (prefs and prefs.agc_max_gain is not None) else " [default]")
             except Exception as e:
                 _LOGGER.debug("Could not set PP_AGCMAXGAIN: %s", e)
             
@@ -282,7 +293,7 @@ class VoiceAssistantService:
             # Default is around -25dB, set to -18dB for stronger output
             try:
                 respeaker.write("PP_AGCDESIREDLEVEL", [-18.0])
-                _LOGGER.info("AGC desired level set (PP_AGCDESIREDLEVEL=-18.0dB)")
+                _LOGGER.debug("AGC desired level set (PP_AGCDESIREDLEVEL=-18.0dB)")
             except Exception as e:
                 _LOGGER.debug("Could not set PP_AGCDESIREDLEVEL: %s", e)
             
@@ -305,22 +316,26 @@ class VoiceAssistantService:
                 _LOGGER.debug("Could not set AUDIO_MGR_MIC_GAIN: %s", e)
             
             # ========== 3. Noise Suppression Settings ==========
-            # Reduce noise suppression to preserve quiet speech
+            # Use saved value if available, otherwise use default (15%)
             # PP_MIN_NS: minimum noise suppression threshold
             # Higher values = less aggressive suppression = better voice pickup
             # PP_MIN_NS = 0.85 means "keep at least 85% of signal" = 15% max suppression
             # UI shows "noise suppression strength" so 15% = PP_MIN_NS of 0.85
+            noise_suppression = prefs.noise_suppression if (prefs and prefs.noise_suppression is not None) else 15.0
+            pp_min_ns = 1.0 - (noise_suppression / 100.0)  # Convert percentage to PP_MIN_NS value
             try:
-                respeaker.write("PP_MIN_NS", [0.85])  # 15% noise suppression strength
-                _LOGGER.info("Noise suppression set to 15%% strength (PP_MIN_NS=0.85)")
+                respeaker.write("PP_MIN_NS", [pp_min_ns])
+                _LOGGER.info("Noise suppression set to %.0f%% strength (PP_MIN_NS=%.2f)%s",
+                            noise_suppression, pp_min_ns,
+                            " [from preferences]" if (prefs and prefs.noise_suppression is not None) else " [default]")
             except Exception as e:
                 _LOGGER.debug("Could not set PP_MIN_NS: %s", e)
             
             # PP_MIN_NN: minimum noise floor estimation
             # Higher values = less aggressive noise floor tracking
             try:
-                respeaker.write("PP_MIN_NN", [0.85])  # Match PP_MIN_NS
-                _LOGGER.info("Noise floor threshold set (PP_MIN_NN=0.85)")
+                respeaker.write("PP_MIN_NN", [pp_min_ns])  # Match PP_MIN_NS
+                _LOGGER.debug("Noise floor threshold set (PP_MIN_NN=%.2f)", pp_min_ns)
             except Exception as e:
                 _LOGGER.debug("Could not set PP_MIN_NN: %s", e)
             
@@ -339,7 +354,8 @@ class VoiceAssistantService:
             except Exception as e:
                 _LOGGER.debug("Could not set AEC_HPFONOFF: %s", e)
             
-            _LOGGER.info("Microphone settings optimized for voice recognition (AGC=ON, MaxGain=30dB, MicGain=2.0x)")
+            _LOGGER.info("Microphone settings initialized (AGC=%s, MaxGain=%.0fdB, NoiseSuppression=%.0f%%)",
+                        "ON" if agc_enabled else "OFF", agc_max_gain, noise_suppression)
             
         except Exception as e:
             _LOGGER.warning("Failed to optimize microphone settings: %s", e)

reachy_mini_ha_voice/zeroconf.py

@@ -1,21 +1,43 @@
-"""Runs mDNS zeroconf service for Home Assistant discovery."""
+"""Runs mDNS zeroconf services for Home Assistant and Sendspin discovery."""
 
+import asyncio
 import logging
 import socket
-from typing import Optional
+from typing import Callable, Optional, TYPE_CHECKING
 
 from .util import get_mac
 
+if TYPE_CHECKING:
+    from zeroconf.asyncio import AsyncServiceBrowser
+
 _LOGGER = logging.getLogger(__name__)
 
 try:
-    from zeroconf.asyncio import AsyncServiceInfo, AsyncZeroconf
+    from zeroconf.asyncio import AsyncServiceInfo, AsyncZeroconf, AsyncServiceBrowser
+    ZEROCONF_AVAILABLE = True
 except ImportError:
     _LOGGER.fatal("pip install zeroconf")
     raise
 
 MDNS_TARGET_IP = "224.0.0.251"
 
+# Sendspin mDNS service type
+SENDSPIN_SERVICE_TYPE = "_sendspin-server._tcp.local."
+SENDSPIN_DEFAULT_PATH = "/sendspin"
+
+
+def get_local_ip() -> str:
+    """Get local IP address for mDNS."""
+    test_sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    test_sock.setblocking(False)
+    try:
+        test_sock.connect((MDNS_TARGET_IP, 1))
+        return test_sock.getsockname()[0]
+    except Exception:
+        return "127.0.0.1"
+    finally:
+        test_sock.close()
+
 
 class HomeAssistantZeroconf:
     """Zeroconf service for Home Assistant discovery."""
@@ -27,15 +49,7 @@ class HomeAssistantZeroconf:
         self.name = name or f"reachy-mini-{get_mac()[:6]}"
 
         if not host:
-            test_sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
-            test_sock.setblocking(False)
-            try:
-                test_sock.connect((MDNS_TARGET_IP, 1))
-                host = test_sock.getsockname()[0]
-            except Exception:
-                host = "127.0.0.1"
-            finally:
-                test_sock.close()
+            host = get_local_ip()
             _LOGGER.debug("Detected IP: %s", host)
 
         assert host
@@ -64,3 +78,157 @@ class HomeAssistantZeroconf:
 
     async def unregister_server(self) -> None:
         await self._aiozc.async_close()
+
+
+class SendspinDiscovery:
+    """mDNS discovery for Sendspin servers.
+    
+    Discovers Sendspin servers on the local network and notifies via callback
+    when a server is found.
+    """
+
+    def __init__(self, on_server_found: Callable[[str], asyncio.coroutine]) -> None:
+        """Initialize Sendspin discovery.
+        
+        Args:
+            on_server_found: Async callback called with server URL when discovered.
+        """
+        self._on_server_found = on_server_found
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._zeroconf: Optional[AsyncZeroconf] = None
+        self._browser: Optional["AsyncServiceBrowser"] = None
+        self._discovery_task: Optional[asyncio.Task] = None
+        self._running = False
+
+    @property
+    def is_running(self) -> bool:
+        """Check if discovery is running."""
+        return self._running
+
+    async def start(self) -> None:
+        """Start mDNS discovery for Sendspin servers."""
+        if self._running:
+            _LOGGER.debug("Sendspin discovery already running")
+            return
+        
+        _LOGGER.info("Starting Sendspin server discovery...")
+        self._loop = asyncio.get_running_loop()
+        self._running = True
+        self._discovery_task = asyncio.create_task(self._discover_loop())
+
+    async def _discover_loop(self) -> None:
+        """Background task to discover Sendspin servers."""
+        try:
+            self._zeroconf = AsyncZeroconf()
+            await self._zeroconf.__aenter__()
+            
+            listener = _SendspinServiceListener(self)
+            self._browser = AsyncServiceBrowser(
+                self._zeroconf.zeroconf,
+                SENDSPIN_SERVICE_TYPE,
+                listener,
+            )
+            
+            _LOGGER.info("Sendspin discovery started, waiting for servers...")
+            
+            # Keep running until stopped
+            while self._running:
+                await asyncio.sleep(60)
+                
+        except asyncio.CancelledError:
+            _LOGGER.debug("Sendspin discovery cancelled")
+        except Exception as e:
+            _LOGGER.error("Sendspin discovery error: %s", e)
+        finally:
+            await self._cleanup()
+
+    async def _cleanup(self) -> None:
+        """Clean up discovery resources."""
+        if self._browser:
+            await self._browser.async_cancel()
+            self._browser = None
+        if self._zeroconf:
+            await self._zeroconf.__aexit__(None, None, None)
+            self._zeroconf = None
+        self._running = False
+
+    async def stop(self) -> None:
+        """Stop Sendspin discovery."""
+        self._running = False
+        if self._discovery_task is not None:
+            self._discovery_task.cancel()
+            try:
+                await self._discovery_task
+            except asyncio.CancelledError:
+                pass
+            self._discovery_task = None
+        
+        await self._cleanup()
+        self._loop = None
+        _LOGGER.info("Sendspin discovery stopped")
+
+    async def _handle_service_found(self, url: str) -> None:
+        """Handle discovered service."""
+        try:
+            await self._on_server_found(url)
+        except Exception as e:
+            _LOGGER.error("Error in Sendspin server callback: %s", e)
+
+
+class _SendspinServiceListener:
+    """Listener for Sendspin server mDNS advertisements."""
+
+    def __init__(self, discovery: SendspinDiscovery) -> None:
+        self._discovery = discovery
+
+    def _build_url(self, host: str, port: int, properties: dict) -> str:
+        """Build WebSocket URL from service info."""
+        path_raw = properties.get(b"path")
+        path = path_raw.decode("utf-8", "ignore") if isinstance(path_raw, bytes) else SENDSPIN_DEFAULT_PATH
+        if not path:
+            path = SENDSPIN_DEFAULT_PATH
+        if not path.startswith("/"):
+            path = "/" + path
+        host_fmt = f"[{host}]" if ":" in host else host
+        return f"ws://{host_fmt}:{port}{path}"
+
+    def add_service(self, zeroconf, service_type: str, name: str) -> None:
+        """Called when a Sendspin server is discovered."""
+        if self._discovery._loop is None:
+            return
+        asyncio.run_coroutine_threadsafe(
+            self._process_service(zeroconf, service_type, name),
+            self._discovery._loop,
+        )
+
+    def update_service(self, zeroconf, service_type: str, name: str) -> None:
+        """Called when a Sendspin server is updated."""
+        self.add_service(zeroconf, service_type, name)
+
+    def remove_service(self, zeroconf, service_type: str, name: str) -> None:
+        """Called when a Sendspin server goes offline."""
+        _LOGGER.info("Sendspin server removed: %s", name)
+
+    async def _process_service(self, zeroconf, service_type: str, name: str) -> None:
+        """Process discovered service and notify callback."""
+        try:
+            azc = AsyncZeroconf(zc=zeroconf)
+            info = await azc.async_get_service_info(service_type, name)
+            
+            if info is None or info.port is None:
+                return
+            
+            addresses = info.parsed_addresses()
+            if not addresses:
+                return
+            
+            host = addresses[0]
+            url = self._build_url(host, info.port, info.properties)
+            
+            _LOGGER.info("Discovered Sendspin server: %s at %s", name, url)
+            
+            # Notify via callback
+            await self._discovery._handle_service_found(url)
+            
+        except Exception as e:
+            _LOGGER.warning("Error processing Sendspin service %s: %s", name, e)