python-voiceio 0.2.0__py3-none-any.whl

voiceio/typers/base.py

@@ -0,0 +1,44 @@
+"""Base protocol and types for text injection backends."""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from voiceio.backends import ProbeResult
+
+__all__ = ["ProbeResult", "TyperBackend", "StreamingTyper"]
+
+
+@runtime_checkable
+class TyperBackend(Protocol):
+    """Protocol for text injection backends."""
+
+    name: str
+
+    def probe(self) -> ProbeResult:
+        """Check if this backend can work on the current system."""
+        ...
+
+    def type_text(self, text: str) -> None:
+        """Type text at the current cursor position."""
+        ...
+
+    def delete_chars(self, n: int) -> None:
+        """Delete n characters before cursor."""
+        ...
+
+
+@runtime_checkable
+class StreamingTyper(TyperBackend, Protocol):
+    """Extended protocol for backends that support preedit-based streaming."""
+
+    def update_preedit(self, text: str) -> None:
+        """Show text as preedit preview (can be freely replaced)."""
+        ...
+
+    def commit_text(self, text: str) -> None:
+        """Clear preedit and commit final text."""
+        ...
+
+    def clear_preedit(self) -> None:
+        """Clear preedit without committing."""
+        ...

voiceio/typers/chain.py

@@ -0,0 +1,79 @@
+"""Fallback chain for typer backends."""
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from voiceio.backends import ProbeResult
+from voiceio.typers.base import TyperBackend
+
+if TYPE_CHECKING:
+    from voiceio.platform import Platform
+
+log = logging.getLogger(__name__)
+
+# Preference order: (display_server, desktop) -> backend list
+_CHAINS: dict[tuple[str, str], list[str]] = {
+    ("x11", "*"):               ["ibus", "xdotool", "clipboard"],
+    ("wayland", "gnome"):       ["ibus", "ydotool", "clipboard"],
+    ("wayland", "kde"):         ["ibus", "ydotool", "clipboard"],
+    ("wayland", "sway"):        ["ibus", "wtype", "ydotool", "clipboard"],
+    ("wayland", "hyprland"):    ["ibus", "wtype", "ydotool", "clipboard"],
+    ("wayland", "*"):           ["ibus", "ydotool", "wtype", "clipboard"],
+    ("quartz", "*"):            ["pynput", "clipboard"],
+}
+
+
+def _get_chain(platform: Platform) -> list[str]:
+    """Get the preference chain for this platform."""
+    key = (platform.display_server, platform.desktop)
+    if key in _CHAINS:
+        return _CHAINS[key]
+    key = (platform.display_server, "*")
+    if key in _CHAINS:
+        return _CHAINS[key]
+    return ["clipboard"]
+
+
+def resolve(platform: Platform, override: str | None = None, **kwargs) -> list[tuple[str, TyperBackend | None, ProbeResult]]:
+    """Probe backends in preference order."""
+    from voiceio.typers import create_typer_backend
+
+    if override and override != "auto":
+        backend = create_typer_backend(override, platform, **kwargs)
+        result = backend.probe()
+        return [(override, backend, result)]
+
+    chain = _get_chain(platform)
+    results = []
+    for name in chain:
+        try:
+            backend = create_typer_backend(name, platform, **kwargs)
+            result = backend.probe()
+            results.append((name, backend, result))
+        except Exception as e:
+            log.debug("Failed to create typer '%s': %s", name, e)
+            results.append((name, None, ProbeResult(ok=False, reason=str(e))))
+
+    return results
+
+
+def select(platform: Platform, override: str | None = None, **kwargs) -> TyperBackend:
+    """Select the first working typer backend.
+
+    Raises RuntimeError if none work.
+    """
+    results = resolve(platform, override, **kwargs)
+
+    for name, backend, probe in results:
+        if probe.ok and backend is not None:
+            log.info("Selected typer backend: %s", name)
+            return backend
+        log.debug("Typer backend '%s' unavailable: %s", name, probe.reason)
+
+    reasons = [f"  {name}: {probe.reason}" for name, _, probe in results if not probe.ok]
+    hints = [probe.fix_hint for _, _, probe in results if probe.fix_hint]
+    msg = "No working typer backend found:\n" + "\n".join(reasons)
+    if hints:
+        msg += "\n\nTo fix:\n" + "\n".join(f"  - {h}" for h in hints)
+    raise RuntimeError(msg)

