Add conversation_app architecture documentation and analysis

.claude/settings.local.json

@@ -3,24 +3,51 @@
   "includeCoAuthoredBy": false,
   "permissions": {
     "allow": [
-      "SlashCommand(/zcf:git-commit)",
+      "Bash",
+      "BashOutput",
       "Edit",
+      "Glob",
+      "Grep",
+      "KillShell",
+      "NotebookEdit",
+      "Read",
+      "SlashCommand",
+      "Task",
+      "TodoWrite",
+      "WebFetch",
+      "WebSearch",
+      "Write",
+      "mcp__ide",
+      "mcp__exa",
+      "mcp__context7",
+      "mcp__mcp-deepwiki",
+      "mcp__Playwright",
+      "mcp__spec-workflow",
+      "mcp__open-websearch",
+      "mcp__serena",
+      "All",
+      "Bash(copy:*)",
+      "mcp__zread__search_doc",
+      "mcp__zread__read_file",
       "Bash(cd:*)",
-      "SlashCommand(/zcf:git-commit --emoji)",
-      "SlashCommand(/zcf:git-commit:*)",
-      "Bash(git:*)",
-      "Bash(ls:*)"
+      "Bash(ls:*)",
+      "Bash(find:*)",
+      "mcp__acp__Bash"
     ],
     "deny": [],
     "ask": []
   },
+  "model": "opus",
   "hooks": {},
-  "alwaysThinkingEnabled": true,
-  "outputStyle": "default",
   "statusLine": {
     "type": "command",
     "command": "%USERPROFILE%\\.claude\\ccline\\ccline.exe",
     "padding": 0
   },
-  "model": "opus"
-}
+  "enabledPlugins": {
+    "glm-plan-usage@zai-coding-plugins": true,
+    "glm-plan-bug@zai-coding-plugins": true
+  },
+  "outputStyle": "Explanatory",
+  "alwaysThinkingEnabled": true
+}

PROJECT_PLAN.md

@@ -850,10 +850,11 @@ During long-term operation, `reachy_mini daemon` would crash, causing robot to b
 
 ### Fix Solution
 
-#### 1. Reduce control loop frequency (movement_manager.py)
+#### 1. Control loop frequency (movement_manager.py)
 ```python
-# Reduced from 100Hz to 20Hz
-CONTROL_LOOP_FREQUENCY_HZ = 20  # 80% reduction in messages
+# Initially reduced from 100Hz to 20Hz, then later restored to 100Hz
+# See "Update (2026-01-12)" below for current status
+CONTROL_LOOP_FREQUENCY_HZ = 100  # Now restored to 100Hz
 ```
 
 #### 2. Add pose change detection (movement_manager.py)
@@ -937,11 +938,11 @@ Through deep analysis of SDK source code:
 
 ### Fix Solution
 
-#### 1. Further reduce control loop frequency (movement_manager.py)
+#### 1. Control loop frequency history (movement_manager.py)
 ```python
-# Reduced from 20Hz to 10Hz
-# 10Hz × 3 messages = 30 messages/second, safely below daemon's 50Hz capacity
-CONTROL_LOOP_FREQUENCY_HZ = 10
+# Evolution: 100Hz -> 20Hz -> 10Hz -> 100Hz (restored)
+# After daemon updates, 100Hz is now stable
+CONTROL_LOOP_FREQUENCY_HZ = 100  # Restored to 100Hz (2026-01-12)
 ```
 
 #### 2. Increase pose change threshold (movement_manager.py)
@@ -965,18 +966,20 @@ self._cache_ttl = 2.0
 
 ### Fix Results
 
