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:

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

Plugin System

Remote Control

Sleep Mode

Self-Voicing

D-Bus Remote Controller

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

Service Details

Discovering Capabilities

# List registered module object paths and introspect their methods/properties
gdbus introspect --session --dest org.stormux.Cthulhu1.Service \
  --object-path /org/stormux/Cthulhu1/Service --recurse

# Inspect one module
gdbus introspect --session --dest org.stormux.Cthulhu1.Service \
  --object-path /org/stormux/Cthulhu1/Service/ModuleName

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):

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

Desktop-Neutral Features

Audio and Speech

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

Braille Support (Optional)

System Integration

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:

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:

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:

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

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

# 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:

# 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:

# 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:

# 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