voiceio/typers/clipboard.py

@@ -0,0 +1,110 @@
+"""Clipboard-based text injection, the universal fallback."""
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+import sys
+
+from voiceio.backends import ProbeResult
+
+log = logging.getLogger(__name__)
+
+
+class ClipboardTyper:
+    """Type text by copying to clipboard and simulating Ctrl+V / Cmd+V."""
+
+    name = "clipboard"
+
+    def __init__(self, platform=None):
+        self._copy_cmd: list[str] | None = None
+        self._paste_tool: list[str] | None = None
+        self._delete_tool: list[str] | None = None
+        self._tools_resolved = False
+
+    def _resolve_tools(self) -> None:
+        """Detect available tools once and cache."""
+        if self._tools_resolved:
+            return
+        self._tools_resolved = True
+
+        if sys.platform == "darwin":
+            if shutil.which("pbcopy"):
+                self._copy_cmd = ["pbcopy"]
+            return
+
+        session = os.environ.get("XDG_SESSION_TYPE", "")
+        if session == "wayland" or os.environ.get("WAYLAND_DISPLAY"):
+            if shutil.which("wl-copy"):
+                self._copy_cmd = ["wl-copy", "--"]
+                if shutil.which("ydotool"):
+                    self._paste_tool = ["ydotool", "key", "29:1", "47:1", "47:0", "29:0"]
+                    self._delete_tool = ["ydotool"]
+                elif shutil.which("wtype"):
+                    self._paste_tool = ["wtype", "-M", "ctrl", "-k", "v", "-m", "ctrl"]
+                    self._delete_tool = ["wtype"]
+        else:
+            if shutil.which("xclip") and shutil.which("xdotool"):
+                self._copy_cmd = ["xclip", "-selection", "clipboard"]
+                self._paste_tool = ["xdotool", "key", "--clearmodifiers", "ctrl+v"]
+                self._delete_tool = ["xdotool"]
+
+    def probe(self) -> ProbeResult:
+        self._resolve_tools()
+        if self._copy_cmd is None or (sys.platform != "darwin" and self._paste_tool is None):
+            return ProbeResult(
+                ok=False,
+                reason="No clipboard tool found",
+                fix_hint="Install xclip (X11), wl-copy (Wayland), or pbcopy (macOS).",
+            )
+        return ProbeResult(ok=True)
+
+    def type_text(self, text: str) -> None:
+        if not text:
+            return
+        self._resolve_tools()
+
+        if sys.platform == "darwin":
+            subprocess.run(["pbcopy"], input=text.encode(), check=True, capture_output=True)
+            subprocess.run(
+                ["osascript", "-e", 'tell application "System Events" to keystroke "v" using command down'],
+                check=True, capture_output=True,
+            )
+            return
+
+        if self._copy_cmd is None:
+            raise RuntimeError("No clipboard tools available")
+
+        subprocess.run(self._copy_cmd, input=text.encode(), check=True, capture_output=True)
+        if self._paste_tool:
+            subprocess.run(self._paste_tool, check=True, capture_output=True)
+
+    def delete_chars(self, n: int) -> None:
+        if n <= 0:
+            return
+        self._resolve_tools()
+
+        if self._delete_tool and self._delete_tool[0] == "xdotool":
+            subprocess.run(
+                ["xdotool", "key", "--clearmodifiers", "--delay", "12"] + ["BackSpace"] * n,
+                check=True, capture_output=True,
+            )
+        elif self._delete_tool and self._delete_tool[0] == "ydotool":
+            # Batch all backspaces into one subprocess call
+            keys = []
+            for _ in range(n):
+                keys.extend(["14:1", "14:0"])
+            subprocess.run(["ydotool", "key"] + keys, check=True, capture_output=True)
+        elif self._delete_tool and self._delete_tool[0] == "wtype":
+            # Batch: -k BackSpace -k BackSpace ...
+            args = ["wtype"]
+            for _ in range(n):
+                args.extend(["-k", "BackSpace"])
+            subprocess.run(args, check=True, capture_output=True)
+        elif sys.platform == "darwin":
+            for _ in range(n):
+                subprocess.run(
+                    ["osascript", "-e", 'tell application "System Events" to key code 51'],
+                    check=True, capture_output=True,
+                )

