cthulhu/README.md

# Cthulhu 

## Note

Cthulhu is a fork of the Orca screen reader. Project home: https://git.stormux.org/storm/cthulhu. Cthulhu is currently a supplemental screen reader that fills a niche for some advanced users. For example, some older Qt-based programs may work with Cthulhu, and if you use certain window managers like i3, Mozilla applications like Firefox and Thunderbird may work better.

## Current Maintenance

Cthulhu is currently maintained by Storm Dragon.

Current contributors called out in this fork's documentation:

- Hunter Joziak
- Harley Richardson (`destructatron`)

## Project History

Cthulhu is forked from Orca and builds on many years of upstream work by the Orca community, including former maintainers and contributors such as Joanmarie Diggs and others.

Those upstream maintainers and contributors are part of the project's history, but they are not current maintainers of this fork unless explicitly noted elsewhere.


## Introduction

Cthulhu is a free, open source, flexible, and extensible screen reader
that provides access to the graphical desktop via user-customizable
combinations of speech and/or braille.

Cthulhu works with applications and toolkits that support the assistive
technology service provider interface (AT-SPI), which is the primary
assistive technology infrastructure for the Solaris and Linux
operating environments.  Applications and toolkits supporting the
AT-SPI include the GNOME GTK+ toolkit, the Java platform's Swing
toolkit, OpenOffice/LibreOffice, Gecko, WebKitGtk, and KDE Qt toolkit.

## Key Features

### Desktop-Agnostic Design
- **Universal compatibility**: Works on KDE, XFCE, i3, Sway, and other desktop environments
- **Minimal GNOME dependencies**: Reduced reliance on GNOME-specific libraries
- **Tiling window manager optimized**: Enhanced support for i3, Sway, and similar WMs

### Plugin System
- **Extensible architecture**: Plugin system using pluggy framework
- **Hot-reloadable plugins**: Add functionality without restarting
- **Community plugins**: User and system plugin directories
- **Plugin preferences**: Plugins can provide preferences pages that appear only when the plugin is active

### Remote Control
- **D-Bus interface**: External control via D-Bus service
- **API access**: Remote access to Cthulhu functions and settings
- **Automation support**: Script-friendly remote control

### Sleep Mode
- **Application-specific**: Disable speech/events per application
- **Toggle keybinding**: `Cthulhu+Ctrl+Alt+Shift+Q`
- **Preserves exit key**: Only sleep toggle remains active

### Self-Voicing
- **Unix socket interface**: Direct speech output via `/tmp/cthulhu.sock`
- **External integration**: Other applications can speak through Cthulhu
- **Simple protocol**: `echo "text" | socat - UNIX-CLIENT:/tmp/cthulhu.sock`

## D-Bus Remote Controller

Cthulhu exposes a D-Bus service for external automation and integrations.

### Service Details
- **Service Name**: `org.stormux.Cthulhu.Service`
- **Main Object Path**: `/org/stormux/Cthulhu/Service`
- **Module Object Paths**: `/org/stormux/Cthulhu/Service/<ModuleName>`

### Discovering Capabilities

```bash
# List registered modules
gdbus call --session --dest org.stormux.Cthulhu.Service \
  --object-path /org/stormux/Cthulhu/Service \
  --method org.stormux.Cthulhu.Service.ListModules

# List commands on a module
gdbus call --session --dest org.stormux.Cthulhu.Service \
  --object-path /org/stormux/Cthulhu/Service/ModuleName \
  --method org.stormux.Cthulhu.Module.ListCommands
```

### Plugin Modules

Plugins that expose D-Bus decorators are automatically registered as modules using the naming
convention `Plugin_<ModuleName>` (for example, `Plugin_GameMode`, `Plugin_WindowTitleReader`).

### PluginSystemManager Module

The `PluginSystemManager` module provides **session-only** plugin control (no preference changes):

- `ListPlugins`
- `ListActivePlugins`
- `IsPluginActive` (parameterized)
- `SetPluginActive` (parameterized)
- `RescanPlugins`

### Plugin Preferences Pages

Plugins can add their own Preferences tab without modifying Cthulhu core code.
Implement `getPreferencesGUI()` to return a Gtk widget (or `(widget, label)`),
and `getPreferencesFromGUI()` to return a settings dict. The tab appears only
when the plugin is active.

### More Documentation

See `README-REMOTE-CONTROLLER.md` and `REMOTE-CONTROLLER-COMMANDS.md` for the full D-Bus API
and usage examples.

## Dependencies

### Core Requirements

* **Python 3.9+**       - Python platform
* **pygobject-3.0**      - Python bindings for the GObject library  
* **gtk+-3.0**           - GTK+ toolkit (minimal usage for AT-SPI integration)
* **AT-SPI2**            - Assistive Technology Service Provider Interface
* **ATK**                - Accessibility Toolkit