-| Metric | Before (20Hz) | After (10Hz) | Improvement |
-|--------|---------------|--------------|-------------|
-| Control loop frequency | 20 Hz | 10 Hz | ↓ 50% |
-| Max Zenoh messages | 60 msg/s | 30 msg/s | ↓ 50% |
-| Actual messages (with change detection) | ~40 msg/s | ~15 msg/s | ↓ 62% |
-| Face tracking frequency | 15 Hz | 10 Hz | ↓ 33% |
-| State cache TTL | 1 second | 2 seconds | ↑ 100% |
-| Expected stability | Crash within hours | Stable operation | Major improvement |
+> **Note**: Control loop has been restored to 100Hz as of 2026-01-12. The table below shows historical values before restoration.
+
+| Metric | Before (20Hz) | After (10Hz) | Current (100Hz) |
+|--------|---------------|--------------|-----------------|
+| Control loop frequency | 20 Hz | 10 Hz | 100 Hz (restored) |
+| Max Zenoh messages | 60 msg/s | 30 msg/s | ~100 msg/s (optimized) |
+| Actual messages (with change detection) | ~40 msg/s | ~15 msg/s | ~30 msg/s |
+| Face tracking frequency | 15 Hz | 10 Hz | Adaptive (2-15 Hz) |
+| State cache TTL | 1 second | 2 seconds | 2 seconds |
+| Expected stability | Crash within hours | Stable operation | Stable (daemon updated) |
 
 ### Key Finding
 
-Reference `reachy_mini_conversation_app` uses 100Hz control loop, but it's an official app that may have special optimizations or runs on more powerful hardware. Our app needs more conservative settings.
+Reference `reachy_mini_conversation_app` uses 100Hz control loop. After daemon updates and optimizations (pose change threshold 0.005, state cache TTL 2s), our app now also runs stably at 100Hz.
 
 ### Related Files
 - `movement_manager.py` - Control loop frequency and pose threshold

reachy_mini_ha_voice/animations/conversation_animations.json

