✨ feat: feat(accessibility): add Kokoro TTS direct speech for livecd wizard

Replace ORCA/speech-dispatcher dependency with direct Kokoro TTS
(koko CLI) for accessibility in the livecd setup wizard.

Changes:
- accessibility.py: Rewrite speak() to use koko directly (generate WAV
  + paplay) instead of spd-say. Add generation counter for cancellation,
  background thread playback, and --speed 1.5 for faster speech.
  Decouple announce() from speak() to prevent double-speaking.
  Add set_speak_voice() to update global voice/language settings.
- app_window.py: Super+Alt+S activates accessibility with Kokoro TTS.
  Use keycode 39 with CAPTURE phase for reliable shortcut detection.
- language_view.py: Always update global speak voice on language
  selection (even when voice preview is off). Add --speed 1.5 to
  preview generation.
- keyboard_view.py: Add selected-children-changed signal handler.
  Fix race condition between _on_map announce and _select_first_item
  using _suppress_speak guard flag. Read title on screen entry, speak
  individual items on navigation.
- base_view.py: Same race condition fix with _suppress_speak flag.
  Unified _select_first_and_announce method replaces separate
  _select_first_item + _on_map logic.
- theme_view.py: Add speak() for JamesDSP/contrast toggle state
  changes. Announce toggle state on screen entry. Support both
  click and keyboard toggle with voice feedback.

Author: talesam

biglinux-livecd/usr/share/biglinux/livecd/accessibility.py

@@ -1,6 +1,9 @@
-"""Accessibility utilities for ORCA screen reader support (AT-SPI2)."""
+"""Accessibility utilities — speech via Kokoro TTS (koko CLI)."""
 
+import os
 import subprocess
+import tempfile
+import threading
 
 import gi
 
@@ -12,12 +15,134 @@
 
 _HAS_ANNOUNCE = hasattr(Gtk.Accessible, "announce")
 
+# ── Kokoro TTS paths ────────────────────────────────────────
+_KOKO_BIN = "/usr/bin/koko"
+_KOKO_MODEL = "/usr/share/biglinux-kokoro-tts/model/model.onnx"
+_KOKO_VOICES = "/usr/share/biglinux-kokoro-tts/voices/voices.bin"
+
+# ── Global accessibility state ──────────────────────────────
+_accessibility_enabled = False
+_speak_gen = 0
+_speak_lock = threading.Lock()
+_play_process = None
+
+# Voice configuration set by the language screen selection
+_current_voice = "af_heart"
+_current_lang_code = "en-us"
+
+
+def is_accessibility_enabled() -> bool:
+    return _accessibility_enabled
+
+
+def set_accessibility_enabled(enabled: bool) -> None:
+    global _accessibility_enabled
+    _accessibility_enabled = enabled
+    logger.info(f"Accessibility {'enabled' if enabled else 'disabled'}")
+
+
+def set_speak_voice(voice: str, lang_code: str) -> None:
+    """Set the voice and language for speak() calls (called when user selects a language)."""
+    global _current_voice, _current_lang_code
+    _current_voice = voice
+    _current_lang_code = lang_code
+
+
+def speak(text: str) -> None:
+    """Speak text using koko directly. Non-blocking, cancels previous speech."""
+    if not _accessibility_enabled or not text:
+        return
+    logger.info(
+        f"speak() called: '{text}' voice={_current_voice} lang={_current_lang_code}"
+    )
+    stop_speaking()
+    global _speak_gen
+    with _speak_lock:
+        _speak_gen += 1
+        gen = _speak_gen
+
+    def _do_speak():
+        global _play_process
+        tmpwav = None
+        try:
+            fd, tmpwav = tempfile.mkstemp(prefix="a11y-", suffix=".wav")
+            os.close(fd)
+            cmd = [
+                _KOKO_BIN,
+                "-m",
+                _KOKO_MODEL,
+                "-d",
+                _KOKO_VOICES,
+                "-l",
+                _current_lang_code,
+                "-s",
+                _current_voice,
+                "--force-style",
+                "true",
+                "--speed",
+                "1.5",
+                "text",
+                text,
+                "-o",
+                tmpwav,
+            ]
+            logger.info(f"speak() running koko: {' '.join(cmd)}")
+            proc = subprocess.run(
+                cmd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                timeout=15,
+            )
+            if proc.returncode != 0:
+                logger.info(
+                    f"speak() koko failed rc={proc.returncode} stderr={proc.stderr.decode()[:200]}"
+                )
+                return
+            with _speak_lock:
+                if gen != _speak_gen:
+                    logger.info("speak() discarded (gen changed)")
+                    return
+            fsize = os.path.getsize(tmpwav) if os.path.isfile(tmpwav) else 0
+            logger.info(f"speak() WAV generated: {tmpwav} size={fsize}")
+            if fsize > 0:
+                play = subprocess.Popen(
+                    ["paplay", tmpwav],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.PIPE,
+                )
+                with _speak_lock:
+                    _play_process = play
+                play.wait(timeout=15)
+                if play.returncode != 0:
+                    logger.info(
+                        f"speak() paplay failed rc={play.returncode} stderr={play.stderr.read().decode()[:200]}"
+                    )
+                else:
+                    logger.info("speak() playback complete")
+        except Exception as e:
+            logger.info(f"speak() exception: {e}")
+        finally:
+            if tmpwav and os.path.isfile(tmpwav):
+                try:
+                    os.unlink(tmpwav)
+                except OSError:
+                    pass
+
+    threading.Thread(target=_do_speak, daemon=True).start()
+
+
+def stop_speaking() -> None:
+    """Cancel any ongoing speech playback."""
+    global _speak_gen, _play_process
+    with _speak_lock:
+        _speak_gen += 1
+        if _play_process and _play_process.poll() is None:
+            _play_process.terminate()
+        _play_process = None
+
 
 def announce(widget: Gtk.Accessible, message: str, assertive: bool = False) -> None:
