fix: TalkingHead Ctrl+drag not working on Linux

- Add pynput for global key state detection on Linux
- Qt modifiers only work when app has focus, but overlay is click-through
- pynput listener runs in background thread tracking Ctrl/Alt key state
- Also fix Qt plugin path conflict with opencv-python

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: Eve

apps/dashboard/TalkinHead/ivy_overlay.py

@@ -16,24 +16,58 @@
 import sys
 import os
 import json
-import cv2
-import numpy as np
 
+# IMPORTANT: Import PyQt5 BEFORE cv2 to avoid Qt plugin conflicts on Linux
+# cv2 bundles its own Qt which can override the system Qt plugin path
 from PyQt5.QtWidgets import QApplication, QWidget, QLabel
 from PyQt5.QtCore import Qt, QTimer, QPoint, pyqtSignal
 from PyQt5.QtGui import QImage, QPixmap, QCursor, QFont
 
+# Now safe to import cv2 (PyQt5 already claimed the Qt plugins)
+import cv2
+import numpy as np
+
 # Pygame for reliable audio playback
 import pygame
 pygame.mixer.init()
 
-# Win32 for global key state detection (Windows)
+# Platform-specific key state detection
 import ctypes
-user32 = ctypes.windll.user32
 VK_CONTROL = 0x11
 VK_MENU = 0x12  # Alt key
 VK_Q = 0x51  # Q key
 
+# Windows uses user32.dll, Linux/macOS use pynput for global key detection
+if sys.platform == "win32":
+    user32 = ctypes.windll.user32
+    pynput_keyboard = None
+else:
+    user32 = None
+    # Linux/macOS: use pynput for global key state detection
+    # (Qt modifiers only work when app has focus, but our window is click-through)
+    try:
+        from pynput import keyboard as pynput_keyboard
+
+        # Global key state tracking
+        _keys_pressed = set()
+
+        def _on_press(key):
+            _keys_pressed.add(key)
+
+        def _on_release(key):
+            _keys_pressed.discard(key)
+
+        # Start global keyboard listener in background thread
+        _keyboard_listener = pynput_keyboard.Listener(on_press=_on_press, on_release=_on_release)
+        _keyboard_listener.daemon = True
+        _keyboard_listener.start()
+        print("pynput keyboard listener started for global key detection")
+    except ImportError:
+        print("WARNING: pynput not installed. Ctrl+drag may not work on Linux.")
+        print("Install with: pip install pynput")
+        pynput_keyboard = None
+        _keys_pressed = set()
+
 # Script directory for relative paths
 SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
 CONFIG_FILE = os.path.join(SCRIPT_DIR, "config.json")
@@ -58,6 +92,7 @@ def __init__(self, parent=None):
 
         # State tracking
         self.running = True
+        self._q_pressed = False  # For Linux/macOS Q key detection
         self.idle_frame_idx = 0
         self.phrase_frame_idx = 0
         self.is_playing_phrase = False
@@ -569,9 +604,34 @@ def _update_tooltip_position(self):
 
     def _check_modifier_keys(self):
         """Check for Ctrl (drag), Alt (resize), Ctrl+Q (quit), and mouse hover."""
-        ctrl_held = (user32.GetAsyncKeyState(VK_CONTROL) & 0x8000) != 0
-        alt_held = (user32.GetAsyncKeyState(VK_MENU) & 0x8000) != 0
-        q_held = (user32.GetAsyncKeyState(VK_Q) & 0x8000) != 0
+        if user32:
+            # Windows: use GetAsyncKeyState for global key state
+            ctrl_held = (user32.GetAsyncKeyState(VK_CONTROL) & 0x8000) != 0
+            alt_held = (user32.GetAsyncKeyState(VK_MENU) & 0x8000) != 0
+            q_held = (user32.GetAsyncKeyState(VK_Q) & 0x8000) != 0
+        elif pynput_keyboard:
+            # Linux/macOS: use pynput for global key state detection
+            # Check if Ctrl, Alt, or Q keys are in the pressed set
+            ctrl_held = any(
+                key in _keys_pressed
+                for key in [pynput_keyboard.Key.ctrl, pynput_keyboard.Key.ctrl_l, pynput_keyboard.Key.ctrl_r]
+            )
+            alt_held = any(
+                key in _keys_pressed
+                for key in [pynput_keyboard.Key.alt, pynput_keyboard.Key.alt_l, pynput_keyboard.Key.alt_r, pynput_keyboard.Key.alt_gr]
+            )
+            # Check for Q key (could be KeyCode or character)
+            q_held = any(
+                (hasattr(key, 'char') and key.char == 'q') or
+                (hasattr(key, 'vk') and key.vk == 81)  # 81 = Q
+                for key in _keys_pressed
+            )
+        else:
+            # Fallback: use Qt keyboard modifiers (only works when app has focus)
+            modifiers = QApplication.keyboardModifiers()
+            ctrl_held = bool(modifiers & Qt.ControlModifier)
+            alt_held = bool(modifiers & Qt.AltModifier)
+            q_held = getattr(self, '_q_pressed', False)
 
         # Check mouse hover for tooltip
         mouse_pos = QCursor.pos()
@@ -691,6 +751,18 @@ def mouseReleaseEvent(self, event):
             self.setCursor(Qt.OpenHandCursor)
             self.save_config()
 
+    def keyPressEvent(self, event):
+        """Track key presses for Linux/macOS (Q key detection)."""
+        if event.key() == Qt.Key_Q:
+            self._q_pressed = True
+        super().keyPressEvent(event)
+
+    def keyReleaseEvent(self, event):
+        """Track key releases for Linux/macOS."""
+        if event.key() == Qt.Key_Q:
+            self._q_pressed = False
+        super().keyReleaseEvent(event)
+
     def save_config(self):
         """Save position and size to config.json."""
         try:

apps/dashboard/TalkinHead/main.py

@@ -14,6 +14,15 @@
 
 import os
 import sys
+
+# Fix Qt plugin path conflict with opencv-python on Linux
+# Only needed for non-headless opencv which bundles Qt
+# When using venv with opencv-python-headless, skip this (no Qt conflict)
+if sys.platform != "win32" and sys.prefix == sys.base_prefix:
+    # Only override for system Python (not venv) - system cv2 may have Qt conflict
+    os.environ["QT_QPA_PLATFORM_PLUGIN_PATH"] = "/usr/lib/x86_64-linux-gnu/qt5/plugins"
+    os.environ.pop("QT_PLUGIN_PATH", None)
+
 import signal
 import atexit
 from pathlib import Path

apps/dashboard/TalkinHead/requirements.txt

@@ -0,0 +1,7 @@
+# TalkinHead dependencies
+# Note: numpy<2 required due to OpenCV compatibility on older systems
+numpy<2
+opencv-python-headless
+pygame
+PyQt5
+pynput  # For global key state detection on Linux

apps/dashboard/TalkinHead/run-talkinhead.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# TalkinHead Launcher for Linux
+# Uses venv to avoid numpy compatibility issues with system packages
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VENV_DIR="$SCRIPT_DIR/.venv"
+
+cd "$SCRIPT_DIR"
+
+# Create venv if it doesn't exist
+if [ ! -d "$VENV_DIR" ]; then
+    echo "Creating virtual environment..."
+    python3 -m venv "$VENV_DIR"
+    "$VENV_DIR/bin/pip" install --upgrade pip
+    "$VENV_DIR/bin/pip" install "numpy<2" opencv-python-headless pygame PyQt5
+fi
+
+# Run with venv python
+exec "$VENV_DIR/bin/python" main.py "$@"