@@ -1,10 +1,12 @@
 {
   "animations": {
     "idle": {
-      "description": "No movement when idle - robot stays at neutral position",
-      "z_amplitude_m": 0.0,
-      "antenna_amplitude_rad": 0.0,
-      "frequency_hz": 0.0
+      "description": "Breathing animation when idle - gentle z-axis movement and antenna sway (same as conversation_app BreathingMove)",
+      "z_amplitude_m": 0.005,
+      "z_frequency_hz": 0.1,
+      "antenna_amplitude_rad": 0.262,
+      "antenna_move_name": "wiggle",
+      "frequency_hz": 0.5
     },
     "listening": {
       "description": "Attentive pose while listening to user - slight forward lean",
@@ -25,63 +27,149 @@
       "antenna_amplitude_rad": 0.25,
       "antenna_move_name": "wiggle",
       "frequency_hz": 0.4
-    },
-    "speaking": {
-      "description": "Speaking animation - multi-frequency natural head sway",
-      "pitch_amplitude_rad": 0.08,
-      "pitch_frequency_hz": 2.2,
-      "yaw_amplitude_rad": 0.13,
-      "yaw_frequency_hz": 0.6,
-      "roll_amplitude_rad": 0.04,
-      "roll_frequency_hz": 1.3,
-      "x_amplitude_m": 0.0045,
-      "x_frequency_hz": 0.35,
-      "y_amplitude_m": 0.00375,
-      "y_frequency_hz": 0.45,
-      "z_amplitude_m": 0.00225,
-      "z_frequency_hz": 0.25,
-      "antenna_amplitude_rad": 0.5,
-      "antenna_move_name": "wiggle",
-      "frequency_hz": 1.0
-    },
+    }
+  },
+  "emotions": {
     "happy": {
-      "description": "Happy/positive response",
-      "pitch_amplitude_rad": 0.08,
-      "z_amplitude_m": 0.01,
-      "antenna_amplitude_rad": 0.5,
-      "antenna_move_name": "both",
-      "frequency_hz": 1.2
+      "description": "Happy/joyful expression - bouncy head movement with excited antennas",
+      "duration": 2.0,
+      "pitch_amplitude": 0.15,
+      "z_amplitude": 0.015,
+      "antenna_left": 0.5,
+      "antenna_right": 0.5,
+      "frequency": 1.5
     },
     "sad": {
-      "description": "Sad/negative response - head droops",
-      "pitch_offset_rad": 0.1,
-      "pitch_amplitude_rad": 0.04,
-      "z_offset_m": -0.01,
-      "z_amplitude_m": 0.002,
-      "antenna_amplitude_rad": 0.1,
-      "antenna_move_name": "both",
-      "frequency_hz": 0.3
+      "description": "Sad/disappointed expression - drooping head and antennas",
+      "duration": 2.5,
+      "pitch": 0.15,
+      "z": -0.01,
+      "pitch_amplitude": 0.05,
+      "antenna_left": -0.2,
+      "antenna_right": -0.2,
+      "frequency": 0.3
+    },
+    "surprised": {
+      "description": "Surprised/shocked expression - head pulls back with alert antennas",
+      "duration": 1.5,
+      "pitch": -0.1,
+      "z": 0.01,
+      "antenna_left": 0.7,
+      "antenna_right": 0.7,
+      "frequency": 2.0
     },
     "confused": {
-      "description": "Confused/error state - head tilts",
-      "roll_amplitude_rad": 0.1,
-      "yaw_amplitude_rad": 0.12,
-      "pitch_amplitude_rad": 0.05,
-      "antenna_amplitude_rad": 0.4,
-      "antenna_move_name": "wiggle",
-      "frequency_hz": 0.7
+      "description": "Confused/puzzled expression - head tilts with asymmetric antennas",
+      "duration": 2.0,
+      "roll": 0.12,
+      "yaw_amplitude": 0.15,
+      "antenna_left": 0.3,
+      "antenna_right": -0.3,
+      "frequency": 0.8
+    },
+    "excited": {
+      "description": "Excited/enthusiastic expression - energetic multi-axis movement",
+      "duration": 2.0,
+      "pitch_amplitude": 0.12,
+      "yaw_amplitude": 0.1,
+      "z_amplitude": 0.02,
+      "antenna_left": 0.6,
+      "antenna_right": 0.6,
+      "frequency": 2.0
+    },
+    "thinking_emotion": {
+      "description": "Thinking/pondering expression - slight tilt with slow movement",
+      "duration": 2.0,
+      "roll": 0.08,
+      "pitch": -0.05,
+      "yaw_amplitude": 0.08,
+      "antenna_left": 0.4,
+      "antenna_right": -0.2,
+      "frequency": 0.4
+    },
+    "nod": {
+      "description": "Nodding gesture - quick up-down head movement",
+      "duration": 0.8,
+      "pitch_amplitude": 0.2,
+      "frequency": 2.5
+    },
+    "shake": {
+      "description": "Shaking gesture - quick left-right head movement",
+      "duration": 0.8,
+      "yaw_amplitude": 0.25,
+      "frequency": 3.0
+    },
+    "curious": {
+      "description": "Curious/interested expression - head tilts forward with alert antennas",
+      "duration": 1.5,
+      "pitch": -0.08,
+      "roll": 0.1,
+      "antenna_left": 0.5,
+      "antenna_right": 0.3,
+      "frequency": 0.6
+    },
+    "sleepy": {
+      "description": "Sleepy/tired expression - slow drooping movement",
+      "duration": 3.0,
+      "pitch": 0.12,
+      "z": -0.015,
+      "pitch_amplitude": 0.03,
+      "antenna_left": -0.4,
+      "antenna_right": -0.4,
+      "frequency": 0.15
+    },
+    "angry": {
+      "description": "Angry/frustrated expression - intense forward lean with tense antennas",
+      "duration": 1.5,
+      "pitch": -0.12,
+      "roll_amplitude": 0.08,
+      "antenna_left": 0.8,
+      "antenna_right": 0.8,
+      "frequency": 1.8
+    },
+    "shy": {
+      "description": "Shy/embarrassed expression - head turns away slightly",
+      "duration": 2.0,
+      "yaw": 0.15,
+      "pitch": 0.08,
+      "roll": 0.05,
+      "antenna_left": -0.1,
+      "antenna_right": -0.1,
+      "frequency": 0.3
+    },
+    "love": {
+      "description": "Loving/affectionate expression - gentle swaying with happy antennas",
+      "duration": 2.5,
+      "yaw_amplitude": 0.08,
+      "pitch_amplitude": 0.06,
+      "z_amplitude": 0.008,
+      "antenna_left": 0.4,
+      "antenna_right": 0.4,
+      "frequency": 0.8
+    },
+    "bored": {
+      "description": "Bored/uninterested expression - slow side-to-side with droopy antennas",
+      "duration": 3.0,
+      "yaw_amplitude": 0.1,
+      "pitch": 0.05,
+      "antenna_left": -0.15,
+      "antenna_right": -0.15,
+      "frequency": 0.2
     },
     "alert": {
-      "description": "Alert/timer finished - quick movements",
-      "pitch_amplitude_rad": 0.1,
-      "z_amplitude_m": 0.012,
-      "antenna_amplitude_rad": 0.6,
-      "antenna_move_name": "both",
-      "frequency_hz": 1.5
+      "description": "Alert/attentive expression - quick upward movement with perky antennas",
+      "duration": 1.0,
+      "pitch": -0.15,
+      "z": 0.015,
+      "antenna_left": 0.7,
+      "antenna_right": 0.7,
+      "frequency": 2.5
     }
   },
   "settings": {
     "amplitude_scale": 1.0,
-    "transition_duration_s": 0.3
+    "transition_duration_s": 0.3,
+    "default_emotion_duration": 2.0,
+    "default_emotion_frequency": 1.0
   }
 }