-    """
-    Announce a message to screen readers (ORCA) via AT-SPI2.
-    Uses Gtk.Accessible.announce() on GTK 4.14+.
-    """
+    """Announce a message to screen readers via AT-SPI2 only (no TTS speak)."""
     if not message or not widget:
         return
     if _HAS_ANNOUNCE:
@@ -30,34 +155,6 @@ def announce(widget: Gtk.Accessible, message: str, assertive: bool = False) -> N
             widget.announce(message, priority)
         except Exception as e:
             logger.debug(f"announce() failed: {e}")
-    else:
-        logger.debug(f"a11y: {message}")
-
-
-def start_orca() -> bool:
-    """Start ORCA screen reader if not already running."""
-    try:
-        result = subprocess.run(
-            ["pgrep", "-x", "orca"],
-            capture_output=True,
-            timeout=5,
-        )
-        if result.returncode == 0:
-            logger.info("ORCA is already running")
-            return True
-        subprocess.Popen(
-            ["orca"],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-        )
-        logger.info("Started ORCA screen reader")
-        return True
-    except FileNotFoundError:
-        logger.warning("ORCA not found on this system")
-        return False
-    except subprocess.TimeoutExpired:
-        logger.warning("Timeout checking for ORCA process")
-        return False
 
 
 def ensure_orca_disabled() -> None:
@@ -73,4 +170,15 @@ def ensure_orca_disabled() -> None:
         stdout=subprocess.DEVNULL,
         stderr=subprocess.DEVNULL,
     )
+    autostart_dir = os.path.expanduser("~/.config/autostart")
+    override_file = os.path.join(autostart_dir, "orca-autostart.desktop")
+    if not os.path.isfile(override_file):
+        try:
+            os.makedirs(autostart_dir, exist_ok=True)
+            with open(override_file, "w") as f:
+                f.write(
+                    "[Desktop Entry]\nType=Application\nName=Orca Screen Reader\nHidden=true\n"
+                )
+        except OSError:
+            pass
     logger.info("Ensured ORCA is disabled at startup")