voiceio/typers/ibus.py

@@ -0,0 +1,389 @@
+"""IBus text injection backend: atomic text insertion via input method."""
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import socket
+import subprocess
+import stat
+import sys
+from pathlib import Path
+
+from voiceio.backends import ProbeResult
+from voiceio.ibus import SOCKET_PATH
+
+log = logging.getLogger(__name__)
+COMPONENT_DIR = Path.home() / ".local" / "share" / "ibus" / "component"
+COMPONENT_DEST = COMPONENT_DIR / "voiceio.xml"
+LAUNCHER_DIR = Path.home() / ".local" / "share" / "voiceio"
+LAUNCHER_PATH = LAUNCHER_DIR / "voiceio-ibus-engine"
+PING_TIMEOUT = 2.0
+
+
+def _find_system_python() -> str:
+    """Find the system Python 3 interpreter.
+
+    IBus GObject bindings (gi) are system packages, so we need the system
+    Python, not a venv or pipx Python.
+    """
+    # Check well-known system locations first (never a venv)
+    for path in ("/usr/bin/python3", "/usr/bin/python"):
+        if os.path.isfile(path) and os.access(path, os.X_OK):
+            return path
+    # Fallback: whatever python3 resolves to, excluding venvs
+    which = shutil.which("python3")
+    if which and "venv" not in which and "pipx" not in which:
+        return which
+    return "/usr/bin/python3"
+
+
+# Resolved once at import time so probe() / install_component() use the same value.
+SYSTEM_PYTHON = _find_system_python()
+
+
+def _gnome_source_configured() -> bool:
+    """Check if voiceio is in GNOME input sources."""
+    from voiceio.platform import detect
+    if not detect().is_gnome:
+        return True  # non-GNOME: no input source needed
+    try:
+        result = subprocess.run(
+            ["gsettings", "get", "org.gnome.desktop.input-sources", "sources"],
+            capture_output=True, text=True, timeout=3,
+        )
+        return result.returncode == 0 and "('ibus', 'voiceio')" in result.stdout
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return True  # can't check, assume OK
+
+
+def _has_ibus_gi() -> bool:
+    """Check if system Python has IBus GObject bindings."""
+    try:
+        result = subprocess.run(
+            [SYSTEM_PYTHON, "-c", "import gi; gi.require_version('IBus', '1.0')"],
+            capture_output=True, timeout=5,
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def _ibus_daemon_running() -> bool:
+    """Check if the IBus daemon (ibus-daemon) is running."""
+    try:
+        result = subprocess.run(
+            ["ibus", "address"], capture_output=True, text=True, timeout=3,
+        )
+        return result.returncode == 0 and bool(result.stdout.strip())
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def _component_installed() -> bool:
+    """Check if the VoiceIO IBus component XML is installed."""
+    return COMPONENT_DEST.exists() and LAUNCHER_PATH.exists()
+
+
+def _get_pkg_root() -> str:
+    """Get the directory that contains the ``voiceio`` package.
+
+    For a normal pip/pipx install this is the site-packages directory.
+    For an editable (``pip install -e .``) or bare git-clone this is the
+    project source root.  Either way, adding the returned path to
+    PYTHONPATH lets ``python -m voiceio.ibus.engine`` work.
+    """
+    # Path(__file__) -> .../voiceio/typers/ibus.py
+    # .parent        -> .../voiceio/typers/
+    # .parent        -> .../voiceio/           (the package dir)
+    # .parent        -> .../                   (site-packages or source root)
+    return str(Path(__file__).resolve().parent.parent.parent)
+
+
+def install_component() -> bool:
+    """Install the IBus engine launcher and component XML.
+
+    Creates a launcher script (with PYTHONPATH baked in) and a component XML
+    that points to it, then refreshes the IBus cache and restarts IBus.
+
+    Returns True if installed successfully.
+    """
+    pkg_root = _get_pkg_root()
+
+    # The Python that is running *right now* has voiceio installed. Record
+    # its site-packages (or source root) so the launcher can find voiceio
+    # even when launched by the system Python (which needs GObject/IBus
+    # bindings from the system packages).
+    #
+    # We also record the *current* Python as a fallback. If the system
+    # Python cannot import voiceio, the launcher will try the installing
+    # Python directly.
+    installing_python = sys.executable or "python3"
+
+    # Create launcher script
+    LAUNCHER_DIR.mkdir(parents=True, exist_ok=True)
+    launcher_content = f"""#!/bin/bash
+# Generated by voiceio. Do not edit manually.
+# voiceio package root baked in at install time:
+VOICEIO_PKG_ROOT="{pkg_root}"
+
+# Prefer the system Python (has GObject / IBus bindings).
+SYSTEM_PY="{SYSTEM_PYTHON}"
+# The Python that installed voiceio (fallback).
+INSTALL_PY="{installing_python}"
+
+# Add voiceio's package root so the system Python can import it.
+export PYTHONPATH="${{VOICEIO_PKG_ROOT}}:${{PYTHONPATH}}"
+
+# Try system Python first (needed for gi / IBus bindings).
+if "$SYSTEM_PY" -c "import voiceio" 2>/dev/null; then
+    exec "$SYSTEM_PY" -m voiceio.ibus.engine "$@"
+fi
+
+# Fallback: the Python that installed voiceio (may be a venv/pipx Python
+# that already has gi accessible via system site-packages).
+exec "$INSTALL_PY" -m voiceio.ibus.engine "$@"
+"""
+    LAUNCHER_PATH.write_text(launcher_content)
+    LAUNCHER_PATH.chmod(LAUNCHER_PATH.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+    log.info("Installed IBus engine launcher to %s", LAUNCHER_PATH)
+
+    # Write component XML pointing to launcher
+    component_xml = f"""<?xml version="1.0" encoding="utf-8"?>
+<component>
+    <name>org.voiceio.ibus</name>
+    <description>VoiceIO voice input</description>
+    <exec>{LAUNCHER_PATH}</exec>
+    <version>1.0</version>
+    <author>voiceio</author>
+    <license>MIT</license>
+    <textdomain>voiceio</textdomain>
+    <engines>
+        <engine>
+            <name>voiceio</name>
+            <language>other</language>
+            <license>MIT</license>
+            <author>voiceio</author>
+            <layout>us</layout>
+            <longname>VoiceIO</longname>
+            <description>Voice-to-text input</description>
+            <rank>0</rank>
+        </engine>
+    </engines>
+</component>
+"""
+    COMPONENT_DIR.mkdir(parents=True, exist_ok=True)
+    COMPONENT_DEST.write_text(component_xml)
+    log.info("Installed IBus component to %s", COMPONENT_DEST)
+
+    # IBus needs IBUS_COMPONENT_PATH to scan ~/.local/share/ibus/component/
+    ibus_env = _ibus_env()
+
+    # Refresh IBus cache and restart so it discovers the new engine
+    try:
+        subprocess.run(
+            ["ibus", "write-cache"], capture_output=True, timeout=5, env=ibus_env,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+
+    try:
+        subprocess.run(
+            ["ibus", "restart"], capture_output=True, timeout=5, env=ibus_env,
+        )
+        log.info("IBus restarted with IBUS_COMPONENT_PATH")
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        log.warning("Could not restart IBus. Restart manually: ibus restart")
+
+    # Persist IBUS_COMPONENT_PATH so it survives reboot
+    _persist_ibus_env()
+
+    return True
+
+
+def _ibus_env() -> dict[str, str]:
+    """Build environment with IBUS_COMPONENT_PATH including user component dir."""
+    env = os.environ.copy()
+    system_dir = "/usr/share/ibus/component"
+    user_dir = str(COMPONENT_DIR)
+    env["IBUS_COMPONENT_PATH"] = f"{user_dir}:{system_dir}"
+    return env
+
+
+def _persist_ibus_env() -> None:
+    """Write IBUS_COMPONENT_PATH to environment.d so it survives reboot.
+
+    See systemd environment.d(5). Files in ~/.config/environment.d/ are
+    loaded by systemd user services and login sessions.
+    """
+    env_dir = Path.home() / ".config" / "environment.d"
+    env_file = env_dir / "voiceio.conf"
+    system_dir = "/usr/share/ibus/component"
+    user_dir = str(COMPONENT_DIR)
+    content = f"IBUS_COMPONENT_PATH={user_dir}:{system_dir}\n"
+
+    try:
+        if env_file.exists() and env_file.read_text() == content:
+            return  # already persisted
+        env_dir.mkdir(parents=True, exist_ok=True)
+        env_file.write_text(content)
+        log.info("Persisted IBUS_COMPONENT_PATH to %s", env_file)
+    except OSError as e:
+        log.debug("Could not persist IBUS_COMPONENT_PATH: %s", e)
+
+
+def _ensure_gnome_input_source() -> None:
+    """Add ('ibus', 'voiceio') to GNOME input sources if running GNOME."""
+    from voiceio.platform import detect
+    if not detect().is_gnome:
+        return
+
+    try:
+        result = subprocess.run(
+            ["gsettings", "get", "org.gnome.desktop.input-sources", "sources"],
+            capture_output=True, text=True, timeout=3,
+        )
+        if result.returncode != 0:
+            return
+        current = result.stdout.strip()
+        if "('ibus', 'voiceio')" in current:
+            log.debug("VoiceIO already in GNOME input sources")
+            return
+
+        # Parse current sources and append voiceio
+        # Format: [('xkb', 'us'), ('xkb', 'fr')]
+        if current.startswith("@as"):
+            # Empty array
+            new_sources = "[('ibus', 'voiceio')]"
+        elif current == "[]":
+            new_sources = "[('ibus', 'voiceio')]"
+        else:
+            # Insert voiceio at the end (keep current keyboard as default)
+            new_sources = current.rstrip("]") + ", ('ibus', 'voiceio')]"
+
+        subprocess.run(
+            ["gsettings", "set", "org.gnome.desktop.input-sources", "sources", new_sources],
+            capture_output=True, text=True, timeout=3,
+        )
+        log.info("Added VoiceIO to GNOME input sources: %s", new_sources)
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+
+
+class IBusTyper:
+    """IBus preedit for streaming preview, IBus commit for final text.
+
+    Also copies committed text to clipboard so terminal users (where IBus
+    doesn't reach) can Ctrl+Shift+V to paste.
+    """
+
+    name = "ibus"
+
+    def __init__(self, platform=None, **kwargs):
+        self._wl_copy = shutil.which("wl-copy")
+        self._sock: socket.socket | None = None
+        self._wl_copy_proc: subprocess.Popen | None = None
+
+    def probe(self) -> ProbeResult:
+        if not shutil.which("ibus"):
+            return ProbeResult(
+                ok=False,
+                reason="ibus not installed",
+                fix_hint="sudo apt install ibus",
+            )
+
+        if not _has_ibus_gi():
+            return ProbeResult(
+                ok=False,
+                reason="IBus Python bindings not available for system Python",
+                fix_hint="sudo apt install gir1.2-ibus-1.0 python3-gi",
+            )
+
+        if not _ibus_daemon_running():
+            return ProbeResult(
+                ok=False,
+                reason="IBus daemon not running",
+                fix_hint="ibus-daemon -drxR",
+            )
+
+        if not _component_installed():
+            if install_component():
+                log.info("Auto-installed IBus component")
+            else:
+                return ProbeResult(
+                    ok=False,
+                    reason="VoiceIO IBus component not installed",
+                    fix_hint="Run 'voiceio setup' to install",
+                )
+
+        if not _gnome_source_configured():
+            return ProbeResult(
+                ok=False,
+                reason="VoiceIO not in GNOME input sources",
+                fix_hint="Run 'voiceio setup' to configure",
+            )
+
+        return ProbeResult(ok=True)
+
+    def type_text(self, text: str) -> None:
+        if not text:
+            return
+        self._send(f"commit:{text}")
+        self._copy_to_clipboard(text)
+
+    def delete_chars(self, n: int) -> None:
+        pass  # Not needed: preedit handles corrections atomically
+
+    def update_preedit(self, text: str) -> None:
+        self._send(f"preedit:{text}")
+
+    def commit_text(self, text: str) -> None:
+        """Clear preedit and commit via IBus. Also copies to clipboard."""
+        if not text:
+            self._send("clear")
+            return
+        log.debug("Committing via IBus (%d chars)", len(text))
+        self._send(f"commit:{text}")
+        self._copy_to_clipboard(text)
+
+    def clear_preedit(self) -> None:
+        self._send("clear")
+
+    def _send(self, msg: str) -> None:
+        """Send a command to the IBus engine via Unix DGRAM socket."""
+        try:
+            if self._sock is None:
+                self._sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+            self._sock.sendto(msg.encode("utf-8"), str(SOCKET_PATH))
+        except OSError as e:
+            log.warning("IBus engine not reachable: %s", e)
+            # Reset socket on error so next call retries
+            if self._sock is not None:
+                self._sock.close()
+                self._sock = None
+
+    def _copy_to_clipboard(self, text: str) -> None:
+        """Copy text to clipboard as backup for non-IBus apps (terminals).
+
+        Fire-and-forget. wl-copy stays alive to serve paste requests.
+        Kill previous instance to avoid accumulating processes.
+        """
+        if not self._wl_copy:
+            return
+        # Kill previous wl-copy (it's replaced by the new one)
+        if self._wl_copy_proc is not None:
+            try:
+                self._wl_copy_proc.kill()
+            except OSError:
+                pass
+        try:
+            proc = subprocess.Popen(
+                ["wl-copy"],
+                stdin=subprocess.PIPE, stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            proc.stdin.write(text.encode())
+            proc.stdin.close()
+            self._wl_copy_proc = proc
+        except OSError as e:
+            log.debug("wl-copy failed to start: %s", e)

voiceio/typers/pynput_type.py

@@ -0,0 +1,51 @@
+"""Pynput text injection backend for macOS (and X11 fallback)."""
+from __future__ import annotations
+
+import logging
+
+from voiceio.backends import ProbeResult
+
+log = logging.getLogger(__name__)
+
+
+class PynputTyper:
+    """Type text via pynput keyboard controller."""
+
+    name = "pynput"
+
+    def __init__(self):
+        self._controller = None
+
+    def _get_controller(self):
+        if self._controller is None:
+            from pynput.keyboard import Controller
+            self._controller = Controller()
+        return self._controller
+
+    def probe(self) -> ProbeResult:
+        try:
+            from pynput.keyboard import Controller  # noqa: F401
+        except ImportError:
+            return ProbeResult(ok=False, reason="pynput not installed",
+                               fix_hint="pip install pynput")
+
+        import os
+        session = os.environ.get("XDG_SESSION_TYPE", "")
+        if session == "wayland":
+            return ProbeResult(ok=False, reason="pynput typing does not work on Wayland")
+
+        return ProbeResult(ok=True)
+
+    def type_text(self, text: str) -> None:
+        if not text:
+            return
+        self._get_controller().type(text)
+
+    def delete_chars(self, n: int) -> None:
+        if n <= 0:
+            return
+        from pynput.keyboard import Key
+        kb = self._get_controller()
+        for _ in range(n):
+            kb.press(Key.backspace)
+            kb.release(Key.backspace)