reachy_mini_ha_voice/animations/emotion_keywords.json

@@ -0,0 +1,67 @@
+{
+  "description": "Emotion keyword detection for automatic emotion triggering. Maps text patterns to robot emotion names from pollen-robotics/reachy-mini-emotions-library.",
+  "keywords": {
+    "haha": "laughing1",
+    "hehe": "laughing1",
+    "lol": "laughing1",
+    "太棒了": "cheerful1",
+    "太好了": "cheerful1",
+    "好开心": "cheerful1",
+    "真高兴": "cheerful1",
+    "恭喜": "cheerful1",
+    "congratulations": "cheerful1",
+    "awesome": "cheerful1",
+    "amazing": "amazed1",
+    "wonderful": "cheerful1",
+    "fantastic": "enthusiastic1",
+    "love": "loving1",
+    "喜欢": "loving1",
+    "爱": "loving1",
+    "thank": "grateful1",
+    "谢谢": "grateful1",
+    "感谢": "grateful1",
+    "welcome": "welcoming1",
+    "欢迎": "welcoming1",
+    "sure": "helpful1",
+    "of course": "helpful1",
+    "当然": "helpful1",
+    "好的": "helpful1",
+    "没问题": "helpful1",
+    "interesting": "curious1",
+    "有意思": "curious1",
+    "curious": "curious1",
+    "好奇": "curious1",
+    "hmm": "thoughtful1",
+    "嗯": "thoughtful1",
+    "让我想想": "thoughtful1",
+    "let me think": "thoughtful1",
+    "sorry": "sad1",
+    "抱歉": "sad1",
+    "对不起": "sad1",
+    "unfortunately": "sad1",
+    "不幸": "sad1",
+    "oops": "oops1",
+    "糟糕": "oops1",
+    "哎呀": "oops1",
+    "don't know": "uncertain1",
+    "不知道": "uncertain1",
+    "不确定": "uncertain1",
+    "confused": "confused1",
+    "困惑": "confused1",
+    "wow": "surprised1",
+    "哇": "surprised1",
+    "真的吗": "surprised1",
+    "really": "surprised1",
+    "yes": "yes1",
+    "是的": "yes1",
+    "对": "yes1",
+    "no": "no1",
+    "不是": "no1",
+    "不行": "no1"
+  },
+  "settings": {
+    "enabled": true,
+    "case_sensitive": false,
+    "max_emotions_per_response": 1
+  }
+}

reachy_mini_ha_voice/audio_player.py

@@ -21,6 +21,11 @@ if TYPE_CHECKING:
 
 _LOGGER = logging.getLogger(__name__)
 
+# Movement latency to sync head motion with audio playback
+# Audio playback has hardware buffer latency, so we delay head motion to match
+# Same as reachy_mini_conversation_app's HeadWobbler.MOVEMENT_LATENCY_S
+MOVEMENT_LATENCY_S = 0.2  # 200ms latency between audio start and head movement
+
 # Check if aiosendspin is available
 try:
     from aiosendspin.client import SendspinClient, PCMFormat
@@ -463,6 +468,8 @@ class AudioPlayer:
                     self.reachy_mini.media.play_sound(file_path)
 
                     # Playback loop with sway animation
+                    # Apply MOVEMENT_LATENCY_S delay to sync head motion with audio
+                    # (audio playback has hardware buffer latency)
                     start_time = time.time()
                     frame_duration = 0.05  # 50ms per sway frame (HOP_MS)
                     frame_idx = 0