biglinux-livecd/usr/share/biglinux/livecd/ui/app_window.py

@@ -11,7 +11,13 @@
 from ui.keyboard_view import KeyboardView
 from ui.desktop_view import DesktopView
 from ui.theme_view import ThemeView
-from accessibility import announce, start_orca, ensure_orca_disabled
+from accessibility import (
+    announce,
+    ensure_orca_disabled,
+    set_accessibility_enabled,
+    speak,
+    set_speak_voice,
+)
 from logging_config import get_logger
 import os
 
@@ -120,8 +126,10 @@ def __init__(self, system_service: SystemService, **kwargs):
         self.set_content(self._build_ui())
         self._update_header_state()
 
-        # Create and add a Gtk.EventControllerKey for global key events
+        # Create and add a Gtk.EventControllerKey for global key events (CAPTURE phase
+        # so it runs before child widgets like the search entry consume keys)
         key_controller = Gtk.EventControllerKey.new()
+        key_controller.set_propagation_phase(Gtk.PropagationPhase.CAPTURE)
         key_controller.connect("key-pressed", self._on_key_press_event)
         self.add_controller(key_controller)
 
@@ -562,13 +570,18 @@ def _on_simple_theme_selected(self, view, theme):
             logger.error(f"ERROR in _on_simple_theme_selected: {e}", exc_info=True)
 
     def _on_key_press_event(self, controller, keyval, keycode, state):
-        # Super+Alt+S: start ORCA screen reader (standard GNOME shortcut)
+        # Super+Alt+S: enable accessibility (speech via speech-dispatcher + Kokoro)
+        # Use keycode 39 (physical 'S' key) so it works on any keyboard layout
         if (
-            keyval == Gdk.KEY_s
+            keycode == 39
             and state & Gdk.ModifierType.SUPER_MASK
             and state & Gdk.ModifierType.ALT_MASK
         ):
-            start_orca()
+            set_accessibility_enabled(True)
+            lang_view = self.stack.get_child_by_name("language")
+            if isinstance(lang_view, LanguageView):
+                lang_view.enable_voice_preview()
+            speak(_("Accessibility enabled. Use arrow keys to navigate."))
             return True
         current_view = self.stack.get_visible_child()
         if isinstance(current_view, LanguageView):

biglinux-livecd/usr/share/biglinux/livecd/ui/base_view.py

@@ -9,7 +9,7 @@
 from gi.repository import Adw, Gdk, GLib, GObject, Gtk
 from services import SystemService
 from translations import _
-from accessibility import announce
+from accessibility import announce, speak, is_accessibility_enabled
 from logging_config import get_logger
 
 logger = get_logger()
@@ -37,6 +37,9 @@ def _on_map(self, *args):
             self.load_items()
             self.items_loaded = True
         self.grab_focus()
