cthulhu/README.md

81 lines
3.0 KiB
Markdown
Raw Permalink Normal View History

2024-10-20 21:23:20 -04:00
# Cthulhu
## 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
2024-10-20 21:23:20 -04:00
toolkit, OpenOffice/LibreOffice, Gecko, WebKitGtk, and KDE Qt toolkit.
## Dependencies
2024-10-20 21:23:20 -04:00
Cthulhu has the following dependencies:
* Python 3 - Python platform
* pygobject-3.0 - Python bindings for the GObject library
2024-10-20 20:17:53 -04:00
* libpeas - GObject based Plugin engine
* gtk+-3.0 - GTK+ toolkit
* json-py - a JSON (<https://json.org/>) reader and writer in Python
* python-speechd - Python bindings for Speech Dispatcher (optional)
* BrlTTY - BrlTTY (<https://mielke.cc/brltty/>) support for braille (optional)
* BrlAPI - BrlAPI support for braille (optional)
* liblouis - Liblouis (<http://liblouis.org/>) support for contracted braille (optional)
* py-setproctitle - Python library to set the process title (optional)
* gstreamer-1.0 - GStreamer - Streaming media framework (optional)
You are strongly encouraged to also have the latest stable versions
2024-10-20 21:23:20 -04:00
of AT-SPI2 and ATK.
2024-10-20 21:23:20 -04:00
## 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
2024-10-20 21:23:20 -04:00
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
2024-10-20 21:23:20 -04:00
of the source tree. Cthulhu also has an excellent plugin system, more documentation and examples coming soon.
2024-10-21 12:53:24 -04:00
## 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
```