@@ -472,10 +479,14 @@ class AudioPlayer:
                             self.reachy_mini.media.stop_playing()
                             break
 
-                        # Apply sway frame if available
+                        # Apply sway frame if available, with 200ms delay
                         if self._sway_callback and frame_idx < len(sway_frames):
                             elapsed = time.time() - start_time
-                            target_frame = int(elapsed / frame_duration)
+                            # Apply latency: head motion starts MOVEMENT_LATENCY_S after audio
+                            effective_elapsed = max(0, elapsed - MOVEMENT_LATENCY_S)
+                            target_frame = int(effective_elapsed / frame_duration)
+
+                            # Skip frames if falling behind (lag compensation)
                             while frame_idx <= target_frame and frame_idx < len(sway_frames):
                                 self._sway_callback(sway_frames[frame_idx])
                                 frame_idx += 1

reachy_mini_ha_voice/movement_manager.py

@@ -5,7 +5,7 @@ This module provides a centralized control system for robot movements,
 inspired by the reachy_mini_conversation_app architecture.
 
 Key features:
-- Single 10Hz control loop (balanced between responsiveness and stability)
+- Single 100Hz control loop (same as reachy_mini_conversation_app)
 - Command queue pattern (thread-safe external API)
 - Error throttling (prevents log explosion)
 - JSON-driven animation system (conversation state animations)
@@ -18,6 +18,7 @@ Key features:
 
 import logging
 import math
+import random
 import threading
 import time
 from dataclasses import dataclass, field
@@ -57,12 +58,21 @@ TARGET_PERIOD = 1.0 / CONTROL_LOOP_FREQUENCY_HZ
 # Antenna freeze parameters (listening mode)
 ANTENNA_BLEND_DURATION = 0.5  # Seconds to blend back from frozen state
 
+# Idle look-around behavior parameters
+IDLE_LOOK_AROUND_MIN_INTERVAL = 8.0   # Minimum seconds between look-arounds
+IDLE_LOOK_AROUND_MAX_INTERVAL = 20.0  # Maximum seconds between look-arounds
+IDLE_LOOK_AROUND_YAW_RANGE = 25.0     # Maximum yaw angle in degrees
+IDLE_LOOK_AROUND_PITCH_RANGE = 10.0   # Maximum pitch angle in degrees
+IDLE_LOOK_AROUND_DURATION = 1.2       # Duration of look-around action in seconds
+IDLE_INACTIVITY_THRESHOLD = 5.0       # Seconds of inactivity before look-around starts
+
 # State to animation mapping
+# Note: SPEAKING uses idle animation as base, with speech_sway offsets layered on top
 STATE_ANIMATION_MAP = {
     "idle": "idle",
     "listening": "listening",
     "thinking": "thinking",
-    "speaking": "speaking",
+    "speaking": "idle",  # Base animation only; actual motion from speech_sway
 }
 
 
@@ -120,6 +130,10 @@ class MovementState:
     antenna_blend: float = 1.0  # 0=frozen, 1=normal
     antenna_blend_start_time: float = 0.0
 
+    # Idle look-around behavior
+    next_look_around_time: float = 0.0
+    look_around_in_progress: bool = False
+
 
 @dataclass
 class PendingAction:
@@ -137,13 +151,10 @@ class PendingAction:
 
 class MovementManager:
     """
-    Unified movement manager with 10Hz control loop.
+    Unified movement manager with 100Hz control loop.
 
     All external interactions go through the command queue,
     ensuring thread safety and preventing race conditions.
-    
-    Note: Frequency reduced from 100Hz to 10Hz to prevent daemon crashes
-    caused by excessive Zenoh message traffic.
     """
 
     def __init__(self, reachy_mini: Optional["ReachyMini"] = None):
@@ -279,7 +290,7 @@ class MovementManager:
 
     def set_camera_server(self, camera_server) -> None:
         """Set the camera server for face tracking offsets.
-        
+
         Args:
             camera_server: MJPEGCameraServer instance with face tracking
         """
@@ -488,6 +499,9 @@ class MovementManager:
                     self._pending_action.callback()
                 except Exception as e:
                     logger.error("Action callback error: %s", e)