+        # Suppress selection-changed speak during initial selection
+        self._suppress_speak = True
+        GLib.idle_add(self._select_first_and_announce)
 
     def _build_ui(self):
         scrolled_window = Gtk.ScrolledWindow(
@@ -87,6 +90,7 @@ def _build_ui(self):
 
         self.flow_box.connect("child-activated", self._on_child_activated)
         self.flow_box.connect("activate-cursor-child", self._on_activate_cursor_child)
+        self.flow_box.connect("selected-children-changed", self._on_selection_changed)
 
         key_controller = Gtk.EventControllerKey.new()
         key_controller.connect("key-pressed", self._on_key_pressed)
@@ -136,8 +140,7 @@ def load_items(self):
 
             self.flow_box.append(flow_child)
 
-        if items:
-            GLib.idle_add(self._select_first_item)
+        # Selection and announce are done in _select_first_and_announce via _on_map
 
     def grab_focus(self):
         self.flow_box.grab_focus()
@@ -171,6 +174,29 @@ def _on_flow_leave(self, controller, *args):
     def _on_item_enter(self, controller, x, y, flow_child):
         self.flow_box.select_child(flow_child)
 
+    def _on_selection_changed(self, flow_box):
+        """Speak the selected item name when selection changes (mouse or keyboard)."""
+        if getattr(self, "_suppress_speak", False):
+            return
+        selected = flow_box.get_selected_children()
+        if selected and is_accessibility_enabled():
+            child = selected[0]
+            if hasattr(child, "item_data"):
+                speak(child.item_data.name)
+
+    def _select_first_and_announce(self):
+        """Select first item and announce page title (without race condition)."""
+        first_child = self.flow_box.get_first_child()
+        if first_child:
+            self.flow_box.select_child(first_child)
+            self.grab_focus()
+        self._suppress_speak = False
+        if is_accessibility_enabled():
+            text = self.get_title() or ""
+            if text:
+                speak(text)
+        return GLib.SOURCE_REMOVE
+
     def _on_activate_cursor_child(self, flow_box):
         selected = flow_box.get_selected_children()
         if selected:

biglinux-livecd/usr/share/biglinux/livecd/ui/keyboard_view.py

@@ -6,7 +6,7 @@
 gi.require_version("Adw", "1")
 from gi.repository import Gtk, Adw, GObject, GLib, Gdk
 from translations import _
-from accessibility import announce
+from accessibility import announce, speak, is_accessibility_enabled
 import os
 
 ASSETS_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "assets"))
@@ -72,6 +72,7 @@ def _build_ui(self):
         # Connect to FlowBox-level signals
         self.flow_box.connect("child-activated", self._on_child_activated)
         self.flow_box.connect("activate-cursor-child", self._on_activate_cursor_child)
+        self.flow_box.connect("selected-children-changed", self._on_selection_changed)
 
         # Add key controller for Enter key handling
         key_controller = Gtk.EventControllerKey.new()
@@ -127,7 +128,7 @@ def load_layouts(self):
             child = self._create_layout_child(name, layout_id)
             self.flow_box.append(child)
 
-        GLib.idle_add(self._select_first_item)
+        # Selection and announce are handled by _select_first_and_announce via _on_map
 
     def _create_layout_child(self, name, layout_id):
         """Create a FlowBoxChild with a keyboard layout card."""
@@ -204,13 +205,41 @@ def _on_item_enter(self, controller, x, y, child):
         """Select the item when the mouse pointer enters it."""
         self.flow_box.select_child(child)
 
+    def _on_selection_changed(self, flow_box):
+        """Speak the selected layout name when selection changes (mouse or keyboard)."""
+        if getattr(self, "_suppress_speak", False):
+            return
+        selected = flow_box.get_selected_children()
+        if selected and is_accessibility_enabled():
+            child = selected[0]
+            if hasattr(child, "layout_data"):
+                speak(child.layout_data["name"])
+
     def _on_flow_leave(self, controller, *args):
         """Clear selection when the mouse pointer leaves the flow box."""
         self.flow_box.unselect_all()
 
     def _on_map(self, *args):
+        from logging_config import get_logger
+
+        logger = get_logger()
+        logger.info(
+            f"KeyboardView._on_map called, accessibility={is_accessibility_enabled()}"
+        )
         self.grab_focus()
-        GLib.idle_add(self._select_first_item)
+        # Suppress selection-changed speak during initial selection
+        self._suppress_speak = True
+        GLib.idle_add(self._select_first_and_announce)
+
+    def _select_first_and_announce(self):
+        """Select first item and announce page title (without race condition)."""
+        child = self.flow_box.get_first_child()
+        if child:
+            self.flow_box.select_child(child)
+        self._suppress_speak = False
+        if is_accessibility_enabled():
+            speak(_("Choose Your Keyboard Layout"))
+        return GLib.SOURCE_REMOVE
 
     def update_primary_layout(self, new_layout):
         self.primary_layout = new_layout