### Desktop-Neutral Features

* **pluggy**             - Plugin and hook calling mechanisms for Python
* **python-dasbus**      - D-Bus remote control interface (optional)

### Audio and Speech

* **python-speechd**     - Python bindings for Speech Dispatcher (recommended)
* **gstreamer-1.0**      - GStreamer streaming media framework (for sounds)
* **piper-tts**          - Piper neural text-to-speech engine (optional)

Piper voice models are typically stored under `~/.local/share/piper/voices` or
`/usr/share/piper-voices`.

### Braille Support (Optional)

* **BrlTTY**             - BrlTTY (<https://mielke.cc/brltty/>) braille terminal support
* **BrlAPI**             - BrlAPI Python bindings for braille
* **liblouis**           - Liblouis (<http://liblouis.org/>) contracted braille translation

### System Integration

* **py-setproctitle**    - Python library to set the process title (optional)
* **socat**              - Used for self-voicing functionality
* **xorg-xkbcomp**       - X keyboard compiler (for key remapping)
* **xorg-xmodmap**       - X modifier map utility

You are strongly encouraged to also have the latest stable versions
of AT-SPI2 and ATK.


## Braille

Cthulhu depends upon the Python bindings for BrlAPI available in BrlTTY v4.5
or better.  You can determine if the Python bindings for BrlAPI are
installed by running the following command:

```sh
python -c "import brlapi"
```

If you get an error, the Python bindings for BrlAPI are not installed.

## Running Cthulhu

If you wish to modify your Cthulhu preferences, you can press "Insert+space"
while Cthulhu is running.

To get help while running Cthulhu, press "Insert+H".  This will enable
"learn mode", which provides a spoken and brailled description of what
various keyboard and braille input device actions will do.  To exit
learn mode, press "Escape."  Finally, the preferences dialog contains
a "Key Bindings" tab that lists the keyboard binding for Cthulhu.

For more information, see the Cthulhu documentation which is available
within Cthulhu.

## Scripting Cthulhu

So, you want to write a script for Cthulhu?  The best thing to do is 
start by looking at other scripts under the src/cthulhu/scripts/ hierarchy
of the source tree. Cthulhu also has an excellent plugin system, more documentation and examples coming soon.

## Building and Installation

### Prerequisites

Ensure you have the development dependencies installed:

**Arch Linux:**
```bash
sudo pacman -S python python-gobject gtk3 at-spi2-core at-spi2-atk \
               python-speechd gstreamer python-pluggy python-dasbus \
               python-tomlkit \
               meson ninja pkgconf intltool gettext
```

**Debian/Ubuntu:**
```bash
sudo apt install python3 python3-gi python3-gi-cairo gir1.2-gtk-3.0 \
                 at-spi2-core libatk-adaptor python3-speechd \
                 gstreamer1.0-plugins-base python3-pluggy python3-dasbus \
                 python3-tomlkit \
                 meson ninja-build pkg-config intltool gettext
```

### Local Development Build (Recommended)

For active development, build and install to your user directory:

```bash
# Build and install to ~/.local
./build-local.sh

# Test the local installation
./test-local.sh

# Run your local version
~/.local/bin/cthulhu

# Clean build artifacts and local installation
./clean-local.sh
```

This approach:
- Installs to `~/.local/bin/cthulhu` (won't conflict with system installation)
- Loads modules from `~/.local/lib/python*/site-packages/cthulhu/`
- Preserves any system-wide Cthulhu installation at `/usr/bin/cthulhu`

### System Installation

For system-wide installation:

```bash
# Configure the build
meson setup _build --prefix=/usr

# Compile
meson compile -C _build

# Install (requires sudo)
sudo meson install -C _build
```

### Manual Meson Build

If you prefer to use Meson commands directly instead of the convenience scripts:

```bash
# Configure for local installation
meson setup _build --prefix=$HOME/.local

# Or configure for system installation  
meson setup _build --prefix=/usr

# Compile
meson compile -C _build

# Install
meson install -C _build

# Clean
rm -rf _build
```

### Testing

Manual testing is recommended. The legacy keystroke-driven test harness has been removed.

## Self-voicing

Cthulhu offers a mechanism through which messages may be spoken directly by the screen reader. Usage is as follows:

```bash
# Speak hello world.
echo "Hello world." | socat - UNIX-CLIENT:/tmp/cthulhu.sock
# Speak Hello world without interrupting the previous speech.
echo "<!#APPEND#!>Hello world." | socat - UNIX-CLIENT:/tmp/cthulhu.sock
# Make hello world persistant in Braille.
echo "Hello world.<#APPEND#>" | socat - UNIX-CLIENT:/tmp/cthulhu.sock
```