+            # Reset look-around state if this was a look-around action
+            if self._pending_action.name == "look_around":
+                self.state.look_around_in_progress = False
             self._pending_action = None
 
     def _update_animation(self, dt: float) -> None:
@@ -563,6 +577,75 @@ class MovementManager:
             except Exception as e:
                 logger.debug("Error getting face tracking offsets: %s", e)
 
+    def _update_idle_look_around(self) -> None:
+        """Trigger random look-around behavior when idle for a while.
+
+        This adds life-like behavior to the robot by occasionally looking around
+        when not engaged in conversation. Similar to conversation_app's idle behaviors.
+        """
+        # Only trigger when in IDLE state
+        if self.state.robot_state != RobotState.IDLE:
+            # Reset timing when not idle
+            self.state.next_look_around_time = 0.0
+            self.state.look_around_in_progress = False
+            return
+
+        # Check if we have an action in progress
+        if self._pending_action is not None:
+            return
+
+        now = self._now()
+        idle_duration = now - self.state.idle_start_time
+
+        # Only start look-around after sufficient inactivity
+        if idle_duration < IDLE_INACTIVITY_THRESHOLD:
+            return
+
+        # Schedule next look-around if not scheduled
+        if self.state.next_look_around_time == 0.0:
+            interval = random.uniform(
+                IDLE_LOOK_AROUND_MIN_INTERVAL,
+                IDLE_LOOK_AROUND_MAX_INTERVAL
+            )
+            self.state.next_look_around_time = now + interval
+            logger.debug("Scheduled next look-around in %.1fs", interval)
+            return
+
+        # Check if it's time for look-around
+        if now >= self.state.next_look_around_time and not self.state.look_around_in_progress:
+            # Generate random look direction
+            target_yaw = random.uniform(
+                -IDLE_LOOK_AROUND_YAW_RANGE,
+                IDLE_LOOK_AROUND_YAW_RANGE
+            )
+            target_pitch = random.uniform(
+                -IDLE_LOOK_AROUND_PITCH_RANGE,
+                IDLE_LOOK_AROUND_PITCH_RANGE
+            )
+
+            # Create look-around action
+            action = PendingAction(
+                name="look_around",
+                target_yaw=math.radians(target_yaw),
+                target_pitch=math.radians(target_pitch),
+                duration=IDLE_LOOK_AROUND_DURATION,
+            )
+
+            # Start the action
+            self._start_action(action)
+            self.state.look_around_in_progress = True
+
+            # Schedule return to center and next look-around
+            interval = random.uniform(
+                IDLE_LOOK_AROUND_MIN_INTERVAL,
+                IDLE_LOOK_AROUND_MAX_INTERVAL
+            )
+            self.state.next_look_around_time = now + IDLE_LOOK_AROUND_DURATION * 2 + interval
+
+            logger.debug("Starting look-around: yaw=%.1f°, pitch=%.1f°",
+                        target_yaw, target_pitch)
+
+
     def _compose_final_pose(self) -> Tuple[np.ndarray, Tuple[float, float], float]:
         """Compose final pose from all sources using SDK's compose_world_offset.
         
@@ -633,8 +716,10 @@ class MovementManager:
             final_head[:3, 3] = primary_head[:3, 3] + secondary_head[:3, 3]
 
         # Antenna pose with freeze blending
-        target_antenna_left = self.state.target_antenna_left + self.state.anim_antenna_left
-        target_antenna_right = self.state.target_antenna_right + self.state.anim_antenna_right
+        target_antenna_left = (self.state.target_antenna_left +
+                               self.state.anim_antenna_left)
+        target_antenna_right = (self.state.target_antenna_right +
+                                self.state.anim_antenna_right)
 
         # Apply antenna freeze blending (listening mode)
         blend = self.state.antenna_blend
@@ -757,7 +842,7 @@ class MovementManager:
     # =========================================================================
 
     def _control_loop(self) -> None:
-        """Main 10Hz control loop."""
+        """Main 100Hz control loop."""
         logger.info("Movement manager control loop started (%.0f Hz)", CONTROL_LOOP_FREQUENCY_HZ)
 
         last_time = self._now()
@@ -779,14 +864,17 @@ class MovementManager:
 
                 # 4. Update antenna blend (listening mode freeze/unfreeze)
                 self._update_antenna_blend(dt)
-                
+
                 # 5. Update face tracking offsets from camera server
                 self._update_face_tracking()
 
-                # 6. Compose final pose (returns head_pose matrix, antennas tuple, body_yaw)
+                # 6. Update idle look-around behavior
+                self._update_idle_look_around()
+
+                # 7. Compose final pose (returns head_pose matrix, antennas tuple, body_yaw)
                 head_pose, antennas, body_yaw = self._compose_final_pose()
 
-                # 7. Send to robot (single control point!)
+                # 8. Send to robot (single control point!)
                 self._issue_control_command(head_pose, antennas, body_yaw)
 
             except Exception as e:

reachy_mini_ha_voice/satellite.py

@@ -142,6 +142,11 @@ class VoiceSatelliteProtocol(APIServer):
             for entity in self.state.entities:
                 entity.server = self
 
+        # Load emotion keywords from JSON file for auto-triggering
+        self._emotion_keywords: Dict[str, str] = {}
+        self._emotion_detection_enabled = True
+        self._load_emotion_keywords()
+
     def handle_voice_event(
         self, event_type: VoiceAssistantEventType, data: Dict[str, str]
     ) -> None:
@@ -179,6 +184,12 @@ class VoiceSatelliteProtocol(APIServer):
             _LOGGER.debug("TTS_START event received, triggering speaking animation")
             self._reachy_on_speaking()
 
+            # Auto-trigger emotion based on response text
+            # TTS_START may contain the text to be spoken
+            tts_text = data.get("tts_output") or data.get("text") or ""
+            if tts_text:
+                self._detect_and_play_emotion(tts_text)
+
         elif event_type == VoiceAssistantEventType.VOICE_ASSISTANT_TTS_END:
             self._tts_url = data.get("url")
             self.play_tts()
@@ -748,6 +759,66 @@ class VoiceSatelliteProtocol(APIServer):
         except Exception as e:
             _LOGGER.error("Reachy Mini motion error: %s", e)
 
+    def _load_emotion_keywords(self) -> None:
+        """Load emotion keywords from JSON configuration file.
+
+        The file is located at animations/emotion_keywords.json and contains
+        keyword-to-emotion mappings for automatic emotion detection.
+        """
+        import json
+        from pathlib import Path
+
+        keywords_file = Path(__file__).parent / "animations" / "emotion_keywords.json"
+
+        if not keywords_file.exists():
+            _LOGGER.warning("Emotion keywords file not found: %s", keywords_file)
+            return
+
+        try:
+            with open(keywords_file, "r", encoding="utf-8") as f:
+                data = json.load(f)
+
+            self._emotion_keywords = data.get("keywords", {})
+            settings = data.get("settings", {})
+            self._emotion_detection_enabled = settings.get("enabled", True)
+
+            _LOGGER.info(
+                "Loaded %d emotion keywords (enabled=%s)",
+                len(self._emotion_keywords),
+                self._emotion_detection_enabled
+            )
+        except Exception as e:
+            _LOGGER.error("Failed to load emotion keywords: %s", e)
+
+    def _detect_and_play_emotion(self, text: str) -> None:
+        """Detect emotion from text and trigger corresponding robot animation.
+
+        This provides automatic emotion expression based on the LLM response content.
+        Keywords are matched case-insensitively against the text.
+
+        Args:
+            text: The text to analyze for emotional content
+        """
+        if not text or not self._emotion_detection_enabled:
+            return
+
+        if not self._emotion_keywords:
+            return
+
+        text_lower = text.lower()
+
+        # Check each keyword pattern
+        for keyword, emotion_name in self._emotion_keywords.items():
+            if keyword.lower() in text_lower:
+                _LOGGER.info(
+                    "Auto-detected emotion '%s' from keyword '%s' in response",
+                    emotion_name, keyword
+                )
+                self._play_emotion(emotion_name)
+                return  # Only trigger one emotion per response
+
+        _LOGGER.debug("No emotion keywords detected in response text")
+
     def _play_emotion(self, emotion_name: str) -> None:
         """Play an emotion/expression from the emotions library.