From 4f5a875d0e55fe6e61c7bc0db7a0528e95fa6d00 Mon Sep 17 00:00:00 2001 From: Storm Dragon Date: Wed, 28 Oct 2026 00:45:23 -0400 Subject: [PATCH] Updated some documentation. --- AGENTS.md | 159 -- CREDITS | 24 +- README.md | 1020 ++------ config/keyboard/Readme.md | 653 +---- docs/Howto Configure Pulse Systemwide.txt | 29 +- docs/create_manpage.sh | 31 +- docs/diff_review_mode.md | 48 - docs/fenrir.1 | 1236 +++++----- docs/fenrir.adoc | 2656 ++++----------------- docs/user.md | 778 +++--- docs/user.txt | 1762 ++++---------- internal/app/screen_policy_test.go | 46 + internal/console/native_linux.go | 21 + internal/console/paste_linux.go | 12 + internal/console/paste_linux_test.go | 13 + internal/console/source_linux.go | 18 +- internal/console/source_linux_test.go | 117 + 17 files changed, 2416 insertions(+), 6207 deletions(-) delete mode 100644 AGENTS.md delete mode 100644 docs/diff_review_mode.md diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 82ca526a..00000000 --- a/AGENTS.md +++ /dev/null @@ -1,159 +0,0 @@ -## Development Philosophy - -**Clean code over backward compatibility.** Breaking changes are acceptable in major versions. - -- PEP8 compliance (snake_case for all variables/functions/settings) -- Remove deprecated code completely - no compatibility hacks -- Trust users to update configs when upgrading - -**Exception**: Never break core accessibility (speech output, basic navigation). - -## Translation Maintenance - -- Make all new or changed user-facing messages translatable, including speech - announcements, help, command descriptions, menus, and errors. Import `_` and - `ngettext` as needed from `fenrirscreenreader.core.i18n`. -- Translate complete literal messages before formatting values, for example - `_("Loading voices for {module}").format(module=module)`. Avoid translated - sentence fragments, f-strings inside `_()`, and formatting before translation. - Use `ngettext()` for count-dependent messages and preserve placeholders. -- Keep internal identifiers, configuration keys, filenames, application content, - and clipboard data unchanged. -- When messages change, regenerate `tools/fenrir.pot` with - `./tools/generate_translations.sh`, then run - `./tools/generate_translations.sh check`. -- Preserve existing translations. Update specific `.po` catalogs only when - requested; leave untranslated and fuzzy entries for translator review. -- Review the diff for user-facing strings missing translation markers; the - catalog check cannot detect every unmarked string. -- For localization behavior changes, run - `pytest tests/unit/test_translations.py` and verify the affected workflow. - Consult the README's Localization section for the maintenance workflow. - -## Core Architecture - -### Drivers -- **Screen**: `vcsaDriver` (TTY), `ptyDriver` (terminal emulation) -- **Input**: `evdevDriver` (evdev), `x11Driver` (X11 terminal mode) -- **Speech**: `speechdDriver` (speech-dispatcher), `genericDriver` (subprocess) -- **Sound**: `gstreamerDriver` (GStreamer), `genericDriver` (Sox subprocess) -- **Remote**: `unixDriver` (Unix sockets), `tcpDriver` - -### Command System -Commands in trigger folders execute automatically: -- `onKeyInput/`, `onCursorChange/`, `onScreenUpdate/`, `onScreenChanged/`, `onHeartBeat/` -- Numeric prefixes control priority (lower = higher priority): `15000-char_echo.py` -- Manual commands in `commands/commands/` - -### Core Managers (in `src/fenrirscreenreader/core/`) -`fenrirManager.py`, `commandManager.py`, `eventManager.py`, `screenManager.py`, `inputManager.py`, `outputManager.py` - -### Configuration -- Main: `config/settings/settings.conf` -- Keyboards: `config/keyboard/` (desktop.conf, laptop.conf) -- Sounds: `config/sound/` -- Punctuation: `config/punctuation/` - -## 🚨 CRITICAL: Files to NEVER Modify - -**These are timing-critical - only fix critical bugs, never refactor:** -- `evdevDriver.py` - Input event processing -- `vcsaDriver.py` - Screen monitoring - -Symptoms of breakage: echo changes, input lag, missing screen updates, sync issues. - -## Development Commands - -```bash -# Run from source (requires root) -cd src/ && sudo ./fenrir -f -d # foreground with debug - -# Validation before commit -python3 tools/validate_syntax.py --fix -python3 tools/validate_release.py --quick - -# Tests -pytest tests/ -pytest tests/ --cov=src/fenrirscreenreader --cov-report=html -``` - -**Note**: Standard TTY Fenrir blocks - only one instance at a time. `fenrir -x` -can run multiple foreground X terminal instances. Ask user to run tests that -need real Fenrir instances or root access. - -### Packaging Test Layouts - -- Debian `pybuild` runs copied tests from a nested `.pybuild/.../build` tree - and may omit top-level source directories such as `config/`. -- Tests that inspect source resources must locate them by walking upward from - the resolved test path; do not assume a fixed `Path(__file__).parents[N]`. -- Packaging-sensitive test changes should be checked from both the source tree - and a representative nested build directory under `/tmp`. - -## Creating Commands - -Use `commands/command_template.py` as base. Required methods: -- `initialize(self, environment)`, `shutdown()`, `run()`, `get_description()` - -### Import Pattern (Required) -Fenrir's command loader doesn't support relative imports: -```python -import os, importlib.util -_base_path = os.path.join(os.path.dirname(__file__), 'base_file.py') -_spec = importlib.util.spec_from_file_location("base_module", _base_path) -_module = importlib.util.module_from_spec(_spec) -_spec.loader.exec_module(_module) -BaseClass = _module.BaseClass -``` - -### Consolidated Base Classes -- **Bookmarks**: `bookmark_base.py` - `BookmarkCommand(id, 'read'|'set'|'clear')` -- **Adjustments**: `adjustment_base.py` - `AdjustmentCommand('speech'|'sound', 'rate'|'pitch'|'volume', 'inc'|'dec')` -- **VMenu Search**: `vmenu_search_base.py` - `VMenuSearchCommand('a'-'z')` - -## VMenu System - -Application-specific menus in `vmenu-profiles/KEY/{app}/`: -- Directories = submenus, `.py` files = actions -- Activate: `Fenrir+F10`, navigate with arrows, Enter to execute - -## Remote Control - -Unix socket: `/tmp/fenrirscreenreader-daemon.sock` -TCP: localhost:22447 - -```bash -echo "command say Hello" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -echo "ls" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -echo "setting set speech#rate=0.8" | nc localhost 22447 -``` - -In `fenrir -x`, each instance has a private socket: -`/tmp/fenrirscreenreader-.sock`. One instance may also own the standard -socket. Use `ls`/`list` on the standard socket to discover registered instances -and their socket paths. Untargeted remote commands use a short cross-process -claim lock so only one instance handles the same broadcast command; direct -commands to a private instance socket still run on that instance. - -Disable in untrusted environments: `[remote] enable=False` - -## Key Implementation Details - -- Commands via `command_mod.command()` instantiation -- Bookmark structure: `env['commandBuffer']['bookMarks'][ID][app]['1'/'2']` -- VMenu search: `env['runtime']['vmenuManager'].searchEntry(char)` - -## Recent Fixes (Reference) - -- Enhanced application detection for screen/tmux sessions -- Table navigation consistency (sound feedback) -- Blank line detection in 22 command files -- Character/space review during navigation - -## Safe vs Risky Changes - -**Safe**: Commands, VMenu profiles, config handling, sound/speech drivers, docs - -**Risky (extra testing)**: Core managers, event processing - -**Avoid**: evdevDriver, vcsaDriver, timing-critical code diff --git a/CREDITS b/CREDITS index 1f889316..4442874d 100644 --- a/CREDITS +++ b/CREDITS @@ -6,25 +6,9 @@ * **Storm Dragon** - Project leader and maintainer -## Current Contributors - -* **Jeremiah** - Developer - - -## Previous Developers - -* **Chrys** - Original creator and main developer - - ## Special Thanks -* **F123 Consulting** - Suggestions, funding, and extensive testing -* **Stormux Community** - Continuation of the project and ongoing support -* **All contributors** - Bug reports, feature requests, and community support - - -## Community - -* IRC: irc.stormux.org #stormux -* Email list: stormux+subscribe@groups.io -* Wiki: https://git.stormux.org/storm/fenrir/wiki +Special thanks to **Chrys**, without whom this project would not exist in the +first place. He wrote Fenrir from scratch when I desperately needed a console +screen reader. His hard work and dedication to accessibility are always +appreciated. diff --git a/README.md b/README.md index 8c3f6adf..0690e75e 100644 --- a/README.md +++ b/README.md @@ -1,879 +1,244 @@ # Fenrir -A modern, modular, flexible and fast console screen reader for Linux. -This software is licensed under the LGPL v3. +Fenrir is a console screen reader for Linux, written in Go. It reads the Linux +text console and can also run inside an X11 terminal without root privileges. **Current maintainer:** Storm Dragon -**Previous developer:** Chrys +**Original creator:** Chrys (see [CREDITS](CREDITS)) -## Key Features +See the [user manual](docs/user.md) for detailed usage documentation. -- **Linux Console Support**: Works as a Linux TTY screen reader, with optional X11 terminal mode -- **Flexible Driver System**: Modular architecture with multiple drivers for speech, sound, input, and screen -- **Review Mode**: Navigate and review screen content without moving the edit cursor -- **Table Navigation**: Advanced table mode with column headers, cell-by-cell navigation, and boundary feedback -- **Progress Bar Monitoring**: Automatic detection and audio feedback for progress indicators with ascending tones -- **Multiple Clipboard Support**: Manage multiple clipboard entries -- **Configurable Key Bindings**: Desktop and laptop keyboard layouts -- **Sound Icons**: Audio feedback for various events -- **Spell Checking**: Built-in spell checker with word management -- **Language Support**: Multiple speech synthesis languages and voices -- **Bookmark System**: Quick access to specific screen areas -- **Auto-announcement**: Automatic reading of incoming text and time announcements -- **Tutorial Mode**: Built-in help system for learning keyboard shortcuts +## Features +- Screen review by line, word, and character, including spelling and phonetic reading. +- Cursor, table, and highlight tracking. +- Desktop and laptop keyboard layouts, with an interactive tutorial. +- A keyboard-operated settings menu and quick settings shortcuts. +- Speech Dispatcher and hardware speech synthesizer support. +- Sound icons, progress tones, and indentation and text attribute feedback. +- Multiple clipboards, optional persistent history, and X clipboard synchronization. +- Spell checking, spelling suggestions, and an emoji picker. +- Script shortcuts and Unix socket remote control. +- Translated announcements and help. -## Platform Support +## Build and run -Fenrir is a Linux screen reader. Linux is the only officially supported platform. +Build requirements: -**Other platforms (macOS, BSD, Windows):** Pull requests adding support for other operating systems may be accepted provided they do not break Linux functionality. However, no special care will be taken to preserve functionality on secondary platforms. If changes to Fenrir break support on a non-Linux OS, it is the responsibility of third-party contributors to submit fixes. +- Linux and Go 1.27.2 or newer (see [go.mod](go.mod)). +- A C compiler and `pkg-config`. +- Development headers and libraries for libevdev, X11, libvterm, and ALSA. + Their pkg-config names are `libevdev`, `x11`, `vterm`, and `alsa`. -- Linux TTY (`vcsaDriver`, `evdevDriver`) - Full support -- X11 terminal emulators (`-x`, `ptyDriver`, `x11Driver`) - Supported +Runtime requirements depend on the features you use: +- Speech Dispatcher with a configured synthesizer for the default speech driver. +- PulseAudio or PipeWire's PulseAudio service for the default sound driver; + ALSA output is also available. +- Enchant 2 and a dictionary for your language for spell checking. +- `xclip` for X clipboard synchronization. +- libusb 1.0 for native DECtalk USB speech, or access to the configured serial + device for a serial synthesizer. -## Core Requirements +From the checkout root: -- Python 3 >= 3.9 (recommended 3.13+) -- Screen, input, speech, sound driver dependencies (see "Features, Drivers, Extras" section) -- For full functionality on Linux: evdev, speech-dispatcher, sox - - -## Features, Drivers, Extras, Dependencies - -### Input Drivers: -1. **evdevDriver** - Linux evdev input driver (recommended for Linux) - - python-evdev >=0.6.3 (This is commonly referred to as python3-evdev by your distribution) - - python-pyudev - - loaded uinput kernel module - - ReadWrite permission: - - /dev/input - - /dev/uinput -2. **x11Driver** - X11 terminal-scoped input driver for `fenrir -x` - - python-xlib -### Remote Drivers: -1. **unixDriver** - Unix socket remote control (default) - - socat (for command-line interaction) -2. **tcpDriver** - TCP socket remote control (localhost only) - - netcat or telnet (for command-line interaction) - - -### Screen Drivers: - -1. **vcsaDriver** - Linux VCSA devices driver (recommended for Linux TTY) - - python-dbus - - Read permission to the following files and services: - - /sys/devices/virtual/tty/tty0/active - - /dev/tty[1-64] - - /dev/vcsa[1-64] - - read logind DBUS -2. **ptyDriver** - Terminal emulation screen driver for `fenrir -x` - - python-pyte - - -### Speech Drivers: - -1. **speechdDriver** - Speech-dispatcher driver (recommended) - - Speech-dispatcher - - python-speechd -2. **genericDriver** - Generic subprocess speech driver - - espeak or espeak-ng (or any TTS command) -3. **dectalkDriver** - Serial DECtalk-compatible hardware speech driver - - RPITalk gadget mode or a DECtalk-compatible serial device -4. **dectalkUsbDriver** - Native Access Solutions DECtalk USB driver - - USB ID `0dd0:2001` - - PyUSB and a libusb backend -5. **litetalkDriver** - Serial LiteTalk-compatible hardware speech driver - - RPITalk gadget mode or a LiteTalk-compatible serial device -6. **doubletalkDriver** - Serial DoubleTalk LT-compatible hardware speech driver - - DoubleTalk LT; does not support the internal DoubleTalk PC card -7. **tripletalkDriver** - Serial TripleTalk-compatible hardware speech driver - - External DB9 serial TripleTalk devices, or USB models that expose a tty serial device -8. **debugDriver** - Debug speech driver for testing - - No dependencies - - -### Sound Drivers: - -1. **genericDriver** (default) - Generic subprocess sound driver - - Sox with opus support (recommended) -2. **gstreamerDriver** - GStreamer sound driver - - gstreamer >=1.0 - - GLib -3. **debugDriver** - Debug sound driver for testing - - No dependencies - - -## Extras: - -1. spellchecker - - python-pyenchant - - aspell-YourLanguageCode (example aspell-en for us English) -2. Unix daemon (also needed for Systemd): - - python-daemonize -3. Modify system volume: - - pyalsaaudio (needs libasound2's headers). - - -## installation - -If there is a package for your distrobution of choice, please let us know so we can add it here. - -- Archlinux: PKGBUILD in AUR - - fenrir: stable release - - fenrir-git: Bleeding edge release -- Manual: - - install "espeak" and "sox" with your package manager - - sudo pip install -r requirements.txt - - run install.sh or uninstall.sh as root -- You can also just run it from Git without installing: -Requires root privileges - - cd src/ - sudo ./fenrir - -Settings are located in: -- **System-wide installation**: `/etc/fenrirscreenreader/settings/settings.conf` -- **User-local settings**: `~/.local/share/stormux/fenrirscreenreader/settings/settings.conf` -- **Development**: `config/settings/settings.conf` - -When Fenrir runs as a regular user, including `fenrir -x`, it loads the -user-local settings file if it exists. If it does not exist, Fenrir falls back -to the system settings file, but saving settings writes to the user-local path. -When Fenrir runs as root, settings save to the system-wide path by default. - -User sound themes are loaded before system themes from -`~/.local/stormux/fenrir/sounds/`. User scripts are loaded before configured -system scripts from `~/.local/stormux/fenrir/`. - -By default Fenrir uses: -- **Sound driver**: genericDriver (via sox) -- **Speech driver**: speechdDriver (via speech-dispatcher) -- **Input driver**: evdevDriver for Linux TTY, x11Driver for `fenrir -x` -- **Screen driver**: vcsaDriver for Linux TTY, ptyDriver for `fenrir -x` - -The VMenu word-echo and sound toggles take effect immediately. Exclusive -keyboard access is staged: save settings, then restart Fenrir to apply it. -Until restart, Fenrir retains the active keyboard-grabbing mode so existing -devices can be released correctly. Toggling it again before restart changes -the staged choice. Unsaved changes are discarded when Fenrir exits. - -## Audio Configuration - -Both PulseAudio and PipeWire require special configuration to allow console applications running as root (like Fenrir) to route audio to your regular user session. This is normal audio system behavior, not a Fenrir issue. - -### Quick Setup - Direct Script Download - -For non-Fenrir users or quick setup, download and run these scripts directly: - -#### PulseAudio Configuration ```bash -# Download the script -wget https://git.stormux.org/storm/fenrir/raw/branch/master/tools/configure_pulse.sh -chmod +x configure_pulse.sh - -# Run twice: once as user, once as root -./configure_pulse.sh -sudo ./configure_pulse.sh +go build -o fenrir ./cmd/fenrir +./fenrir --config config/settings/settings.toml --check-config ``` -#### PipeWire Configuration +Keep the binary beside the `config/` directory when running from the checkout; +keyboard layouts, punctuation profiles, and sound themes are runtime resources. + +### Linux console + +From a Linux text console: + ```bash -# Download the script -wget https://git.stormux.org/storm/fenrir/raw/branch/master/tools/configure_pipewire.sh -chmod +x configure_pipewire.sh - -# Run twice: once as user, once as root -./configure_pipewire.sh -sudo ./configure_pipewire.sh +sudo ./fenrir ``` -**Direct links:** -- [configure_pulse.sh](https://git.stormux.org/storm/fenrir/raw/branch/master/tools/configure_pulse.sh) -- [configure_pipewire.sh](https://git.stormux.org/storm/fenrir/raw/branch/master/tools/configure_pipewire.sh) +Console mode needs access to the console devices, keyboard event devices, and +`/dev/uinput`. Run only one reader on the same console. Fenrir releases keyboard +input on graphical virtual terminals and on text consoles listed in +`screen.ignored_vts`. -### Using Installed Scripts +When running as root, audio must be configured to reach the intended sound +server or ALSA device. The [PulseAudio](tools/configure_pulse.sh) and +[PipeWire](tools/configure_pipewire.sh) configuration scripts are included for +systems that need root audio access. -If you have Fenrir installed, the scripts are available at: +### X11 terminal + +From an X11 terminal that supplies `WINDOWID`: -**PulseAudio:** ```bash -/usr/share/fenrirscreenreader/tools/configure_pulse.sh -sudo /usr/share/fenrirscreenreader/tools/configure_pulse.sh +./fenrir -x ``` -**PipeWire:** +This starts a shell in a new PTY inside the terminal. Fenrir's key bindings are +scoped to that terminal window, allowing a desktop screen reader to handle +other windows. Multiple terminal instances can run at once. Both `DISPLAY` and +a valid `WINDOWID` must be available. + +Use `--keyboard-layout laptop` with either mode to select the laptop layout. + +## Basic controls + +The Fenrir key is Insert, Super/Windows, or keypad 0 with NumLock off. +Hold it while pressing the other keys in a shortcut. Bare keypad review keys +also require NumLock off. + +| Action | Desktop | Laptop | +| --- | --- | --- | +| Previous / current / next line | Keypad 7 / 8 / 9 | Fenrir+U / I / O | +| Previous / current / next word | Keypad 4 / 5 / 6 | Fenrir+J / K / L | +| Previous / current / next character | Keypad 1 / 2 / 3 | Fenrir+M / Comma / Period | +| Read screen | Fenrir+Keypad 5 | Fenrir+Shift+K | +| Follow application cursor | Fenrir+Keypad Period | Fenrir+Slash | +| Cycle tracking mode | Fenrir+Keypad Asterisk | Fenrir+Y | +| Toggle progress tones | Keypad Plus | Fenrir+Shift+P | + +Shortcuts shared by both layouts: + +- **Control**: interrupt speech. +- **Fenrir+F**: open the Fenrir Menu. +- **Fenrir+H** or **Fenrir+F1**: enter the tutorial. Press command shortcuts to + hear their descriptions, or browse with the arrow keys. Escape exits. +- **Fenrir+S**: open the spellcheck menu. +- **Fenrir+Control+E**: open the emoji picker. +- **Fenrir+T**: announce the time; press twice quickly for the date. +- **Fenrir+F4**: toggle mute. +- **Fenrir+Backspace**: pass the next key through to the application. +- **Fenrir+Q**: quit Fenrir. + +Press the current-line or current-word shortcut twice quickly to spell it, or +three times for phonetic reading. Press the current-character shortcut twice +for its phonetic name. The complete bindings are in +[desktop.toml](config/keyboard/desktop.toml) and +[laptop.toml](config/keyboard/laptop.toml). + +Tracking cycles through **cursor**, **table**, and **highlight**. Cursor mode +follows application cursor movement. Table mode supports cell navigation in +delimited or aligned text. Highlight mode follows changes to highlighted text. +Screen review lets you explore text without moving the application cursor. + +## Settings + +Press **Fenrir+F** to open the Fenrir Menu. Use arrows to choose a settings tab, +then Tab or Shift+Tab to move between controls and back to the tab selector. +Space toggles checkboxes; arrows change selections and numeric values. Activate +**OK** to save, or **Cancel** or Escape to discard the form's changes. + +The menu includes speech, sound, reading, keyboard, clipboard, and other +settings. Speech rate, pitch, and volume use a scale from -100 to 100. +Backend, device, keyboard layout, sound theme, and other launch-only changes +take effect the next time Fenrir starts. + +Quick settings are available without opening the menu: + +- **Fenrir+Space**: announce the current setting. +- **Fenrir+Left / Right**: select a setting. +- **Fenrir+Control+Left / Right**: select a category. +- **Fenrir+Up / Down**: change the value. +- **Fenrir+Control+S**: save settings. + +Quick settings take effect during the session; save them to keep them for the +next launch. + +### Configuration files + +Fenrir uses TOML. The annotated [settings.toml](config/settings/settings.toml) +describes the available settings, including options edited only in the file. + +Default settings locations: + +- Regular user: `~/.local/share/stormux/fenrirscreenreader/settings/settings.toml`, + then `/etc/fenrirscreenreader/settings/settings.toml`. +- Root: `/etc/fenrirscreenreader/settings/settings.toml`. + +Fenrir loads the first existing file, or built-in defaults if neither exists. +Use `--config PATH` to select a specific file. To create a personal settings +file without opening devices: + ```bash -/usr/share/fenrirscreenreader/tools/configure_pipewire.sh -sudo /usr/share/fenrirscreenreader/tools/configure_pipewire.sh +./fenrir --write-config ~/.local/share/stormux/fenrirscreenreader/settings/settings.toml ``` -**Note:** These scripts work for any console application that needs root audio access, not just Fenrir. +Validate an edited file with: + +```bash +./fenrir --config ~/.local/share/stormux/fenrirscreenreader/settings/settings.toml --check-config +``` + +Keyboard layouts are separate TOML files. Named layouts are searched in the +user's `keyboard/` directory beside `settings/`, then +`/etc/fenrirscreenreader/keyboard/`, then the checkout's bundled layouts. +Root uses the system and bundled locations. `--keyboard-layout PATH.toml` +selects a file directly. + +Speech drivers are `speech-dispatcher`, `dectalk`, `dectalk-usb`, `litetalk`, +`doubletalk`, and `tripletalk`. Serial drivers need a device path. The Speech +settings tab includes a **Test synthesizer** button for hardware drivers. + +Clipboard persistence is optional and off by default. It stores unencrypted +history separately for console and terminal sessions. X clipboard sync is +controlled by `clipboard.sync`. + +## Remote control + +Fenrir accepts remote commands through Unix sockets. The standard socket is +`/tmp/fenrirscreenreader-daemon.sock`; instances also have private sockets named +`/tmp/fenrirscreenreader-.sock`. Discover instances with: -## Getting Started - -### Basic Usage - -1. **Start Fenrir**: - ```bash - sudo systemctl start fenrir # If installed as service - # OR - sudo fenrir # Run directly - ``` - -2. **Basic Navigation**: - - **Fenrir Key**: By default `Insert`, `Keypad Insert`, or `Meta/Super` key - - **Tutorial Mode**: `Fenrir + H` to learn all commands interactively - - **Speech History**: `Fenrir + Ctrl + H` to review recent speech - - **Quit Fenrir**: `Fenrir + Q` - -3. **Essential Commands**: - - `Ctrl` - Stop speech (shut up) - - `Fenrir + Keypad 5` - Read current screen - - `Keypad 8` - Read current line - - `Keypad 5` - Read current word - - `Keypad 2` - Read current character - - `Fenrir + T` - Announce time - - `Fenrir + S` - Spell check current word - - `Fenrir + Keypad *` - Toggle table mode / highlight tracking - -### Keyboard Layouts - -Fenrir supports two main keyboard layouts: - -- **Desktop Layout**: Uses numeric keypad for navigation (recommended for desktop users) -- **Laptop Layout**: Alternative bindings for keyboards without numeric keypad - -Configure in `/etc/fenrirscreenreader/settings/settings.conf` or your -user-local settings file: -```ini -[keyboard] -keyboard_layout=desktop # or 'laptop' -``` - -### First Time Setup - -1. **Enable Fenrir at boot**: - ```bash - sudo systemctl enable fenrir - ``` - -2. **Configure audio** (if needed): - - For PulseAudio: Run configure_pulse.sh script (see below) - - For PipeWire: Run configure_pipewire.sh script (see below) - -3. **Test speech**: - ```bash - # Test speech-dispatcher directly - sudo spd-say "Hello World" - ``` - -## Remote Control - -Fenrir includes a powerful remote control system that allows external applications and scripts to control Fenrir through Unix sockets or TCP connections. This is particularly useful for automation, integration with other applications, or providing alternative control methods. - -### Configuration - -Enable remote control in `/etc/fenrirscreenreader/settings/settings.conf` or -your user-local settings file: - -```ini -[remote] -enable=True -driver=unixDriver # or tcpDriver -port=22447 # for TCP driver -socket_file= # custom socket path (optional) -enable_settings_remote=True # allow settings changes -enable_command_remote=True # allow command execution -``` - -### Remote Drivers - -1. **unixDriver** (recommended): Uses Unix domain sockets - - Socket location: `/tmp/fenrirscreenreader-daemon.sock` for the standard control socket - - `fenrir -x` instances also create private sockets: `/tmp/fenrirscreenreader-.sock` - - More secure, local-only access - - Works with `socat` - -2. **tcpDriver**: Uses TCP sockets on localhost - - Default port: 22447 - - Works with `netcat`, `telnet`, or any TCP client - - Local connections only (127.0.0.1) - -### Using socat with Unix Sockets - -The `socat` command provides the easiest way to send commands to Fenrir: - -#### Instance Discovery ```bash -# List registered Fenrir instances and their socket paths echo "ls" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock ``` -In X terminal mode (`fenrir -x`), multiple Fenrir instances can run at the same -time. Each instance has a private socket, and one instance may also own the -standard control socket. Use `ls` or `command ls` on the standard socket to find -the private socket for a specific instance. Commands sent to the standard socket -are handled by its owner when possible; otherwise they are forwarded to a -registered private socket, preferring the sender's Fenrir ancestor when one can -be found. Untargeted commands sent through a shared or broadcast path are -claimed by one instance so duplicate instances do not all perform the same -action. +Send commands to a private socket when targeting a particular reader. Examples +using the standard socket: -#### Basic Speech Control ```bash -# Interrupt current speech +echo "command say Hello" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock echo "command interrupt" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Speak custom text -echo "command say Hello, this is a test message" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Temporarily disable speech (until next keystroke) -echo "command tempdisablespeech" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock +echo "setting set reading#mode=highlight" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock ``` -#### Settings Control -```bash -# Enable highlight tracking mode -echo "setting set focus#highlight=True" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock +Set `remote.enabled = false` to disable remote control. Command and settings +requests can also be enabled separately in the `[remote]` section. -# Change speech parameters -echo "setting set speech#rate=0.8" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -echo "setting set speech#pitch=0.6" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -echo "setting set speech#volume=0.9" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock +## Command-line help -# Change punctuation level (none/some/most/all) -echo "setting set general#punctuation_level=all" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -echo "setting set general#punctuation_level=none" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Voice and TTS engine control -echo "setting set speech#voice=en-us+f3" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -echo "setting set speech#module=espeak-ng" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Disable sound temporarily -echo "setting set sound#enabled=False" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -echo "setting set sound#volume=0.5" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Keyboard and input settings -echo "setting set keyboard#char_echo_mode=1" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -echo "setting set keyboard#word_echo=True" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Screen control (ignore specific TTYs) -echo "setting set screen#ignore_screen=1,2,3" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Multiple settings at once -echo "setting set speech#rate=0.8;sound#volume=0.7;general#punctuation_level=most" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Reset all settings to defaults -echo "setting reset" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Save current settings -echo "setting save" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -echo "setting saveas /tmp/my-fenrir-settings.conf" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -``` - -#### Clipboard Operations -```bash -# Place text into clipboard -echo "command clipboard This text will be copied to clipboard" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Export clipboard to file -echo "command exportclipboard" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -``` - -#### Window Management -```bash -# Define a window area (x1 y1 x2 y2) -echo "command window 0 0 80 24" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Reset window to full screen -echo "command resetwindow" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -``` - -#### VMenu Control -```bash -# Set virtual menu context -echo "command vmenu nano/file" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Reset virtual menu -echo "command resetvmenu" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -``` - -#### Application Control -```bash -# Quit Fenrir -echo "command quitapplication" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -``` - -### Using TCP Driver - -If using the TCP driver, replace socat commands with netcat: - -```bash -# Using netcat -echo "command say Hello from TCP" | nc localhost 22447 - -# Using telnet -echo "command interrupt" | telnet localhost 22447 -``` - -### Remote Command Reference - -#### Command Format -``` -command [parameters] -setting [parameters] -``` - -#### Available Commands - -**Speech Commands:** -- `command say ` - Speak the specified text -- `command interrupt` - Stop current speech -- `command tempdisablespeech` - Disable speech until next key press - -**Clipboard Commands:** -- `command clipboard ` - Add text to clipboard -- `command exportclipboard` - Export clipboard to file - -**Window Commands:** -- `command window ` - Define window area -- `command resetwindow` - Reset to full screen - -**VMenu Commands:** -- `command vmenu ` - Set vmenu context -- `command resetvmenu` - Reset vmenu - -**Application Commands:** -- `command quitapplication` - Quit Fenrir - -**Instance Commands:** -- `ls` / `list` / `command ls` / `command list` - List registered Fenrir instances and their socket paths - -#### Available Settings - -**Settings Commands:** -- `setting set
#=` - Set configuration value -- `setting reset` - Reset all settings to defaults -- `setting save [path]` - Save current settings -- `setting saveas ` - Save settings to specific file - -**Common Settings:** - -*Speech Settings:* -- `speech#enabled=True/False` - Enable/disable speech -- `speech#rate=0.1-1.0` - Speech rate (speed) -- `speech#pitch=0.1-1.0` - Speech pitch (tone) -- `speech#volume=0.1-1.0` - Speech volume -- `speech#voice=voice_name` - Voice selection (e.g., "en-us+f3") -- `speech#module=module_name` - TTS module (e.g., "espeak-ng") -- `speech#driver=driver_name` - Speech driver (speechdDriver/genericDriver/dectalkDriver/dectalkUsbDriver/litetalkDriver/doubletalkDriver/tripletalkDriver) -- `speech#hardware_device=/dev/ttyS0` - Hardware synth serial device for dectalkDriver/litetalkDriver -- `speech#hardware_baud_rate=9600` - Hardware synth serial baud rate -- `speech#history_size=50` - Number of spoken items kept in runtime speech history - -The native Access Solutions DECtalk USB, USB ID `0dd0:2001`, uses -`dectalkUsbDriver`. It is autodetected and does not use -`speech#hardware_device` or `speech#hardware_baud_rate`. Install PyUSB and a -libusb backend first. From a source checkout, use -`python3 -m pip install '.[dectalk_usb]'`; distributions may package PyUSB as -`python3-usb` or `python-pyusb`. Root-run Fenrir can access the device directly. -A non-root Fenrir process needs a local udev rule granting its account -read/write access to `0dd0:2001`; do not make the device world-writable. Other -USB hardware synths are supported only when Linux exposes them as a serial tty -such as `/dev/ttyACM0` or `/dev/ttyUSB0`. Use an explicit -`speech#hardware_device` path for serial hardware speech. -- `speech#auto_read_incoming=True/False` - Auto-read new text - -*Sound Settings:* -- `sound#enabled=True/False` - Enable/disable sound -- `sound#volume=0.1-1.0` - Sound volume -- `sound#driver=driver_name` - Sound driver (genericDriver/gstreamerDriver) -- `sound#theme=theme_name` - Sound theme - -*General Settings:* -- `general#punctuation_level=none/some/most/all` - Punctuation verbosity -- `general#debug_level=0-3` - Debug level -- `general#emoticons=True/False` - Enable emoticon replacement -- `general#auto_spell_check=True/False` - Automatic spell checking - -*Focus Settings:* -- `focus#cursor=True/False` - Follow text cursor -- `focus#highlight=True/False` - Follow text highlighting - -*Keyboard Settings:* -- `keyboard#char_echo_mode=0-2` - Character echo (0=none, 1=always, 2=capslock only) -- `keyboard#word_echo=True/False` - Echo complete words -- `keyboard#char_delete_echo=True/False` - Echo deleted characters -- `keyboard#interrupt_on_key_press=True/False` - Interrupt speech on key press - -*Screen Settings:* -- `screen#ignore_screen=1,2,3` - TTY screens to ignore -- `screen#autodetect_ignore_screen=True/False` - Auto-detect screens to ignore -- `screen#screen_update_delay=float` - Screen update delay - -*Time Settings:* -- `time#enabled=True/False` - Enable time announcements -- `time#present_time=True/False` - Announce time -- `time#present_date=True/False` - Announce date changes -- `time#delay_sec=seconds` - Announcement interval -- `time#on_minutes=00,30` - Specific minutes to announce - -## Table Navigation - -Fenrir includes advanced table navigation capabilities for working with tabular data in terminal applications, CSV files, and formatted text output. - -### Entering Table Mode - -Table mode is activated through the **toggle_highlight_tracking** command, which cycles through three focus modes: - -1. **Highlight tracking mode** (default) - Follows text highlighting -2. **Cursor tracking mode** - Follows text cursor movement -3. **Table mode** - Enables table navigation - -**Key bindings:** -- **Desktop layout**: `Fenrir + Keypad *` (asterisk) -- **Laptop layout**: `Fenrir + Y` - -Press the key combination repeatedly to cycle through modes until you hear "table mode enabled". - -### Table Navigation Commands - -#### Column Navigation (Desktop Layout) -- **Next column**: `Keypad 6` - Move to next table column -- **Previous column**: `Keypad 4` - Move to previous table column -- **First column**: `Fenrir + Keypad 4` - Jump to first column of current row -- **Last column**: `Fenrir + Keypad 6` - Jump to last column of current row - -#### Column Navigation (Laptop Layout) -- **Next column**: `Fenrir + L` - Move to next table column -- **Previous column**: `Fenrir + J` - Move to previous table column -- **First column**: `Fenrir + Shift + J` - Jump to first column of current row -- **Last column**: `Fenrir + Shift + L` - Jump to last column of current row - -#### Cell Character Navigation -- **First character in cell**: `Fenrir + Keypad 1` (desktop) or `Fenrir + Ctrl + J` (laptop) -- **Last character in cell**: `Fenrir + Keypad 3` (desktop) or `Fenrir + Ctrl + L` (laptop) - -### Setting Column Headers - -For better navigation experience, you can set column headers: - -1. **Navigate to header row**: Use normal navigation to reach the row containing column headers -2. **Set headers**: Press `Fenrir + X` to mark the current line as the header row -3. **Navigation feedback**: Column headers will be announced along with cell content - -### Table Detection - -Fenrir automatically detects table structures using multiple strategies: -- **Delimited text**: CSV, pipe-separated (`|`), semicolon-separated (`;`), tab-separated -- **Aligned columns**: Space-aligned columns (2+ spaces between columns) -- **Flexible parsing**: Handles various table formats commonly found in terminal applications - -### Table Mode Features - -- **Cell-by-cell navigation**: Navigate through table cells with precise positioning -- **Column header support**: Set and announce column headers for better context -- **Boundary feedback**: Audio cues when reaching start/end of rows -- **Empty cell handling**: Blank cells are announced as "blank" -- **Independent tracking**: Table position is maintained independently of cursor movement - -### Speech Output in Table Mode - -When navigating in table mode, Fenrir announces: -- **Cell content** followed by **column header/name** -- **Boundary notifications**: "end of line", "start of line" -- **Position indicators**: "first character in cell [column name]" - -### Example Usage - -```bash -# Working with CSV data -cat data.csv -Name,Age,City -Alice,30,New York -Bob,25,Los Angeles - -# 1. Press Fenrir + Keypad * until "table mode enabled" -# 2. Navigate to "Name,Age,City" line -# 3. Press Fenrir + X to set headers -# 4. Use Keypad 4/6 to navigate between columns -# 5. Each cell will be announced with its column header -``` - -## Progress Bar Monitoring - -Fenrir provides intelligent progress bar detection and audio feedback for various progress indicators commonly found in terminal applications. - -### Enabling Progress Monitoring - -**Command**: `progress_bar_monitor` (no default key binding - assign manually) - -To enable progress monitoring: -1. Add a key binding in your keyboard layout file -2. Or use the remote control system: `echo "command progress_bar_monitor" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock` - -### Progress Detection Patterns - -Fenrir automatically detects various progress indicator formats: - -#### 1. Percentage Progress -``` -Download: 45% -Processing: 67.5% -Installing: 100% -``` - -#### 2. Fraction Progress -``` -Files: 15/100 -Progress: 3 of 10 -Step 7/15 -``` - -#### 3. Progress Bars -``` -[#### ] 40% -[====> ] 50% -[**********] 100% -``` - -#### 4. Activity Indicators -``` -Loading... -Processing... -Working... -Installing... -Downloading... -Compiling... -Building... -``` - -### Audio Feedback - -#### Progress Tones -- **Ascending tones**: 400Hz to 1200Hz frequency range -- **Percentage mapping**: 0% = 400Hz, 100% = 1200Hz -- **Smooth progression**: Frequency increases proportionally with progress - -#### Activity Indicators -- **Steady beep**: 800Hz tone every 2 seconds for ongoing activity -- **Non-intrusive**: Beeps don't interrupt speech or other audio - -### Progress Monitoring Features - -- **Automatic detection**: No manual configuration required -- **Multiple format support**: Handles various progress indicator styles -- **Prompt awareness**: Automatically pauses when command prompts are detected -- **Non-blocking**: Progress tones don't interrupt speech or other functionality -- **Configurable**: Can be enabled/disabled as needed - -Fenrir detects stable progress structures rather than application-specific -status formats. Application-specific formats change too frequently to support -reliably. - -### Usage Examples - -```bash -# Enable progress monitoring -echo "command progress_bar_monitor" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Common scenarios where progress monitoring is useful: -wget https://example.com/large-file.zip # Download progress -tar -xvf archive.tar.gz # Extraction progress -make -j4 # Compilation progress -pacman -S package # Package installation -rsync -av source/ destination/ # File synchronization -``` - -### Customization - -Progress monitoring can be configured through settings: -- **Default enabled**: Set `progress_monitoring=True` in sound section -- **Sound integration**: Works with all sound drivers (sox, gstreamer) -- **Remote control**: Enable/disable through remote commands - -### Scripting Examples - -#### Bash Script for Speech Notifications -```bash -#!/bin/bash -# notify_fenrir.sh - Send notifications to Fenrir - -SOCKET="/tmp/fenrirscreenreader-daemon.sock" - -fenrir_say() { - echo "command say $1" | socat - UNIX-CLIENT:$SOCKET -} - -fenrir_interrupt() { - echo "command interrupt" | socat - UNIX-CLIENT:$SOCKET -} - -# Usage examples -fenrir_say "Build completed successfully" -fenrir_interrupt -``` - -#### Python Integration -```python -#!/usr/bin/env python3 -import socket -import os - -def send_fenrir_command(command): - """Send command to Fenrir via Unix socket""" - socket_path = "/tmp/fenrirscreenreader-daemon.sock" - if os.path.exists(socket_path): - sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) - try: - sock.connect(socket_path) - sock.send(command.encode('utf-8')) - finally: - sock.close() - -# Examples -send_fenrir_command("command say Processing complete") -send_fenrir_command("setting set speech#rate=0.9") -``` - -### Security Considerations - -- Unix sockets are accessible only to the user running Fenrir -- TCP driver binds only to localhost (127.0.0.1) -- Socket file permissions are set to write-only (0o222) -- Commands are processed with Fenrir's privileges -- Settings changes can be disabled via `enable_settings_remote=False` -- Command execution can be disabled via `enable_command_remote=False` - -### Troubleshooting - -**Socket not found:** -- Verify Fenrir is running: `ps aux | grep fenrir` -- Check socket location: `/tmp/fenrirscreenreader-*` -- Ensure remote driver is enabled in settings - -**Commands not working:** -- Verify `enable_command_remote=True` in settings -- Check Fenrir debug logs: `/tmp/fenrir.log` -- Test with simple command: `echo "command interrupt" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock` - -## Command Line Options - -Fenrir supports several command-line options for different use cases: - -``` -fenrir [OPTIONS] -``` - -### Options: -- `-h, --help` - Show help message and exit -- `-v, --version` - Show version information and exit -- `-f, --foreground` - Run in foreground (don't daemonize) -- `-s, --setting SETTING-FILE` - Path to custom settings file -- `-o, --options SECTION#SETTING=VALUE;..` - Override settings file options -- `-d, --debug` - Enable debug mode -- `-p, --print` - Print debug messages to screen -- `-x, --x11` - Use PTY emulation with X11 keyboard input scoped to the terminal window -- `--x11-window-id WINDOWID` - X11 window id to use for `--x11` terminal mode -- `-F, --force-all-screens` - Force Fenrir to respond on all screens, ignoring ignore_screen setting -- `-i, -I, --ignore-screen SCREEN` - Ignore specific screen(s). Can be used multiple times. Combines with existing ignore settings. - -### Examples: -```bash -# Run in foreground with debug output -sudo fenrir -f -d - -# Use PTY emulation with X11 terminal-scoped keybindings -fenrir -x - -# Use X11 mode with an explicit terminal window id -fenrir -x --x11-window-id 0x123456 - -# Override settings via command line -sudo fenrir -o "speech#rate=0.8;sound#volume=0.5" - -# Force Fenrir to work on all screens (ignore ignore_screen setting) -sudo fenrir -F - -# Ignore specific screens -sudo fenrir --ignore-screen 1 -sudo fenrir -i 1 -i 2 # Ignore screens 1 and 2 -``` - -### X11 Terminal Mode - -`fenrir -x` runs Fenrir inside a GUI terminal without root. It uses the PTY screen driver for terminal contents and the X11 input driver for Fenrir keybindings. Unlike evdev mode, it does not listen to the whole desktop; key grabs are scoped to the target terminal window so desktop screen readers can keep their own global bindings outside that terminal. - -By default, Fenrir targets the X11 window from `WINDOWID`, falling back to the active X11 window. If a terminal does not set `WINDOWID`, pass the window explicitly with `--x11-window-id`. - -X11 terminal mode uses the normal keyboard layout files, including desktop and laptop bindings. It supports Fenrir keys such as numpad Insert/`KEY_KP0`, CapsLock/`KEY_CAPSLOCK`, Insert/`KEY_INSERT`, and Super/Windows/`KEY_META`. Script keys such as Compose use `KEY_COMPOSE`. - -In this mode Fenrir runs as a regular user. Settings are loaded from -`~/.local/share/stormux/fenrirscreenreader/settings/settings.conf` when present, -otherwise from `/etc/fenrirscreenreader/settings/settings.conf`; saving settings -creates or updates the user-local file. User sound themes and scripts are read -first from `~/.local/stormux/fenrir/sounds/` and `~/.local/stormux/fenrir/`. - -This mode requires `python-xlib`. - -For users who want a dedicated PTY/terminal screen reader instead of Fenrir's Linux console focus, see TDSR: https://github.com/tspivey/tdsr +Run `./fenrir --help` for all options. Useful options include `--config`, +`--keyboard-layout`, `--punctuation-profile`, `--speech-driver`, `--speech-rate`, +`--speech-module`, `--input-device`, and `--debug-file`. `--version` prints the +version and release channel. Fenrir runs in the foreground. ## Localization -Fenrir's announcements and help text use GNU gettext. The message template is -`tools/fenrir.pot`; contributors maintain translations in `locale/` as `.po` -files. Compiled `fenrir.mo` files are installed by both `setup.py` and `install.sh`. Fenrir selects its interface language from `LANGUAGE`, `LC_ALL`, `LC_MESSAGES`, -or `LANG` at startup. The `[speech] language` setting controls synthesis, not -the interface language. Messages without a translation fall back to English. +or `LANG`. The speech language setting controls synthesis separately. +Translations are bundled from [internal/i18n/locale](internal/i18n/locale); +missing translations fall back to English. -Install GNU gettext to use the maintenance tool. Run these commands from the -checkout root; the tool itself also works from other working directories: +The translation tool extracts Go messages and validates catalogs. With GNU +gettext installed, run this read-only check from the checkout root: ```bash -# Refresh only the template; leave every language catalog untouched. -./tools/generate_translations.sh - -# Check template freshness and validate catalogs without changing files. -./tools/generate_translations.sh check - -# Translator workflow: merge new messages into one catalog. -./tools/generate_translations.sh update locale/de/LC_MESSAGES/fenrir.po -# Translate empty entries and review fuzzy entries in your PO editor. -./tools/generate_translations.sh check locale/de/LC_MESSAGES/fenrir.po -./tools/generate_translations.sh compile locale/de/LC_MESSAGES/fenrir.po +go run ./tools/translations check ``` -`update` requires explicit catalog paths and preserves existing translations -for review. `compile` with no paths builds all catalogs after validating them. -Catalog paths are relative to your current working directory. Neither operation -installs anything or requires root. To start a new language, run `msginit` with -the template and create its catalog under `locale/LANGUAGE/LC_MESSAGES/`. +## Development -Developers should translate complete messages before formatting values: -`_("Loading voices for {module}").format(module=module)`. Do not pass an f-string -or an already formatted sentence to `_()`. Keep placeholders intact in -translations, use `ngettext()` for counts, and leave application contents, -clipboard data, filenames, and configuration identifiers unchanged. The tool -also extracts built-in menu labels, key names, and color names that are looked -up dynamically. Custom profiles must supply their own translated descriptions -and catalogs. - -To install a compiled catalog manually: +Run the Go tests from the checkout root: ```bash -# Copy translation file to system location -sudo install -m644 -D locale/your_language/LC_MESSAGES/fenrir.mo /usr/share/locale/your_language/LC_MESSAGES/fenrir.mo +go test ./... ``` -Available languages: -- German (de) -- Spanish (es) -- Polish (pl) -- Portuguese (pt) -- Russian (ru) +Device-free checks do not establish audible speech or real keyboard behavior. +Test changes affecting input, speech, or menus in the affected console or X11 +workflow as well. ## AI-assisted contributions @@ -905,9 +270,12 @@ For email patches, assistants should offer guidance with configuring `git format-patch`, reviewing the generated patch, sending a test message when appropriate, and sending the final patches to the contribution address. -## Documentation and Support +## Support and license -- **Email list**: [stormux+subscribe@groups.io](mailto:stormux+subscribe@groups.io?subject=subscribe) with the subject subscribe -- **Fenrir Wiki**: [https://git.stormux.org/storm/fenrir/wiki](https://git.stormux.org/storm/fenrir/wiki) -- **IRC**: irc.stormux.org #stormux -- **Issues**: Report bugs and feature requests on the project repository +- [Project repository and issue tracker](https://git.stormux.org/storm/fenrir) +- [Fenrir Wiki](https://git.stormux.org/storm/fenrir/wiki) +- Email list: [stormux+subscribe@groups.io](mailto:stormux+subscribe@groups.io?subject=subscribe) + with the subject `subscribe`. +- IRC: `irc.stormux.org`, channel `#stormux`. + +The Go code is licensed under the GNU GPL, version 3 or later. See [LICENSE](LICENSE). diff --git a/config/keyboard/Readme.md b/config/keyboard/Readme.md index 986bdd1b..5f5ed971 100644 --- a/config/keyboard/Readme.md +++ b/config/keyboard/Readme.md @@ -1,588 +1,83 @@ +# Fenrir keyboard layouts -# Fenrir Keyboard Configuration +Both Linux console and X11 terminal modes use the TOML layouts in this directory: -This directory contains keyboard layout files for Fenrir screen reader. +- [desktop.toml](desktop.toml): numeric keypad review, with NumLock off. +- [laptop.toml](laptop.toml): review chords on the main keyboard. -## Available Layouts +The Fenrir key is Insert, Super/Windows, or keypad 0 with NumLock off. -- **desktop.conf** - Desktop layout using numeric keypad (recommended) -- **laptop.conf** - Laptop layout for keyboards without numeric keypad +## Selecting and customizing a layout -## Key Features +Select a layout at launch: -### Table Navigation -- **Toggle table mode**: `Fenrir + Keypad *` (desktop) or `Fenrir + Y` (laptop) -- **Column navigation**: `Keypad 4/6` (desktop) or `Fenrir + J/L` (laptop) -- **Row boundaries**: `Fenrir + Keypad 4/6` (desktop) or `Fenrir + Shift + J/L` (laptop) -- **Set headers**: `Fenrir + X` in table mode - -### Progress Bar Monitoring -- **Monitor progress**: `progress_bar_monitor` command (assign key binding manually) -- **Auto-detection**: Percentage, fractions, progress bars, activity indicators -- **Audio feedback**: Ascending tones (400Hz-1200Hz) for progress - -### Review Mode -- **Basic navigation**: `Keypad 7/8/9` (lines), `Keypad 4/5/6` (words), `Keypad 1/2/3` (characters) -- **Exit review**: `Fenrir + Keypad .` -- **Screen reading**: `Fenrir + Keypad 5` (current screen) - -### Speech History -- **Open speech history**: `Fenrir + Ctrl + H` -- **Navigate history**: `Up` and `Down` -- **Copy current item**: `Enter` -- **Exit speech history**: `Escape` - -## Configuration - -To change keyboard layout, edit `/etc/fenrirscreenreader/settings/settings.conf` -or your user-local settings file at -`~/.local/share/stormux/fenrirscreenreader/settings/settings.conf`: - -```ini -[keyboard] -keyboard_layout=desktop # or laptop +```bash +./fenrir --keyboard-layout laptop +./fenrir -x --keyboard-layout /path/to/custom.toml ``` -## Available Key Constants +Or set the startup choice in `settings.toml`: -Keymap for Fenrir -KEY_RESERVED -KEY_ESC -KEY_1 -KEY_2 -KEY_3 -KEY_4 -KEY_5 -KEY_6 -KEY_7 -KEY_8 -KEY_9 -KEY_0 -KEY_MINUS -KEY_EQUAL -KEY_BACKSPACE -KEY_TAB -KEY_Q -KEY_W -KEY_E -KEY_R -KEY_T -KEY_Y -KEY_U -KEY_I -KEY_O -KEY_P -KEY_LEFTBRACE -KEY_RIGHTBRACE -KEY_ENTER -KEY_LEFTCTRL -KEY_A -KEY_S -KEY_D -KEY_F -KEY_G -KEY_H -KEY_J -KEY_K -KEY_L -KEY_SEMICOLON -KEY_APOSTROPHE -KEY_GRAVE -KEY_LEFTSHIFT -KEY_BACKSLASH -KEY_Z -KEY_X -KEY_C -KEY_V -KEY_B -KEY_N -KEY_M -KEY_COMMA -KEY_DOT -KEY_SLASH -KEY_RIGHTSHIFT -KEY_KPASTERISK -KEY_LEFTALT -KEY_SPACE -KEY_CAPSLOCK -KEY_F1 -KEY_F2 -KEY_F3 -KEY_F4 -KEY_F5 -KEY_F6 -KEY_F7 -KEY_F8 -KEY_F9 -KEY_F10 -KEY_NUMLOCK -KEY_SCROLLLOCK -KEY_KP7 -KEY_KP8 -KEY_KP9 -KEY_KPMINUS -KEY_KP4 -KEY_KP5 -KEY_KP6 -KEY_KPPLUS -KEY_KP1 -KEY_KP2 -KEY_KP3 -KEY_KP0 -KEY_KPDOT -KEY_ZENKAKUHANKAKU -KEY_102ND -KEY_F11 -KEY_F12 -KEY_RO -KEY_KATAKANA -KEY_HIRAGANA -KEY_HENKAN -KEY_KATAKANAHIRAGANA -KEY_MUHENKAN -KEY_KPJPCOMMA -KEY_KPENTER -KEY_RIGHTCTRL -KEY_KPSLASH -KEY_SYSRQ -KEY_RIGHTALT -KEY_LINEFEED -KEY_HOME -KEY_UP -KEY_PAGEUP -KEY_LEFT -KEY_RIGHT -KEY_END -KEY_DOWN -KEY_PAGEDOWN -KEY_INSERT -KEY_DELETE -KEY_MACRO -['KEY_MIN_INTERESTING', 'KEY_MUTE'] -KEY_VOLUMEDOWN -KEY_VOLUMEUP -KEY_POWER -KEY_KPEQUAL -KEY_KPPLUSMINUS -KEY_PAUSE -KEY_SCALE -KEY_KPCOMMA -['KEY_HANGEUL', 'KEY_HANGUEL'] -KEY_HANJA -KEY_YEN -KEY_LEFTMETA -KEY_RIGHTMETA -KEY_COMPOSE -KEY_STOP -KEY_AGAIN -KEY_PROPS -KEY_UNDO -KEY_FRONT -KEY_COPY -KEY_OPEN -KEY_PASTE -KEY_FIND -KEY_CUT -KEY_HELP -KEY_MENU -KEY_CALC -KEY_SETUP -KEY_SLEEP -KEY_WAKEUP -KEY_FILE -KEY_SENDFILE -KEY_DELETEFILE -KEY_XFER -KEY_PROG1 -KEY_PROG2 -KEY_WWW -KEY_MSDOS -['KEY_COFFEE', 'KEY_SCREENLOCK'] -['KEY_DIRECTION', 'KEY_ROTATE_DISPLAY'] -KEY_CYCLEWINDOWS -KEY_MAIL -KEY_BOOKMARKS -KEY_COMPUTER -KEY_BACK -KEY_FORWARD -KEY_CLOSECD -KEY_EJECTCD -KEY_EJECTCLOSECD -KEY_NEXTSONG -KEY_PLAYPAUSE -KEY_PREVIOUSSONG -KEY_STOPCD -KEY_RECORD -KEY_REWIND -KEY_PHONE -KEY_ISO -KEY_CONFIG -KEY_HOMEPAGE -KEY_REFRESH -KEY_EXIT -KEY_MOVE -KEY_EDIT -KEY_SCROLLUP -KEY_SCROLLDOWN -KEY_KPLEFTPAREN -KEY_KPRIGHTPAREN -KEY_NEW -KEY_REDO -KEY_F13 -KEY_F14 -KEY_F15 -KEY_F16 -KEY_F17 -KEY_F18 -KEY_F19 -KEY_F20 -KEY_F21 -KEY_F22 -KEY_F23 -KEY_F24 -KEY_PLAYCD -KEY_PAUSECD -KEY_PROG3 -KEY_PROG4 -KEY_DASHBOARD -KEY_SUSPEND -KEY_CLOSE -KEY_PLAY -KEY_FASTFORWARD -KEY_BASSBOOST -KEY_PRINT -KEY_HP -KEY_CAMERA -KEY_SOUND -KEY_QUESTION -KEY_EMAIL -KEY_CHAT -KEY_SEARCH -KEY_CONNECT -KEY_FINANCE -KEY_SPORT -KEY_SHOP -KEY_ALTERASE -KEY_CANCEL -KEY_BRIGHTNESSDOWN -KEY_BRIGHTNESSUP -KEY_MEDIA -KEY_SWITCHVIDEOMODE -KEY_KBDILLUMTOGGLE -KEY_KBDILLUMDOWN -KEY_KBDILLUMUP -KEY_SEND -KEY_REPLY -KEY_FORWARDMAIL -KEY_SAVE -KEY_DOCUMENTS -KEY_BATTERY -KEY_BLUETOOTH -KEY_WLAN -KEY_UWB -KEY_UNKNOWN -KEY_VIDEO_NEXT -KEY_VIDEO_PREV -KEY_BRIGHTNESS_CYCLE -['KEY_BRIGHTNESS_AUTO', 'KEY_BRIGHTNESS_ZERO'] -KEY_DISPLAY_OFF -['KEY_WIMAX', 'KEY_WWAN'] -KEY_RFKILL -KEY_MICMUTE -['BTN_0', 'BTN_MISC'] -BTN_1 -BTN_2 -BTN_3 -BTN_4 -BTN_5 -BTN_6 -BTN_7 -BTN_8 -BTN_9 -['BTN_LEFT', 'BTN_MOUSE'] -BTN_RIGHT -BTN_MIDDLE -BTN_SIDE -BTN_EXTRA -BTN_FORWARD -BTN_BACK -BTN_TASK -['BTN_JOYSTICK', 'BTN_TRIGGER'] -BTN_THUMB -BTN_THUMB2 -BTN_TOP -BTN_TOP2 -BTN_PINKIE -BTN_BASE -BTN_BASE2 -BTN_BASE3 -BTN_BASE4 -BTN_BASE5 -BTN_BASE6 -BTN_DEAD -['BTN_A', 'BTN_GAMEPAD', 'BTN_SOUTH'] -['BTN_B', 'BTN_EAST'] -BTN_C -['BTN_NORTH', 'BTN_X'] -['BTN_WEST', 'BTN_Y'] -BTN_Z -BTN_TL -BTN_TR -BTN_TL2 -BTN_TR2 -BTN_SELECT -BTN_START -BTN_MODE -BTN_THUMBL -BTN_THUMBR -['BTN_DIGI', 'BTN_TOOL_PEN'] -BTN_TOOL_RUBBER -BTN_TOOL_BRUSH -BTN_TOOL_PENCIL -BTN_TOOL_AIRBRUSH -BTN_TOOL_FINGER -BTN_TOOL_MOUSE -BTN_TOOL_LENS -BTN_TOOL_QUINTTAP -BTN_TOUCH -BTN_STYLUS -BTN_STYLUS2 -BTN_TOOL_DOUBLETAP -BTN_TOOL_TRIPLETAP -BTN_TOOL_QUADTAP -['BTN_GEAR_DOWN', 'BTN_WHEEL'] -BTN_GEAR_UP -KEY_OK -KEY_SELECT -KEY_GOTO -KEY_CLEAR -KEY_POWER2 -KEY_OPTION -KEY_INFO -KEY_TIME -KEY_VENDOR -KEY_ARCHIVE -KEY_PROGRAM -KEY_CHANNEL -KEY_FAVORITES -KEY_EPG -KEY_PVR -KEY_MHP -KEY_LANGUAGE -KEY_TITLE -KEY_SUBTITLE -KEY_ANGLE -KEY_ZOOM -KEY_MODE -KEY_KEYBOARD -KEY_SCREEN -KEY_PC -KEY_TV -KEY_TV2 -KEY_VCR -KEY_VCR2 -KEY_SAT -KEY_SAT2 -KEY_CD -KEY_TAPE -KEY_RADIO -KEY_TUNER -KEY_PLAYER -KEY_TEXT -KEY_DVD -KEY_AUX -KEY_MP3 -KEY_AUDIO -KEY_VIDEO -KEY_DIRECTORY -KEY_LIST -KEY_MEMO -KEY_CALENDAR -KEY_RED -KEY_GREEN -KEY_YELLOW -KEY_BLUE -KEY_CHANNELUP -KEY_CHANNELDOWN -KEY_FIRST -KEY_LAST -KEY_AB -KEY_NEXT -KEY_RESTART -KEY_SLOW -KEY_SHUFFLE -KEY_BREAK -KEY_PREVIOUS -KEY_DIGITS -KEY_TEEN -KEY_TWEN -KEY_VIDEOPHONE -KEY_GAMES -KEY_ZOOMIN -KEY_ZOOMOUT -KEY_ZOOMRESET -KEY_WORDPROCESSOR -KEY_EDITOR -KEY_SPREADSHEET -KEY_GRAPHICSEDITOR -KEY_PRESENTATION -KEY_DATABASE -KEY_NEWS -KEY_VOICEMAIL -KEY_ADDRESSBOOK -KEY_MESSENGER -['KEY_BRIGHTNESS_TOGGLE', 'KEY_DISPLAYTOGGLE'] -KEY_SPELLCHECK -KEY_LOGOFF -KEY_DOLLAR -KEY_EURO -KEY_FRAMEBACK -KEY_FRAMEFORWARD -KEY_CONTEXT_MENU -KEY_MEDIA_REPEAT -KEY_10CHANNELSUP -KEY_10CHANNELSDOWN -KEY_IMAGES -KEY_DEL_EOL -KEY_DEL_EOS -KEY_INS_LINE -KEY_DEL_LINE -KEY_FN -KEY_FN_ESC -KEY_FN_F1 -KEY_FN_F2 -KEY_FN_F3 -KEY_FN_F4 -KEY_FN_F5 -KEY_FN_F6 -KEY_FN_F7 -KEY_FN_F8 -KEY_FN_F9 -KEY_FN_F10 -KEY_FN_F11 -KEY_FN_F12 -KEY_FN_1 -KEY_FN_2 -KEY_FN_D -KEY_FN_E -KEY_FN_F -KEY_FN_S -KEY_FN_B -KEY_BRL_DOT1 -KEY_BRL_DOT2 -KEY_BRL_DOT3 -KEY_BRL_DOT4 -KEY_BRL_DOT5 -KEY_BRL_DOT6 -KEY_BRL_DOT7 -KEY_BRL_DOT8 -KEY_BRL_DOT9 -KEY_BRL_DOT10 -KEY_NUMERIC_0 -KEY_NUMERIC_1 -KEY_NUMERIC_2 -KEY_NUMERIC_3 -KEY_NUMERIC_4 -KEY_NUMERIC_5 -KEY_NUMERIC_6 -KEY_NUMERIC_7 -KEY_NUMERIC_8 -KEY_NUMERIC_9 -KEY_NUMERIC_STAR -KEY_NUMERIC_POUND -KEY_NUMERIC_A -KEY_NUMERIC_B -KEY_NUMERIC_C -KEY_NUMERIC_D -KEY_CAMERA_FOCUS -KEY_WPS_BUTTON -KEY_TOUCHPAD_TOGGLE -KEY_TOUCHPAD_ON -KEY_TOUCHPAD_OFF -KEY_CAMERA_ZOOMIN -KEY_CAMERA_ZOOMOUT -KEY_CAMERA_UP -KEY_CAMERA_DOWN -KEY_CAMERA_LEFT -KEY_CAMERA_RIGHT -KEY_ATTENDANT_ON -KEY_ATTENDANT_OFF -KEY_ATTENDANT_TOGGLE -KEY_LIGHTS_TOGGLE -BTN_DPAD_UP -BTN_DPAD_DOWN -BTN_DPAD_LEFT -BTN_DPAD_RIGHT -KEY_ALS_TOGGLE -KEY_BUTTONCONFIG -KEY_TASKMANAGER -KEY_JOURNAL -KEY_CONTROLPANEL -KEY_APPSELECT -KEY_SCREENSAVER -KEY_VOICECOMMAND -KEY_BRIGHTNESS_MIN -KEY_BRIGHTNESS_MAX -KEY_KBDINPUTASSIST_PREV -KEY_KBDINPUTASSIST_NEXT -KEY_KBDINPUTASSIST_PREVGROUP -KEY_KBDINPUTASSIST_NEXTGROUP -KEY_KBDINPUTASSIST_ACCEPT -KEY_KBDINPUTASSIST_CANCEL -KEY_RIGHT_UP -KEY_RIGHT_DOWN -KEY_LEFT_UP -KEY_LEFT_DOWN -KEY_ROOT_MENU -KEY_MEDIA_TOP_MENU -KEY_NUMERIC_11 -KEY_NUMERIC_12 -KEY_AUDIO_DESC -KEY_3D_MODE -KEY_NEXT_FAVORITE -KEY_STOP_RECORD -KEY_PAUSE_RECORD -KEY_VOD -KEY_UNMUTE -['KEY_DATA', 'KEY_FASTREVERSE'] -KEY_SLOWREVERSE -['BTN_TRIGGER_HAPPY', 'BTN_TRIGGER_HAPPY1'] -BTN_TRIGGER_HAPPY2 -BTN_TRIGGER_HAPPY3 -BTN_TRIGGER_HAPPY4 -BTN_TRIGGER_HAPPY5 -BTN_TRIGGER_HAPPY6 -BTN_TRIGGER_HAPPY7 -BTN_TRIGGER_HAPPY8 -BTN_TRIGGER_HAPPY9 -BTN_TRIGGER_HAPPY10 -BTN_TRIGGER_HAPPY11 -BTN_TRIGGER_HAPPY12 -BTN_TRIGGER_HAPPY13 -BTN_TRIGGER_HAPPY14 -BTN_TRIGGER_HAPPY15 -BTN_TRIGGER_HAPPY16 -BTN_TRIGGER_HAPPY17 -BTN_TRIGGER_HAPPY18 -BTN_TRIGGER_HAPPY19 -BTN_TRIGGER_HAPPY20 -BTN_TRIGGER_HAPPY21 -BTN_TRIGGER_HAPPY22 -BTN_TRIGGER_HAPPY23 -BTN_TRIGGER_HAPPY24 -BTN_TRIGGER_HAPPY25 -BTN_TRIGGER_HAPPY26 -BTN_TRIGGER_HAPPY27 -BTN_TRIGGER_HAPPY28 -BTN_TRIGGER_HAPPY29 -BTN_TRIGGER_HAPPY30 -BTN_TRIGGER_HAPPY31 -BTN_TRIGGER_HAPPY32 -BTN_TRIGGER_HAPPY33 -BTN_TRIGGER_HAPPY34 -BTN_TRIGGER_HAPPY35 -BTN_TRIGGER_HAPPY36 -BTN_TRIGGER_HAPPY37 -BTN_TRIGGER_HAPPY38 -BTN_TRIGGER_HAPPY39 -BTN_TRIGGER_HAPPY40 +```toml +[keyboard] +layout = "laptop" +``` + +For a named layout, Fenrir searches the regular user's +`~/.local/share/stormux/fenrirscreenreader/keyboard/`, then +`/etc/fenrirscreenreader/keyboard/`, then `config/keyboard/` beside the binary. +Root searches the system and bundled locations. The first existing layout is +loaded as a complete file; layouts are not merged. Copy a bundled layout as the +starting point for customization. Layout changes apply on the next launch. + +Each binding has a label, a key chord, and a command ID: + +```toml +version = 1 + +[[bindings]] +name = "Current word" +keys = ["FENRIR", "K"] +command = "current_word" +double_command = "spell_word" +triple_command = "phonetic_word" +``` + +This is a minimal example, not a complete replacement layout. Optional double +and triple commands run on successive quick presses of the same chord; a +triple command requires a double command. The default multi-press interval is +200 ms, configured by `keyboard.multi_press_timeout_ms`. + +Put modifiers (`FENRIR`, `CTRL`, `SHIFT`, `ALT`) before the final key. +Use key names from the bundled layouts, such as `SPACE`, `RIGHT`, `KP8`, and +`KPASTERISK`. Chords outside the bare review keypad keys require `FENRIR`. +Unsupported keys, unknown commands, and duplicate chords are rejected. + +Validate a custom layout without opening devices: + +```bash +./fenrir --keyboard-layout /path/to/custom.toml --check-config +``` + +## Common shortcuts + +| Action | Desktop | Laptop | +| --- | --- | --- | +| Previous / current / next line | Keypad 7 / 8 / 9 | Fenrir+U / I / O | +| Previous / current / next word | Keypad 4 / 5 / 6 | Fenrir+J / K / L | +| Previous / current / next character | Keypad 1 / 2 / 3 | Fenrir+M / Comma / Period | +| Read screen | Fenrir+Keypad 5 | Fenrir+Shift+K | +| Follow cursor | Fenrir+Keypad Period | Fenrir+Slash | +| Cycle cursor / table / highlight tracking | Fenrir+Keypad Asterisk | Fenrir+Y | +| Toggle progress tones | Keypad Plus | Fenrir+Shift+P | +| Set reading window; double press to clear | Fenrir+Keypad Slash | Fenrir+Control+8 | + +Both layouts use **Fenrir+F** for settings, **Fenrir+H** or **Fenrir+F1** for +the tutorial, and **Fenrir+Control+S** to save settings. The tutorial describes +loaded shortcuts and lets you browse unbound commands. + +In table mode, word navigation moves between cells. **Fenrir+X** selects the +current row as headers. Outside table mode it places a text-selection mark. + +See the [user manual](../../docs/user.md) for clipboard, reading-region, +spellcheck, and menu workflows. diff --git a/docs/Howto Configure Pulse Systemwide.txt b/docs/Howto Configure Pulse Systemwide.txt index 3893d21b..492aca15 100644 --- a/docs/Howto Configure Pulse Systemwide.txt +++ b/docs/Howto Configure Pulse Systemwide.txt @@ -1 +1,28 @@ -https://rudd-o.com/linux-and-free-software/how-to-make-pulseaudio-run-once-at-boot-for-all-your-users +Fenrir console audio + +Fenrir's pulse sound driver uses PulseAudio or PipeWire's PulseAudio service. +The alsa driver opens the configured ALSA PCM device directly. Speech Dispatcher +has its own synthesis and audio configuration, separate from Fenrir's sound cues. + +For an X11 terminal session, start Fenrir as the regular user with ./fenrir -x. +For console mode started through sudo, Fenrir uses SUDO_UID to find the invoking +user's PulseAudio and Speech Dispatcher sockets. An explicit PULSE_SERVER takes +precedence for sound cues; SPEECHD_ADDRESS with a unix_socket: address takes +precedence for Speech Dispatcher. The relevant services must already be running +and accessible to the reader process. + +If root sound still needs separate configuration, the checkout includes + tools/configure_pulse.sh for PulseAudio and + tools/configure_pipewire.sh for PipeWire. +Read the appropriate script before running it. Each has a regular-user part +and a root part, and writes audio configuration files. The PulseAudio script +replaces the user's default.pa and configures an anonymously accessible socket +at /tmp/pulse.sock. The PipeWire script also changes WirePlumber settings. +These are system audio changes, not prerequisites for every Fenrir session. + +For ALSA, select driver = "alsa" under [presentation.sound] in settings.toml +and set device to the desired PCM name, such as "default". Driver and device +changes apply at the next launch. + +See README.md for build and startup instructions and docs/user.md for the Sound +settings and troubleshooting sections. diff --git a/docs/create_manpage.sh b/docs/create_manpage.sh index cf775a3a..13d3620a 100755 --- a/docs/create_manpage.sh +++ b/docs/create_manpage.sh @@ -1,13 +1,28 @@ #!/usr/bin/env bash -# needs pandoc and php installed +set -euo pipefail -# remove old files -rm fenrir.1 -rm user.md +docsDir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" -# convert to markdown -php DokuWiki-to-Markdown-Converter/convert.php user.txt +if ! command -v pandoc >/dev/null 2>&1; then + echo "Pandoc is required to generate the manuals." >&2 + exit 1 +fi -# convert markdown to manpage -pandoc user.md -f markdown -t man -s -o fenrir.1 +tempDir="$(mktemp -d "$docsDir/.manuals.XXXXXX")" +trap 'rm -rf -- "$tempDir"' EXIT + +# Generate every format successfully before replacing any existing output. +pandoc "$docsDir/user.md" --from markdown --to plain --wrap=auto \ + | sed 's/[[:blank:]]*$//' > "$tempDir/user.txt" +pandoc "$docsDir/user.md" --from markdown --to asciidoc --wrap=auto \ + --output "$tempDir/fenrir.adoc" +pandoc "$docsDir/user.md" --from markdown --to man --standalone \ + --lua-filter "$docsDir/man_tables.lua" \ + --metadata title=fenrir --metadata section=1 \ + --metadata header="Fenrir User Manual" \ + --output "$tempDir/fenrir.1" + +for manualFile in user.txt fenrir.adoc fenrir.1; do + mv -- "$tempDir/$manualFile" "$docsDir/$manualFile" +done diff --git a/docs/diff_review_mode.md b/docs/diff_review_mode.md deleted file mode 100644 index 925a38df..00000000 --- a/docs/diff_review_mode.md +++ /dev/null @@ -1,48 +0,0 @@ -# Diff Review Mode - -Diff review mode provides read-only navigation for unified and classic diff files with speech-first output. - -## Quick Workflow - -1. Copy the full absolute path of a diff file to the Fenrir clipboard. -2. Press `Fenrir + Ctrl + D` to toggle diff mode on. -3. Review the diff using the keys below. -4. Press `Esc` to leave diff mode. - -If the clipboard does not contain a full absolute file path, Fenrir announces an error and does not enter diff mode. - -## Keys (Active Only In Diff Mode) - -- `h` - Next hunk -- `Shift + h` - Previous hunk -- `f` - Next file section -- `Shift + f` - Previous file section -- `a` - Next added line -- `Shift + a` - Previous added line -- `d` - Next removed line -- `Shift + d` - Previous removed line -- `Up` - Previous line -- `Down` - Next line -- `Left` - Previous character -- `Right` - Next character -- `Ctrl + Left` - Previous word -- `Ctrl + Right` - Next word -- `s` - Diff summary -- `F1` - Speak key help -- `Esc` - Exit diff mode - -## Speech Behavior - -- Added and removed content is spoken as `Added:` and `Removed:` lines. -- Marker-only lines are normalized for speech: - - `+++` is spoken as `added` - - `---` is spoken as `removed` -- Classic diff markers are spoken in plain language: - - `17c17` -> `line 17 changed` - - `17d16` -> `line 17 deleted` - - `16a17` -> `line 17 added` - -## Notes - -- Diff mode is read-only and does not modify the diff file. -- Normal Fenrir key bindings are restored when diff mode exits. diff --git a/docs/fenrir.1 b/docs/fenrir.1 index 142d1d85..6cc98d8a 100644 --- a/docs/fenrir.1 +++ b/docs/fenrir.1 @@ -1,566 +1,674 @@ -.TH FENRIR 1 "2025" "Fenrir Screen Reader" "User Commands" -.SH NAME -fenrir \- A modern, modular console screen reader for Linux - -.SH SYNOPSIS -.B fenrir -.RB [ \-h ] -.RB [ \-v ] -.RB [ \-f ] -.RB [ \-s -.IR SETTING-FILE ] -.RB [ \-o -.IR SECTION#SETTING=VALUE;.. ] -.RB [ \-d ] -.RB [ \-p ] -.RB [ \-x ] -.RB [ \-\-x11-window-id -.IR WINDOWID ] -.RB [ \-F ] -.RB [ \-i -.IR SCREEN ] - -.SH DESCRIPTION -Fenrir is a modern, modular, flexible and fast console screen reader written in Python 3. -It provides spoken feedback for Linux console applications and supports Linux TTYs plus X11 terminal mode. - -Fenrir features a modular driver architecture supporting multiple speech synthesizers, sound systems, input methods, and screen reading techniques. It includes advanced features like review mode, multiple clipboards, spell checking, bookmarks, and configurable key bindings. - -.SH OPTIONS -.TP -.BR \-h ", " \-\-help -Show help message and exit. - -.TP -.BR \-v ", " \-\-version -Show version information and exit. - -.TP -.BR \-f ", " \-\-foreground -Run Fenrir in the foreground instead of as a daemon. Useful for debugging and testing. - -.TP -.BR \-s ", " \-\-setting " " \fISETTING-FILE\fR -Path to a custom settings file. Default is /etc/fenrirscreenreader/settings/settings.conf for root and ~/.local/share/stormux/fenrirscreenreader/settings/settings.conf for regular-user saves. - -.TP -.BR \-o ", " \-\-options " " \fISECTION#SETTING=VALUE;..\fR -Override settings file options. Format: SECTION#SETTING=VALUE;... (case sensitive). -Multiple settings can be separated by semicolons. - -.TP -.BR \-d ", " \-\-debug -Enable debug mode. Debug information will be logged to /tmp/fenrir.log by -default. If another Fenrir debug instance is already using it, Fenrir uses -/tmp/fenrir2.log, /tmp/fenrir3.log, etc. - -.TP -.BR \-p ", " \-\-print -Print debug messages to screen in addition to logging them. - -.TP -.BR \-F ", " \-\-force-all-screens -Force Fenrir to respond on all screens, ignoring the ignore_screen setting. This temporarily overrides screen filtering for the current session. - -.TP -.BR \-i ", " \-I ", " \-\-ignore-screen " \fISCREEN\fR" -Ignore specific screen(s). Can be used multiple times to ignore multiple screens. This is equivalent to setting ignore_screen in the configuration file and will be combined with any existing ignore settings. - -.TP -.BR \-x ", " \-\-x11 -Run in X11 terminal mode using PTY screen monitoring and X11 keyboard input scoped to the terminal window. - -.TP -.BR \-\-x11-window-id " " \fIWINDOWID\fR -Use a specific X11 terminal window id for X11 terminal mode. - -.SH KEY CONCEPTS - -.SS Fenrir Key -The Fenrir Key is used to invoke screen reader commands. By default, the following keys act as Fenrir Keys: -.IP \[bu] 2 -Insert -.IP \[bu] 2 -Keypad Insert -.IP \[bu] 2 -Meta (Super/Windows key) - -.SS Keyboard Layouts -Fenrir supports two main keyboard layouts: -.IP \[bu] 2 -.B Desktop Layout -\- Uses numeric keypad for navigation (recommended for desktop users) -.IP \[bu] 2 -.B Laptop Layout -\- Alternative bindings for keyboards without numeric keypad - -.SS Review Mode -Fenrir provides a virtual cursor that allows navigation around the screen without changing the text cursor position. This is essential for reviewing content without disrupting your work. - -.SH BASIC COMMANDS - -.SS Essential Navigation -.TP -.B Ctrl -Stop speech (shut up) - -.TP -.B Fenrir + H -Toggle tutorial mode (interactive help system) - -.TP -.B Fenrir + Q -Quit Fenrir - -.TP -.B Fenrir + Keypad 5 -Read current screen - -.TP -.B Keypad 8 -Read current line - -.TP -.B Keypad 5 -Read current word - -.TP -.B Keypad 2 -Read current character - -.TP -.B Fenrir + T -Announce current time - -.TP -.B Fenrir + S -Spell check current word - -.SS Review Commands (Desktop Layout) -.TP -.B Keypad 7 -Review previous line - -.TP -.B Keypad 9 -Review next line - -.TP -.B Keypad 4 -Review previous word - -.TP -.B Keypad 6 -Review next word - -.TP -.B Keypad 1 -Review previous character - -.TP -.B Keypad 3 -Review next character - -.TP -.B Fenrir + Keypad dot -Exit review mode - -.SS Clipboard Operations -.TP -.B Fenrir + C -Copy marked text to clipboard - -.TP -.B Fenrir + V -Paste clipboard contents - -.TP -.B Fenrir + Shift + C -Read current clipboard - -.TP -.B Fenrir + X -Set mark (for text selection) - -.TP -.B Fenrir + Shift + X -Announce marked text - -.SH CONFIGURATION - -.SS Settings File -The main configuration file is located at: -.IP \[bu] 2 -.B /etc/fenrirscreenreader/settings/settings.conf -(system-wide installation) -.IP \[bu] 2 -.B ~/.local/share/stormux/fenrirscreenreader/settings/settings.conf -(user-local settings) -.IP \[bu] 2 -.B config/settings/settings.conf -(development/git version) - -When Fenrir runs as a regular user, including fenrir -x, it loads the -user-local settings file if it exists. If it does not exist, Fenrir falls back -to the system settings file, but saving settings writes to the user-local path. -When Fenrir runs as root, settings save to the system-wide path by default. - -User sound themes are loaded before system themes from -~/.local/stormux/fenrir/sounds/. User scripts are loaded before configured -system scripts from ~/.local/stormux/fenrir/. - -.SS Key Sections -.TP -.B [speech] -Configure speech synthesis (rate, pitch, volume, driver) - -.TP -.B [sound] -Configure sound output and sound icons - -.TP -.B [keyboard] -Configure input driver and keyboard layout - -.TP -.B [screen] -Configure screen reading driver and ignored screens - -.TP -.B [general] -General settings like punctuation, clipboard, and debug levels - -.SS Driver Configuration -Fenrir uses a modular driver system: - -.TP -.B Speech Drivers: -.IP \[bu] 4 -speechdDriver - Speech-dispatcher (recommended) -.IP \[bu] 4 -genericDriver - Command-line TTS (espeak, etc.) -.IP \[bu] 4 -dectalkDriver - DECtalk-compatible serial hardware speech -.IP \[bu] 4 -dectalkUsbDriver - Native Access Solutions DECtalk USB hardware speech -.IP \[bu] 4 -litetalkDriver - LiteTalk-compatible serial hardware speech -.IP \[bu] 4 -doubletalkDriver - DoubleTalk LT-compatible serial hardware speech -.IP \[bu] 4 -tripletalkDriver - TripleTalk-compatible serial hardware speech -.IP \[bu] 4 -debugDriver - Debug/testing - -.TP -.B Sound Drivers: -.IP \[bu] 4 -genericDriver - Sox-based (default) -.IP \[bu] 4 -gstreamerDriver - GStreamer-based -.IP \[bu] 4 -debugDriver - Debug/testing - -.TP -.B Input Drivers: -.IP \[bu] 4 -evdevDriver - Linux evdev (recommended for Linux) -.IP \[bu] 4 -x11Driver - X11 terminal-scoped input for fenrir -x - -.TP -.B Screen Drivers: -.IP \[bu] 4 -vcsaDriver - Linux VCSA devices (TTY) -.IP \[bu] 4 -ptyDriver - Terminal emulation - -.TP -.B Remote Drivers: -.IP \[bu] 4 -unixDriver - Unix socket remote control (recommended) -.IP \[bu] 4 -tcpDriver - TCP socket remote control (localhost only) - -.SH EXAMPLES - -.TP -.B fenrir -Start Fenrir as a daemon with default settings. - -.TP -.B fenrir -f -d -Run Fenrir in foreground with debug output. - -.TP -.B fenrir -o "speech#rate=0.8;sound#volume=0.5" -Override speech rate and sound volume settings. - -.TP -.B fenrir -F -Force Fenrir to work on all screens, ignoring ignore_screen settings. - -.TP -.B fenrir -s /home/user/my-fenrir.conf -Use a custom configuration file. - -.SH REMOTE CONTROL - -Fenrir includes a powerful remote control system for automation and integration with external applications. - -.SS Configuration -Enable remote control in /etc/fenrirscreenreader/settings/settings.conf or the user-local settings file: - -.EX -[remote] -enable=True -driver=unixDriver -enable_settings_remote=True -enable_command_remote=True -.EE - -.SS Using socat with Unix Sockets - -.TP -.B Instance Discovery: -.EX -# List registered Fenrir instances and their socket paths -echo "ls" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -.EE - -In X terminal mode (fenrir -x), multiple Fenrir instances can run at the -same time. Each instance has a private socket at -/tmp/fenrirscreenreader-.sock, and one instance may also own the -standard control socket. Use ls or "command ls" on the standard socket to -find the private socket for a specific instance. Commands sent to the standard -socket are handled by its owner when possible; otherwise they are forwarded to a -registered private socket, preferring the sender's Fenrir ancestor when one can -be found. - -.TP -.B Basic Speech Control: -.EX -# Interrupt current speech -echo "command interrupt" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Speak custom text -echo "command say Hello, this is a test" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Temporarily disable speech -echo "command tempdisablespeech" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -.EE - -.TP -.B Settings Control: -.EX -# Enable highlight tracking -echo "setting set focus#highlight=True" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Change speech rate -echo "setting set speech#rate=0.8" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Change punctuation level (none/some/most/all) -echo "setting set general#punctuation_level=all" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Voice and TTS control -echo "setting set speech#voice=en-us+f3" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Multiple settings at once -echo "setting set speech#rate=0.8;sound#volume=0.7;general#punctuation_level=most" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Reset all settings -echo "setting reset" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -.EE - -.TP -.B Clipboard Operations: -.EX -# Add text to clipboard -echo "command clipboard Text to copy" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Export clipboard to file -echo "command exportclipboard" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -.EE - -.SS Command Reference - -.TP -.B Speech Commands: -.IP \[bu] 2 -command say - Speak the specified text -.IP \[bu] 2 -command interrupt - Stop current speech -.IP \[bu] 2 -command tempdisablespeech - Disable speech until next key press -.IP \[bu] 2 -ls / list / command ls / command list - List registered Fenrir instances - -.TP -.B Settings Commands: -.IP \[bu] 2 -setting set
#= - Set configuration value -.IP \[bu] 2 -setting reset - Reset all settings to defaults -.IP \[bu] 2 -setting save [path] - Save current settings - -.TP -.B Other Commands: -.IP \[bu] 2 -command clipboard - Add text to clipboard -.IP \[bu] 2 -command window - Define window area -.IP \[bu] 2 -command resetwindow - Reset to full screen -.IP \[bu] 2 -command vmenu - Set virtual menu -.IP \[bu] 2 -command resetvmenu - Reset virtual menu -.IP \[bu] 2 -command quitapplication - Quit Fenrir - -.SS Important Controllable Settings - -.TP -.B Speech Control: -.IP \[bu] 2 -general#punctuation_level=none/some/most/all - Punctuation verbosity -.IP \[bu] 2 -speech#rate=0.1-1.0 - Speech rate -.IP \[bu] 2 -speech#pitch=0.1-1.0 - Speech pitch -.IP \[bu] 2 -speech#volume=0.1-1.0 - Speech volume -.IP \[bu] 2 -speech#voice=voice_name - Voice selection -.IP \[bu] 2 -speech#module=module_name - TTS module - -.TP -.B Screen Control: -.IP \[bu] 2 -screen#ignore_screen=1,2,3 - TTY screens to ignore -.IP \[bu] 2 -focus#highlight=True/False - Follow text highlighting - -.TP -.B Input Control: -.IP \[bu] 2 -keyboard#char_echo_mode=0-2 - Character echo mode -.IP \[bu] 2 -keyboard#word_echo=True/False - Word echo - -.SH FILES -.TP -.B /etc/fenrirscreenreader/settings/settings.conf -Main configuration file - -.TP -.B ~/.local/share/stormux/fenrirscreenreader/settings/settings.conf -User-local configuration file - -.TP -.B /etc/fenrirscreenreader/keyboard/ -Keyboard layout definitions - -.TP -.B /etc/fenrirscreenreader/punctuation/ -Punctuation level definitions - -.TP -.B /usr/share/sounds/fenrirscreenreader/ -System sound themes - -.TP -.B ~/.local/stormux/fenrir/sounds/ -User sound themes - -.TP -.B ~/.local/stormux/fenrir/ -User scripts - -.TP -.B /tmp/fenrir.log -Debug log file - -.TP -.B /run/fenrir.pid -Process ID file when running as daemon - -.SH ENVIRONMENT -Fenrir respects standard Linux permissions and requires appropriate access to: -.IP \[bu] 2 -/dev/input/* (for evdev input driver) -.IP \[bu] 2 -/dev/uinput (for key injection) -.IP \[bu] 2 -/dev/vcsa* (for VCSA screen driver) -.IP \[bu] 2 -DBus system bus (for screen change detection) - -.SH DEPENDENCIES -.SS Required -.IP \[bu] 2 -Python 3.6 or later -.IP \[bu] 2 -python3-evdev (for evdev input driver) -.IP \[bu] 2 -python3-pyudev (for device detection) - -.SS Recommended -.IP \[bu] 2 -speech-dispatcher and python3-speechd (for speech) -.IP \[bu] 2 -sox with opus support (for sound) -.IP \[bu] 2 -espeak-ng (for speech synthesis) - -.SS Optional -.IP \[bu] 2 -python3-pyenchant and aspell-* (for spell checking) -.IP \[bu] 2 -python3-daemonize (for daemon mode) -.IP \[bu] 2 -pyalsaaudio (for ALSA volume control) - -.SH SIGNALS -.TP -.B SIGTERM, SIGINT -Gracefully shut down Fenrir - -.SH EXIT STATUS -.TP -.B 0 -Success - -.TP -.B 1 -General error (configuration, permission, etc.) - -.SH BUGS -Report bugs to the project maintainer or via the project repository. - -.SH AUTHORS -.B Current maintainer: -Storm Dragon - -.B Previous developer: -Chrys - -.B Contributors: -Jeremiah and others - -.SH COPYRIGHT -This software is licensed under the LGPL v3. - -.SH SEE ALSO -.BR speechd (1), -.BR espeak (1), -.BR espeak-ng (1), -.BR sox (1) - +.\" Automatically generated by Pandoc 3.12.1 +.\" +.TH "fenrir" "1" "" "" "Fenrir User Manual" +.SH Fenrir User Manual +Fenrir is a Linux console screen reader written in Go. +It reads Linux text consoles and can run in an X11 terminal as a regular +user. .PP -Full documentation: https://git.stormux.org/storm/fenrir/wiki - +\f[B]Current maintainer:\f[R] Storm Dragon +.PD 0 +.P +.PD +\f[B]Original creator:\f[R] Chrys (see CREDITS) .PP -Support: stormux+subscribe@groups.io +For build requirements and setup, see the README. +.SS Starting and stopping +Run these commands from the checkout root after building +\f[CR]fenrir\f[R]: +.IP +.EX +\f[I]# Linux text console, with console and keyboard device access\f[R] +sudo ./fenrir + +\f[I]# X11 terminal, as your regular user\f[R] +\&./fenrir \-x + +\f[I]# Either mode can select the laptop layout\f[R] +\&./fenrir \-x \-\-keyboard\-layout laptop +.EE +.PP +Fenrir runs in the foreground. +Press \f[B]Fenrir+Q\f[R] to quit. +Run only one reader on a given Linux console. +Separate X11 terminal instances can run at once. +.PP +X11 mode starts a shell in a new PTY. +The launching terminal must supply valid \f[CR]DISPLAY\f[R] and +\f[CR]WINDOWID\f[R] environment variables. +Keyboard interception is scoped to that terminal window; a desktop +screen reader can handle other windows. +.PP +Console mode needs access to console devices, keyboard event devices, +and \f[CR]/dev/uinput\f[R]. +It releases keyboard input on graphical virtual terminals and on text +consoles selected in \f[CR]screen.ignored_vts\f[R]. +.SS Keyboard layouts and help +The \f[B]Fenrir key\f[R] is Insert, Super/Windows, or keypad 0 with +NumLock off. +Hold it while pressing the other keys in a shortcut. +Bare keypad review keys also require NumLock off. +.PP +The desktop layout uses the numeric keypad. +The laptop layout uses Fenrir chords on the main keyboard. +Select a layout with \f[CR]\-\-keyboard\-layout desktop\f[R] or +\f[CR]\-\-keyboard\-layout laptop\f[R], or set +\f[CR]keyboard.layout\f[R] in the settings file. +.PP +Press \f[B]Fenrir+H\f[R] or \f[B]Fenrir+F1\f[R] to enter the tutorial. +Command shortcuts are announced and described instead of executed. +Up and Down browse commands; Left and Right switch between active +actions, unbound actions, and scripts. +Space repeats the current item. +Escape or Fenrir+F1 exits. +.PP +The complete layouts are desktop.toml and laptop.toml. +.SS Screen review +Review moves Fenrir\(cqs reading position without moving the +application\(cqs cursor. +Return to the application cursor with the Follow cursor shortcut. +By default, application cursor movement or a screen change also leaves +review. +.IP \(bu 2 +\f[B]Previous / current / next line\f[R] +.RS 2 +.PP +Desktop: Keypad 7 / 8 / 9 +.PP +Laptop: Fenrir+U / I / O +.RE +.IP \(bu 2 +\f[B]Previous / current / next word\f[R] +.RS 2 +.PP +Desktop: Keypad 4 / 5 / 6 +.PP +Laptop: Fenrir+J / K / L +.RE +.IP \(bu 2 +\f[B]Previous / current / next character\f[R] +.RS 2 +.PP +Desktop: Keypad 1 / 2 / 3 +.PP +Laptop: Fenrir+M / Comma / Period +.RE +.IP \(bu 2 +\f[B]Top / bottom of screen\f[R] +.RS 2 +.PP +Desktop: Fenrir+Keypad 7 / 9 +.PP +Laptop: Fenrir+Shift+U / O +.RE +.IP \(bu 2 +\f[B]Line start / end\f[R] +.RS 2 +.PP +Desktop: Fenrir+Keypad 4 / 6 +.PP +Laptop: Fenrir+Shift+J / L +.RE +.IP \(bu 2 +\f[B]First / last text on line\f[R] +.RS 2 +.PP +Desktop: Fenrir+Keypad 1 / 3 +.PP +Laptop: Fenrir+Control+J / L +.RE +.IP \(bu 2 +\f[B]Read screen\f[R] +.RS 2 +.PP +Desktop: Fenrir+Keypad 5 +.PP +Laptop: Fenrir+Shift+K +.RE +.IP \(bu 2 +\f[B]Screen before / after cursor\f[R] +.RS 2 +.PP +Desktop: Fenrir+Keypad 8 / 2 +.PP +Laptop: Fenrir+Shift+I / Comma +.RE +.IP \(bu 2 +\f[B]Character above / below\f[R] +.RS 2 +.PP +Desktop: Fenrir+Control+Keypad 8 / 2 +.PP +Laptop: Fenrir+Control+I / Comma +.RE +.IP \(bu 2 +\f[B]Follow cursor\f[R] +.RS 2 +.PP +Desktop: Fenrir+Keypad Period +.PP +Laptop: Fenrir+Slash +.RE +.IP \(bu 2 +\f[B]Review position\f[R] +.RS 2 +.PP +Desktop: Keypad Period +.PP +Laptop: Fenrir+Shift+Period +.RE +.PP +Press the current\-line or current\-word shortcut twice quickly to spell +the text, or three times for phonetic reading. +Press the current\-character shortcut twice for its phonetic name. +The default interval between presses is 200 ms; +\f[CR]keyboard.multi_press_timeout_ms\f[R] changes it at launch. +.SS Tracking modes +Cycle through \f[B]cursor\f[R], \f[B]table\f[R], and \f[B]highlight\f[R] +with \f[B]Fenrir+Keypad Asterisk\f[R] on desktop or \f[B]Fenrir+Y\f[R] +on laptop. +The startup selection is \f[CR]reading.mode\f[R]. +.IP \(bu 2 +\f[B]Cursor\f[R]: follows application cursor movement. +.IP \(bu 2 +\f[B]Table\f[R]: treats delimited or space\-aligned text as cells. +.IP \(bu 2 +\f[B]Highlight\f[R]: follows changes to highlighted text, such as menu +selections. +.PP +In table mode, word navigation moves between cells, line start/end moves +to the first/last cell, and first/last text moves to the first/last +character in the current cell. +Place review on a header row and press \f[B]Fenrir+X\f[R] to use its +cells as column headers. +Outside table mode, Fenrir+X places a text\-selection mark. +.SS Speech and automatic reading +.IP \(bu 2 +\f[B]Control\f[R] interrupts speech. +.IP \(bu 2 +\f[B]Fenrir+F4\f[R] toggles mute. +.IP \(bu 2 +\f[B]Keypad Enter\f[R] on desktop temporarily silences speech. +Speech can return on the next keypress or a newly recognized prompt or +completion. +.IP \(bu 2 +\f[B]Fenrir+Keypad Enter\f[R] on desktop, or \f[B]Fenrir+Enter\f[R] on +laptop, toggles automatic reading of new text. +.IP \(bu 2 +\f[B]Fenrir+Backspace\f[R] passes the next key through to the +application. +.PP +Character echo, word echo, and cursor echo can be configured separately. +Punctuation levels are \f[CR]none\f[R], \f[CR]some\f[R], +\f[CR]most\f[R], and \f[CR]all\f[R]. +Character review still names punctuation. +Capital indicators, emoticons, repeated\-symbol summaries, indentation +feedback, and attribute feedback are configurable in Reading. +.PP +\f[B]Fenrir+T\f[R] announces the time; press twice quickly for the date. +\f[B]Fenrir+Shift+V\f[R] announces the Fenrir version. +.SS Fenrir Menu and quick settings +Press \f[B]Fenrir+F\f[R] to open the Fenrir Menu. +It contains settings tabs for presentation, speech, sound, reading, +keyboard, clipboard, and other options. +The form captures its navigation keys until it closes. +.IP \(bu 2 +At the tab selector, use arrows to choose a tab. +.IP \(bu 2 +Tab and Shift+Tab move between controls and the tab selector. +.IP \(bu 2 +Space or Enter toggles a checkbox. +.IP \(bu 2 +Arrows change list selections and numeric values. +.IP \(bu 2 +Activate \f[B]OK\f[R] to save, or \f[B]Cancel\f[R] or Escape to discard +the form\(cqs changes. +.PP +Speech rate, pitch, and volume use a scale from \-100 to 100. +Sound volume is between 0.0 and 1.0. +Backend, device, keyboard layout, sound theme, and other launch\-only +settings take effect on the next start. +.PP +Quick settings work without opening the form: +.IP \(bu 2 +\f[B]Fenrir+Space\f[R] +.RS 2 +.PP +Action: Announce current setting +.RE +.IP \(bu 2 +\f[B]Fenrir+Left / Right\f[R] +.RS 2 +.PP +Action: Previous / next setting +.RE +.IP \(bu 2 +\f[B]Fenrir+Control+Left / Right\f[R] +.RS 2 +.PP +Action: Previous / next category +.RE +.IP \(bu 2 +\f[B]Fenrir+Up / Down\f[R] +.RS 2 +.PP +Action: Change value +.RE +.IP \(bu 2 +\f[B]Fenrir+Control+S\f[R] +.RS 2 +.PP +Action: Save settings +.RE +.PP +Quick changes apply to the current session. +Save to retain them for future launches. +Session controls such as mute and temporary silence are separate from +saved startup preferences. +.SS Clipboard +Use review navigation to place two marks around text with +\f[B]Fenrir+X\f[R], then press \f[B]Fenrir+C\f[R] to copy it. +In table mode Fenrir+X sets headers instead. +.IP \(bu 2 +\f[B]Fenrir+Shift+X\f[R] +.RS 2 +.PP +Action: Read marked text +.RE +.IP \(bu 2 +\f[B]Fenrir+Control+Shift+X\f[R] +.RS 2 +.PP +Action: Remove marks +.RE +.IP \(bu 2 +\f[B]Fenrir+C\f[R] +.RS 2 +.PP +Action: Copy marked text +.RE +.IP \(bu 2 +\f[B]Fenrir+Control+C\f[R] +.RS 2 +.PP +Action: Copy last presented text +.RE +.IP \(bu 2 +\f[B]Fenrir+Shift+C\f[R] +.RS 2 +.PP +Action: Read selected clipboard +.RE +.IP \(bu 2 +\f[B]Fenrir+Control+Shift+C\f[R] +.RS 2 +.PP +Action: Clear selected clipboard +.RE +.IP \(bu 2 +\f[B]Fenrir+Home / End\f[R] +.RS 2 +.PP +Action: First / last clipboard +.RE +.IP \(bu 2 +\f[B]Fenrir+PageUp / PageDown\f[R] +.RS 2 +.PP +Action: Previous / next clipboard +.RE +.IP \(bu 2 +\f[B]Fenrir+V\f[R] +.RS 2 +.PP +Action: Paste selected clipboard +.RE +.IP \(bu 2 +\f[B]Fenrir+F5 / F6\f[R] +.RS 2 +.PP +Action: Import from / export to file +.RE +.IP \(bu 2 +\f[B]Fenrir+F7 / F8\f[R] +.RS 2 +.PP +Action: Import from / export to X clipboard +.RE +.PP +\f[CR]clipboard.number_of_clipboards\f[R] limits history; the default is +200. +\f[CR]clipboard.export_path\f[R] selects the import/export file, +initially \f[CR]/tmp/fenrirClipboard\f[R]. +\f[CR]clipboard.sync\f[R] enables automatic X clipboard synchronization, +which requires \f[CR]xclip\f[R] and access to the X display. +.PP +Persistent history is optional and off by default. +Set \f[CR]clipboard.persistent\f[R] to retain unencrypted history across +launches. +Terminal sessions use +\f[CR]\(ti/.local/state/fenrir/clipboard/terminal.json\f[R]; console +sessions use \f[CR]/var/lib/fenrir/clipboard/tty.json\f[R]. +Same\-user readers of the same mode share persistent history. +.SS Spell checking and emoji +Automatic spell checking uses Enchant 2 and a dictionary matching the +session language. +Reading settings control word repetition, spoken misspelling feedback, +and misspelling sounds. +.PP +Press \f[B]Fenrir+S\f[R] to open the Spellcheck Menu for the current +word. +The Suggestions tab lets you edit the word and choose a suggested +spelling. +The Exceptions tab lets you add words, remove selected entries with +Delete, and undo a removal. +Selecting a suggestion copies it to Fenrir\(cqs clipboard; paste it with +Fenrir+V. +.PP +Press \f[B]Fenrir+Control+E\f[R] to open the Emoji Menu. +Choose a category at the tab selector, then Tab to the emoji grid. +Arrows navigate, typing filters by name prefix, and Control+Backspace +clears the filter. +Enter copies the selected emoji to Fenrir\(cqs clipboard. +Escape closes the menu. +.SS Reading windows and live regions +Reading regions belong to the current terminal and last for the reader +session. +A reading window restricts automatic reading to a rectangle. +Live regions exclude changing areas from automatic speech while allowing +explicit reading and progress monitoring. +.PP +Outside table mode, place two marks with \f[B]Fenrir+X\f[R] to define +opposite corners. +Press \f[B]Fenrir+Keypad Slash\f[R] on desktop or +\f[B]Fenrir+Control+8\f[R] on laptop to set a reading window. +Press the shortcut twice quickly to clear it. +.PP +To create a live region, place one mark for the rest of that line, or +two marks for a rectangle, then press \f[B]Fenrir+B\f[R]. +Fenrir assigns the first free slot, up to ten. +Region creation clears the marks. +.IP \(bu 2 +\f[B]Fenrir+1\f[R] through \f[B]Fenrir+0\f[R] read live regions 1 +through 10. +.IP \(bu 2 +\f[B]Fenrir+Shift+1\f[R] through \f[B]Fenrir+Shift+0\f[R] clear +individual live regions. +.IP \(bu 2 +\f[B]Fenrir+Shift+B\f[R] lists the current reading regions. +.IP \(bu 2 +\f[B]Fenrir+Control+B\f[R] clears all live regions. +.IP \(bu 2 +\f[B]Fenrir+Control+Shift+B\f[R] clears both the reading window and live +regions. +.SS Sound and progress +Sound output uses \f[CR]pulse\f[R] for PulseAudio or PipeWire\(cqs +PulseAudio service, or \f[CR]alsa\f[R] for an ALSA PCM device. +Select the driver and theme in Sound settings. +The ALSA device name is set with \f[CR]presentation.sound.device\f[R] in +the file. +.PP +Personal themes are searched under +\f[CR]\(ti/.local/stormux/fenrir/sounds/\f[R] before bundled and system +themes. +A theme contains WAV files and \f[CR]soundicons.toml\f[R]. +.PP +Progress tones are controlled separately from speech and automatic +reading. +Press \f[B]Keypad Plus\f[R] on desktop or \f[B]Fenrir+Shift+P\f[R] on +laptop to toggle them. +Fenrir recognizes percentages, fractions, progress bars, and activity +indicators; tones rise with progress. +Startup behavior is set by \f[CR]presentation.progress.enabled\f[R]. +.SS Configuration files +Settings are TOML. +The annotated settings.toml lists all available options. +Fenrir loads one settings file rather than merging files. +.IP \(bu 2 +Regular users: first +\f[CR]\(ti/.local/share/stormux/fenrirscreenreader/settings/settings.toml\f[R], +then \f[CR]/etc/fenrirscreenreader/settings/settings.toml\f[R]. +.IP \(bu 2 +Root: \f[CR]/etc/fenrirscreenreader/settings/settings.toml\f[R]. +.IP \(bu 2 +\f[CR]\-\-config PATH\f[R]: use that file explicitly. +.PP +If default files are absent, Fenrir uses built\-in defaults. +An explicitly selected file must exist. +Saving targets the selected file; if startup used built\-in defaults, +saving creates the first default path for that account. +.PP +Create a personal settings file and validate it without opening devices: +.IP +.EX +\&./fenrir \-\-write\-config \(ti/.local/share/stormux/fenrirscreenreader/settings/settings.toml +\&./fenrir \-\-config \(ti/.local/share/stormux/fenrirscreenreader/settings/settings.toml \-\-check\-config +.EE +.PP +Named keyboard layouts are searched in the regular user\(cqs +\f[CR]\(ti/.local/share/stormux/fenrirscreenreader/keyboard/\f[R], then +\f[CR]/etc/fenrirscreenreader/keyboard/\f[R], then +\f[CR]config/keyboard/\f[R] beside the binary. +Root searches the system and bundled locations. +An explicit TOML path selects one file. +Custom layouts replace the complete layout; they are not overlays. +See the keyboard guide for an example. +.SS Speech synthesizers +The default driver is \f[CR]speech\-dispatcher\f[R]. +Select its module, language, and voice in Speech settings; empty values +use server defaults. +.PP +Hardware driver IDs are \f[CR]dectalk\f[R], \f[CR]dectalk\-usb\f[R], +\f[CR]litetalk\f[R], \f[CR]doubletalk\f[R], and \f[CR]tripletalk\f[R]. +Serial drivers require \f[CR]presentation.speech.hardware_device\f[R], +for example \f[CR]/dev/ttyUSB0\f[R], and default to 9600 baud when +\f[CR]hardware_baud_rate = 0\f[R]. +DoubleTalk support targets the external LT device. +TripleTalk USB devices need to expose a serial tty. +.PP +Native \f[CR]dectalk\-usb\f[R] uses libusb 1.0 and ignores serial +settings. +The process needs access to the device. +The Speech form\(cqs \f[B]Test synthesizer\f[R] button previews hardware +choices before saving. +Driver and port changes apply at launch. +.SS Script shortcuts +Fenrir searches \f[CR]\(ti/.local/stormux/fenrir/\f[R], the configured +\f[CR]general.script_path\f[R] (default +\f[CR]/usr/share/fenrirscreenreader/scripts\f[R]), and the bundled +\f[CR]config/scripts/\f[R] beside the binary. +Earlier directories take priority. +.PP +A filename such as \f[CR]example__\-__key_y.sh\f[R] assigns the script +key plus Y. The script key defaults to Compose and is configured by +\f[CR]general.script_keys\f[R]. +Scripts must be executable to run. +Fenrir invokes them directly and passes the current account name as the +first argument. +Commands appear in the tutorial\(cqs script list. +.SS Remote control +Unix socket remote control is enabled by default. +The standard socket is \f[CR]/tmp/fenrirscreenreader\-daemon.sock\f[R], +and instances also have private sockets +\f[CR]/tmp/fenrirscreenreader\-.sock\f[R]. +Set \f[CR]remote.socket_file\f[R] for a custom socket. +.PP +Use \f[CR]ls\f[R] to discover instances. +Use a private socket to address one reader: +.IP +.EX +echo \(dqls\(dq \f[B]|\f[R] socat \- UNIX\-CLIENT:/tmp/fenrirscreenreader\-daemon.sock +echo \(dqcommand say Hello\(dq \f[B]|\f[R] socat \- UNIX\-CLIENT:/tmp/fenrirscreenreader\-daemon.sock +echo \(dqcommand interrupt\(dq \f[B]|\f[R] socat \- UNIX\-CLIENT:/tmp/fenrirscreenreader\-daemon.sock +echo \(dqsetting set reading#mode=highlight\(dq \f[B]|\f[R] socat \- UNIX\-CLIENT:/tmp/fenrirscreenreader\-daemon.sock +.EE +.PP +Remote requests use \f[CR]section#setting=value\f[R] syntax +independently of TOML. +Remote speech rate, pitch, and volume use \f[B]0.0 to 1.0\f[R], mapped +to the \-100 to 100 scale used in settings files and menus. +For example, \f[CR]speech#rate=0.8\f[R] selects rate 60. +.PP +Other supported operations include: +.IP \(bu 2 +\f[CR]command tempdisablespeech\f[R]: temporarily silence speech. +.IP \(bu 2 +\f[CR]command clipboard TEXT\f[R]: add text to the clipboard. +.IP \(bu 2 +\f[CR]command exportclipboard\f[R]: export the selected clipboard. +.IP \(bu 2 +\f[CR]command window X1 Y1 X2 Y2\f[R]: set a reading window, using +zero\-based, inclusive coordinates. +.IP \(bu 2 +\f[CR]command resetwindow\f[R]: clear the window. +.IP \(bu 2 +\f[CR]setting save\f[R]: save settings. +.IP \(bu 2 +\f[CR]setting reset\f[R]: clear quick and remote overrides back to the +last loaded or successfully saved settings. +.IP \(bu 2 +\f[CR]command quitapplication\f[R]: quit Fenrir. +.PP +Set \f[CR]remote.enabled = false\f[R] to disable the service. +Command and setting requests have separate switches, +\f[CR]enable_command_remote\f[R] and \f[CR]enable_settings_remote\f[R]. +Requests are authorized against the caller\(cqs account; console +self\-voicing also allows an account logged into the active console. +.SS Command\-line options +Fenrir runs as \f[CR]fenrir [options]\f[R]. +Use \f[CR]\-\-help\f[R] for the built\-in reference. +.IP \(bu 2 +\f[B]\-\-help\f[R] +.RS 2 +.PP +Purpose: Show usage and options +.RE +.IP \(bu 2 +\f[B]\-\-version\f[R] +.RS 2 +.PP +Purpose: Print version and release channel +.RE +.IP \(bu 2 +\f[B]\-x\f[R] +.RS 2 +.PP +Purpose: Start a shell inside this X11 terminal +.RE +.IP \(bu 2 +\f[B]\-\-config PATH\f[R] +.RS 2 +.PP +Purpose: Load a specific TOML settings file +.RE +.IP \(bu 2 +\f[B]\-\-keyboard\-layout NAME_OR_PATH\f[R] +.RS 2 +.PP +Purpose: Select a named layout or TOML file +.RE +.IP \(bu 2 +\f[B]\-\-punctuation\-profile NAME_OR_PATH\f[R] +.RS 2 +.PP +Purpose: Select a punctuation profile +.RE +.IP \(bu 2 +\f[B]\-\-check\-config\f[R] +.RS 2 +.PP +Purpose: Validate settings, layout, and punctuation without opening devices +.RE +.IP \(bu 2 +\f[B]\-\-write\-config PATH\f[R] +.RS 2 +.PP +Purpose: Write effective settings to a file and exit +.RE +.IP \(bu 2 +\f[B]\-\-speech\-driver ID\f[R] +.RS 2 +.PP +Purpose: Override the configured speech driver +.RE +.IP \(bu 2 +\f[B]\-\-speech\-rate NUMBER\f[R] +.RS 2 +.PP +Purpose: Override rate, from \-100 to 100 +.RE +.IP \(bu 2 +\f[B]\-\-speech\-module NAME\f[R] +.RS 2 +.PP +Purpose: Select a Speech Dispatcher module +.RE +.IP \(bu 2 +\f[B]\-\-input\-device PATH\f[R] +.RS 2 +.PP +Purpose: Select a console keyboard event device; may be repeated +.RE +.IP \(bu 2 +\f[B]\-\-debug\-file PATH\f[R] +.RS 2 +.PP +Purpose: Append timing and reader\-decision diagnostics +.RE +.SS Troubleshooting +.SS Speech or sound is missing +Check that speech and sound are enabled, and that the selected backend +is available. +Speech Dispatcher needs a configured synthesizer. +Pulse output needs access to a running PulseAudio service, including +PipeWire\(cqs PulseAudio service; ALSA needs access to its selected PCM +device. +Root console sessions may need separate audio configuration; see the +README\(cqs setup section. +.PP +For hardware speech, check the driver, device path, device permissions, +and serial baud rate. +Use \f[B]Test synthesizer\f[R] before saving a new hardware selection. +.SS Keyboard input or X11 mode fails +In console mode, check access to keyboard event devices and +\f[CR]/dev/uinput\f[R]. +In X11 mode, check \f[CR]DISPLAY\f[R], \f[CR]WINDOWID\f[R], and +competing grabs on the terminal. +Use NumLock off for bare keypad review. +A configured \f[CR]keyboard.devices\f[R] list or +\f[CR]\-\-input\-device\f[R] applies to console mode and cannot be used +with \f[CR]\-x\f[R]. +.SS Check configuration and collect diagnostics +Validate an edited settings file with +\f[CR]\-\-config PATH \-\-check\-config\f[R]. +For reader diagnostics, add +\f[CR]\-\-debug\-file /tmp/fenrir\-debug.log\f[R] to the launch command. +This appends timing and reader decisions without screen text or key +values. +\f[CR]./fenrir \-\-version\f[R] identifies the build when reporting a +problem. +.SS Documentation maintenance and support +\f[CR]docs/user.md\f[R] is the shared manual source. +With Pandoc installed, run \f[CR]./docs/create_manpage.sh\f[R] to +regenerate \f[CR]docs/user.txt\f[R], \f[CR]docs/fenrir.adoc\f[R], and +\f[CR]docs/fenrir.1\f[R]. +The script can run from any working directory. +.PP +Please review documentation and test instructions for the affected +workflow before submitting a change, as described in the README\(cqs +contribution policy. +.IP \(bu 2 +\c +.UR https://git.stormux.org/storm/fenrir +Project repository and issue tracker +.UE \c +.IP \(bu 2 +\c +.UR https://git.stormux.org/storm/fenrir/wiki +Fenrir Wiki +.UE \c +.IP \(bu 2 +Email list: \f[CR]stormux+subscribe\(atgroups.io\f[R], with the subject +\f[CR]subscribe\f[R]. +.IP \(bu 2 +IRC: \f[CR]irc.stormux.org\f[R], channel \f[CR]#stormux\f[R]. diff --git a/docs/fenrir.adoc b/docs/fenrir.adoc index 921e6d24..6cbb1d71 100644 --- a/docs/fenrir.adoc +++ b/docs/fenrir.adoc @@ -1,2297 +1,461 @@ -== Fenrir User Manual for Slint users +== Fenrir User Manual -Fenrir is a modern command line screen reader written in Python3. + -It has a modular structure, a flexible based driver model, is highly -configurable and easy to customize and extend. +Fenrir is a Linux console screen reader written in Go. It reads Linux +text consoles and can run in an X11 terminal as a regular user. -=== Credit and intended audience +*Current maintainer:* Storm Dragon + +*Original creator:* Chrys (see link:../CREDITS[CREDITS]) -This document is just a customization for Slint of the genuine -https://git.stormux.org/storm/fenrir/src/branch/master/docs/user.txt[Fenrir User -Manual] motly written by Chrys, main developer of Fenrir. +For build requirements and setup, see the link:../README.md[README]. -It has been adapted to its intended audience: end users of Fenrir on -Slint where it is already installed, thus concentrates on its setting -and usage. You will find more information about its features, -installation and how customize and troubleshoot it and contribute to its -development on https://git.stormux.org/storm/fenrir[the Fenrir Git -repository]. +=== Starting and stopping -=== Getting started with Fenrir +Run these commands from the checkout root after building `fenrir`: -Fenrir is a screen reader, that reads aloud the text displayed on the -screen and allows to review it, like espeakup and speechd-up also -shipped in Slint. + -In Slint it is mostly used in console mode, and uses the synthesizers -and voices provided by Speech Dispatcher. + -Keyboard shortcuts are bound to commands to read the screen, review it -and perform other actions like modify the settings on the fly, switch -languages, copy and paste text, provide miscellaneous information. + -=== Configuration file === The system-wide settings are recorded in the -configuration file /etc/fenrirscreenreader/settings/settings.conf, that is -heavily commented. Regular-user sessions, including `+fenrir -x+`, load -`+~/.local/share/stormux/fenrirscreenreader/settings/settings.conf+` when it -exists, otherwise they fall back to the system settings file. Saving settings -as a regular user creates or updates the user-local file. + -These settings are described in this user guide. +[source,bash] +---- +# Linux text console, with console and keyboard device access +sudo ./fenrir -To start Fenrir once type as root: +# X11 terminal, as your regular user +./fenrir -x -.... -service start fenrir -.... +# Either mode can select the laptop layout +./fenrir -x --keyboard-layout laptop +---- -To enable auto start on system boot type as root: +Fenrir runs in the foreground. Press *Fenrir{plus}Q* to quit. Run only +one reader on a given Linux console. Separate X11 terminal instances can +run at once. -.... -speak-with fenrir -.... +X11 mode starts a shell in a new PTY. The launching terminal must supply +valid `DISPLAY` and `WINDOWID` environment variables. Keyboard +interception is scoped to that terminal window; a desktop screen reader +can handle other windows. -and confirm that you want to have it started at boot time. +Console mode needs access to console devices, keyboard event devices, +and `/dev/uinput`. It releases keyboard input on graphical virtual +terminals and on text consoles selected in `screen.ignored++_++vts`. -If you are using Fenrir for the first time you may want to take a look -at these resources: +=== Keyboard layouts and help -* link:#Keybindings[Keybindings] -* link:#Tutorial Mode[Tutorial Mode] +The *Fenrir key* is Insert, Super/Windows, or keypad 0 with NumLock off. +Hold it while pressing the other keys in a shortcut. Bare keypad review +keys also require NumLock off. -== Keybindings +The desktop layout uses the numeric keypad. The laptop layout uses +Fenrir chords on the main keyboard. Select a layout with +`--keyboard-layout desktop` or `--keyboard-layout laptop`, or set +`keyboard.layout` in the settings file. -Two series of key bindings are provided: +Press *Fenrir{plus}H* or *Fenrir{plus}F1* to enter the tutorial. Command +shortcuts are announced and described instead of executed. Up and Down +browse commands; Left and Right switch between active actions, unbound +actions, and scripts. Space repeats the current item. Escape or +Fenrir{plus}F1 exits. -. the link:#Desktop layout[Desktop layout] uses a numeric keypad (here -abbreviated as keypad). -. the link:#Laptop layout[Laptop layout] for keyboards that do not have -a numeric keypad. +The complete layouts are +link:../config/keyboard/desktop.toml[desktop.toml] and +link:../config/keyboard/laptop.toml[laptop.toml]. -The layout is set in the configuration file in the section -link:#Keyboard[Keyboard]. +=== Screen review -=== Fenrir Key +Review moves Fenrir’s reading position without moving the application’s +cursor. Return to the application cursor with the Follow cursor +shortcut. By default, application cursor movement or a screen change +also leaves review. -The Fenrir Key is for invoking screen reader commands. Fenrir can -utilize more than one FenrirKey at the same time. By default the -following keys are used: +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Action |Desktop |Laptop +|Previous / current / next line |Keypad 7 / 8 / 9 |Fenrir{plus}U / I / O -. Insert -. KeyPad Insert -. Meta (Super, Windows) +|Previous / current / next word |Keypad 4 / 5 / 6 |Fenrir{plus}J / K / L -=== Script Key +|Previous / current / next character |Keypad 1 / 2 / 3 |Fenrir{plus}M / +Comma / Period -To invoke "Scripts" the Script Key is mandatory. The shortcut is encoded -in the filename of the script. See link:#Scripting[Scripting] +|Top / bottom of screen |Fenrir{plus}Keypad 7 / 9 +|Fenrir{plus}Shift{plus}U / O -By default the Script Key is Compose (the key between AltGr and Ctrl at -the right of the space bar). +|Line start / end |Fenrir{plus}Keypad 4 / 6 |Fenrir{plus}Shift{plus}J / +L -For instance, pressing Script Key + L switches between the languages -possibly listed in the configuration file. Feel free to write you own -scripts to expand Fenrir features and share them! +|First / last text on line |Fenrir{plus}Keypad 1 / 3 +|Fenrir{plus}Control{plus}J / L -=== Desktop Layout +|Read screen |Fenrir{plus}Keypad 5 |Fenrir{plus}Shift{plus}K + +|Screen before / after cursor |Fenrir{plus}Keypad 8 / 2 +|Fenrir{plus}Shift{plus}I / Comma + +|Character above / below |Fenrir{plus}Control{plus}Keypad 8 / 2 +|Fenrir{plus}Control{plus}I / Comma + +|Follow cursor |Fenrir{plus}Keypad Period |Fenrir{plus}Slash + +|Review position |Keypad Period |Fenrir{plus}Shift{plus}Period +|=== + +Press the current-line or current-word shortcut twice quickly to spell +the text, or three times for phonetic reading. Press the +current-character shortcut twice for its phonetic name. The default +interval between presses is 200 ms; +`keyboard.multi++_++press++_++timeout++_++ms` changes it at launch. + +=== Tracking modes + +Cycle through *cursor*, *table*, and *highlight* with +*Fenrir{plus}Keypad Asterisk* on desktop or *Fenrir{plus}Y* on laptop. +The startup selection is `reading.mode`. + +* *Cursor*: follows application cursor movement. +* *Table*: treats delimited or space-aligned text as cells. +* *Highlight*: follows changes to highlighted text, such as menu +selections. + +In table mode, word navigation moves between cells, line start/end moves +to the first/last cell, and first/last text moves to the first/last +character in the current cell. Place review on a header row and press +*Fenrir{plus}X* to use its cells as column headers. Outside table mode, +Fenrir{plus}X places a text-selection mark. + +=== Speech and automatic reading + +* *Control* interrupts speech. +* *Fenrir{plus}F4* toggles mute. +* *Keypad Enter* on desktop temporarily silences speech. Speech can +return on the next keypress or a newly recognized prompt or completion. +* *Fenrir{plus}Keypad Enter* on desktop, or *Fenrir{plus}Enter* on +laptop, toggles automatic reading of new text. +* *Fenrir{plus}Backspace* passes the next key through to the +application. + +Character echo, word echo, and cursor echo can be configured separately. +Punctuation levels are `none`, `some`, `most`, and `all`. Character +review still names punctuation. Capital indicators, emoticons, +repeated-symbol summaries, indentation feedback, and attribute feedback +are configurable in Reading. + +*Fenrir{plus}T* announces the time; press twice quickly for the date. +*Fenrir{plus}Shift{plus}V* announces the Fenrir version. + +=== Fenrir Menu and quick settings + +Press *Fenrir{plus}F* to open the Fenrir Menu. It contains settings tabs +for presentation, speech, sound, reading, keyboard, clipboard, and other +options. The form captures its navigation keys until it closes. + +* At the tab selector, use arrows to choose a tab. +* Tab and Shift{plus}Tab move between controls and the tab selector. +* Space or Enter toggles a checkbox. +* Arrows change list selections and numeric values. +* Activate *OK* to save, or *Cancel* or Escape to discard the form’s +changes. + +Speech rate, pitch, and volume use a scale from -100 to 100. Sound +volume is between 0.0 and 1.0. Backend, device, keyboard layout, sound +theme, and other launch-only settings take effect on the next start. + +Quick settings work without opening the form: [cols=",",options="header",] |=== -|Shortcut |Command -|link:#General[General] | - -|CTRL |link:#shut up[shut up (interrupts speech)] - -|FenrirKey + Q |link:#quit Fenrir[quits fenrir] - -|link:#Review modes[Review modes] | - -|FenrirKey + KeyPad dot |link:#exit review[exit review] - -|FenrirKey + KeyPad 9 |link:#review bottom[reviews bottom] - -|FenrirKey + KeyPad 7 |link:#review top[reviews top] - -|KeyPad 8 |link:#review current line[reviews current line] - -|KeyPad 7 |link:#review previous line[reviews previous line] - -|KeyPad 9 |link:#review next line[reviews next line] - -|FenrirKey + KeyPad 4 |link:#review line beginning[reviews line -beginning] - -|FenrirKey + KeyPad 6 |link:#review line ending[reviews line ending] - -|FenrirKey + KeyPad 1 |link:#review line first character[reviews line -first character] - -|FenrirKey + KeyPad 3 |link:#review line last character[reviews line -last character] - -|FenrirKey + Alt + 1 |link:#present first line[presents first line] - -|FenrirKey + Alt + 2 |link:#present last line[presents last line] - -|KeyPad 5 |link:#review current word[reviews current word] - -|KeyPad 4 |link:#review previous word[reviews previous word] - -|KeyPad 6 |link:#review next word[reviews next word] - -|FenrirKey + Shift + KeyPad 5 -|link:#review current word phonetic[reviews current word phonetic] - -|FenrirKey + Shift + KeyPad 4 -|link:#review previous word phonetic[reviews previous word phonetic] - -|FenrirKey + Shift + KeyPad 6 |link:#review next word phonetic[reviews -next word phonetic] - -|KeyPad 2 |link:#review current character[reviews current char] - -|KeyPad 1 |link:#review previous character[reviews previous char] - -|KeyPad 3 |link:#review next character[reviews next char] - -|FenrirKey + Shift + KeyPad 2 -|link:#review current character phonetic[reviews current character -phonetic] - -|FenrirKey + Shift + KeyPad 1 -|link:#review previous character phonetic[reviews previous character -phonetic] - -|FenrirKey + Shift + KeyPad 3 -|link:#review next character phonetic[reviews next character phonetic] - -|FenrirKey + CTRL + KeyPad 8 |link:#review up[reviews up] - -|FenrirKey + CTRL + KeyPad 2 |link:#review down[reviews down] - -|FenrirKey + I |link:#indent current line[indent curr line] - -|FenrirKey + KeyPad 5 |link:#current screen[current screen] - -|FenrirKey + KeyPad 8 |link:#current screen before cursor[current screen -before cursor] - -|FenrirKey + KeyPad 2 |link:#current screen after cursor[current screen -after cursor] - -| |link:#cursor read to end of line[cursor read to end of line] - -|link:#Tutorial mode[Tutorial mode] | - -|FenrirKey + H |link:#Tutorial Mode[toggle tutorial mode] - -|link:#Information[Information] | - -|FenrirKey + T |link:#Time[Announce time] - -|FenrirKey + T +T |link:#Date[Announce date] - -|FenrirKey + CTRL + |link:#clear Bookmark [clear bookmark number -] - -|FenrirKey + Shift + |link:#set Bookmark [set bookmark number -] - -|FenrirKey + |link:#read Bookmark [read bookmark number ] - -|KeyPad dot |link:#cursor position[cursor position] - -| |link:#cursor column[cursor column] - -| |link:#cursor line number[cursor line number] - -|link:#Screen Interaction[Screen Interaction] | - -|FenrirKey + CTRL + Shift + C |link:#clear clipboard[clears clipboard] - -|FenrirKey + Home |link:#first clipboard[first clipboard] - -|FenrirKey + End |link:#last clipboard[last clipboard] - -|FenrirKey + PageUp |link:#previous clipboard[previous clipboard] - -|FenrirKey + PageDown |link:#next clipboard[next clipboard] - -|FenrirKey + Shift + C |link:#read current clipboard[current clipboard] - -|FenrirKey + C |link:#copy marked to clipboard[copy marked text to -clipboard] - -|FenrirKey + V |link:#paste clipboard[paste clipboard contents] - -|FenrirKey + P |link:#import clipboard from file[import clipboard from -file] - -|FenrirKey + Alt + Shift +C |link:#export clipboard to file[export -clipboard to file] - -|FenrirKey + CTRL + Shift + X |link:#Remove Marks[remove marks] - -|FenrirKey + X |link:#Set mark[set mark] - -|FenrirKey + Shift + X |link:#Get text between marks[announce marked -text] - -| |export clipboard to X - -|link:#Window mode[Window mode] | - -|FenrirKey + KeyPad Slash |link:#Create Window[set window application] - -|2 * FenrirKey + KeyPad Slash |link:#Remove Window[clear window -application] - -|KeyPad Plus |link:#last incoming[read last incoming] - -|link:/#Quick Settings/ toggle or switch[Quick settings: toggle or -switch] | - -|Compose + L |link:#switch language[switch language] - -|FenrirKey + F3 |link:#toggle sound[toggles sound] - -|FenrirKey + F4 |link:#toggle speech[toggles speech] - -|KeyPad Enter |link:#disable speech temporarily[temporarily disables -speech] - -|FenrirKey + CTRL + P |link:#toggle punctuation level[toggles -punctuation level] - -|FenrirKey + RightBrace |link:#toggle auto spell check[toggle auto spell -check] - -|FenrirKey + Backslash |link:#toggle output[toggles output] - -|FenrirKey + CTRL + E |link:#toggle emoticons[toggles emoticons] - -|FenrirKey + KeyPad Enter |link:#toggle auto read[toggles auto read] - -|FenrirKey + CTRL + T |link:#toggle auto time[toggles auto time] - -|FenrirKey + KeyPad ASTERISK |link:#toggle highlight tracking[toggles -highlight tracking] - -|link:/#Quick Settings/ speech and sound[Quick Settings: speech and -sound] | - -|FenrirKey + Up |link:#increase speech volume[increase speech volume] - -|FenrirKey + Down |link:#decrease speech volume[decrease speech volume] - -|FenrirKey + Right |link:#increase speech rate[increase speech rate] - -|FenrirKey + Left |link:#decrease speech rate[decrease speech rate] - -|FenrirKey + Alt + Right |link:#increase speech pitch[increase speech -pitch] - -|FenrirKey + Alt + Left |link:#decrease speech pitch[decrease speech -pitch] - -|FenrirKey + Alt + Up |link:#increase sound volume[increase sound -volume] - -|FenrirKey + Alt + Down |link:#decrease sound volume[decrease sound -volume] - -|FenrirKey + CTRL + Up |increase Alsa volume - -|FenrirKey + CTRL + Down |decrease Alsa volume - -|link:#Spellchecker[Spell checker] | - -|FenrirKey + S |link:#spell check[spell check] - -|2 * FenrirKey + S |link:#add word to spell check[add word to spell -check] - -|FenrirKey + Shift + S |link:#removes word from spell check[removes word -from spell check] - -|FenrirKey + Backspace |link:#forward keypress[forward keypress] +|Shortcut |Action +|Fenrir{plus}Space |Announce current setting +|Fenrir{plus}Left / Right |Previous / next setting +|Fenrir{plus}Control{plus}Left / Right |Previous / next category +|Fenrir{plus}Up / Down |Change value +|Fenrir{plus}Control{plus}S |Save settings |=== -=== Laptop Layout +Quick changes apply to the current session. Save to retain them for +future launches. Session controls such as mute and temporary silence are +separate from saved startup preferences. + +=== Clipboard + +Use review navigation to place two marks around text with +*Fenrir{plus}X*, then press *Fenrir{plus}C* to copy it. In table mode +Fenrir{plus}X sets headers instead. [cols=",",options="header",] |=== -|Shortcut |Command -|link:#General[General] | - -|FenrirKey + H |link:#Tutorial Mode[toggle tutorial mode] - -|CTRL |link:#shut up[shut up (interrupts speech)] - -|link:#Review modes[Review modes] | - -|FenrirKey + Shift + O |link:#review bottom[reviews bottom] - -|FenrirKey + Shift + U |link:#review top[reviews top] - -|FenrirKey + I |link:#review current line[reviews current line] - -|FenrirKey + U |link:#review previous line[reviews previous line] - -|FenrirKey + O |link:#review next line[reviews next line] - -|FenrirKey + Shift + J |link:#review line beginning[reviews line -beginning] - -|FenrirKey + Shift + L |link:#review line ending[reviews line ending] - -|FenrirKey + CTRL + J |link:#review line first character[reviews line -first character] - -|FenrirKey + CTRL + L |link:#review line last character[reviews line -last character] - -|FenrirKey + Alt + 1 |link:#present first line[presents first line] - -|FenrirKey + Alt + 2 |link:#present last line[presents last line] - -|FenrirKey + K |link:#review current word[reviews current word] - -|FenrirKey + J |link:#review previous word[reviews previous word] - -|FenrirKey + L |link:#review next word[reviews next word] - -|FenrirKey + CTRL + ALT + K |link:#review current word phonetic[reviews -current word phonetic] - -|FenrirKey + CTRL + ALT + J |link:#review previous word phonetic[reviews -previous word phonetic] - -|FenrirKey + CTRL + ALT + L |link:#review next word phonetic[reviews -next word phonetic] - -|FenrirKey + comma |link:#review current character[reviews current -character] - -|FenrirKey + M |link:#review previous character[reviews previous -character] - -|FenrirKey + dot |link:#review next character[reviews next character] - -|FenrirKey + CTRL + ALT + comma -|link:#review current character phonetic[reviews current character -phonetic] - -|FenrirKey + CTRL + ALT + M -|link:#review previous character phonetic[reviews previous character -phonetic] - -|FenrirKey + CTRL + ALT + dot -|link:#review next character phonetic[reviews next character phonetic] - -|FenrirKey + CTRL + I |link:#review up[reviews up] - -|FenrirKey + CTRL + comma |link:#review down[reviews down] - -|FenrirKey + Slash |link:#exit review[exit review] - -|FenrirKey + Shift + dot |link:#cursor position[cursor position] - -|FenrirKey + I +I |link:#indent current line[indent curr line] - -|FenrirKey + Shift + K |link:#current screen[current screen] - -|FenrirKey + Shift + I |link:#current screen before cursor[current -screen before cursor] - -|FenrirKey + Shift + comma |link:#current screen after cursor[current -screen after cursor] - -| |link:#cursor read to end of line[cursor read to end of line] - -|link:#Tutorial mode[Tutorial mode] | - -|FenrirKey + H |link:#Tutorial Mode[toggle tutorial mode] - -|link:#Information[Information] | - -|FenrirKey + T |link:#Time[Announce time] - -|FenrirKey + T +T |link:#Date[Announce date] - -|FenrirKey + CTRL + |link:#clear Bookmark [clear bookmark number -] - -|FenrirKey + Shift + 1 |link:#set Bookmark [set bookmark bumber ] - -|FenrirKey + 1 |link:#read Bookmark [bookmark number ] - -| |link:#cursor column[cursor column] - -| |link:#cursor line number[cursor line number] - -|link:#Screen Interaction[Screen Interaction] | - -|FenrirKey + CTRL + Shift + C |link:#clear clipboard[clears clipboard] - -|FenrirKey + Home |link:#first clipboard[first clipboard] - -|FenrirKey + End |link:#last clipboard[last clipboard] - -|FenrirKey + PageUp |link:#previous clipboard[previous clipboard] - -|FenrirKey + PageDown |link:#next clipboard[next clipboard] - -|FenrirKey + Shift + C |link:#read current clipboard[current clipboard] - -|FenrirKey + C |link:#copy marked to clipboard[copy marked text to -clipboard] - -|FenrirKey + V |link:#paste clipboard[paste clipboard contents] - -|FenrirKey + F5 |link:#import clipboard from file[import clipboard from -file] - -|FenrirKey + Alt + Shift +C |link:#export clipboard to file[export -clipboard to file] - -|FenrirKey + CTRL + Shift + X |link:#Remove Marks[remove marks] - -|FenrirKey + X |link:#Set mark[set mark] - -|FenrirKey + Shift + X |link:#Get text between marks[announce marked -text] - -| |export clipboard to X - -|link:#Window mode[Window mode] | - -|FenrirKey + CTRL + 8 |link:#Create Window[set window application] - -|2 * FenrirKey + CTRL + 8 |link:#Remove Window[clear window application] - -|FenrirKey + Semicolon |link:#last incoming[read last incoming] - -|link:/#Quick Settings/ toggle or switch[Quick settings: toggle or -switch] | - -|Compose + L |link:#switch language[switch language] - -|FenrirKey + F3 |link:#toggle sound[toggles sound] - -|FenrirKey + F4 |link:#toggle speech[toggles speech] - -|FenrirKey + Enter |link:#disable speech temporarily[temporarily -disables speech] - -|FenrirKey + Shift + CTRL + P |link:#toggle punctuation level[toggles -punctuation level] - -|FenrirKey + RightBrace |link:#toggle auto spell check[toggle auto spell -check] - -|FenrirKey + Shift + Enter |link:#toggle output[toggles output] - -|FenrirKey + Shift + E |link:#toggle emoticons[toggles emoticons] - -|FenrirKey + Enter |link:#toggle auto read[toggles auto read] - -|FenrirKey + CTRL + T |link:#toggle auto time[toggles auto time] - -|FenrirKey + Y |link:#toggle highlight tracking[toggles highlight -tracking] - -|FenrirKey + Q |link:#quit Fenrir[quits fenrir] - -|FenrirKey + T |link:#Time[Announce time] - -|FenrirKey + T +T |link:#Date[Announce date] - -|link:/#Quick Settings/ speech and sound[Quick Settings: speech and -sound] | - -|FenrirKey + Up |link:#increase speech volume[increase speech volume] - -|FenrirKey + Down |link:#decrease speech volume[decrease speech volume] - -|FenrirKey + Right |link:#increase speech rate[increase speech rate] - -|FenrirKey + Left |link:#decrease speech rate[decrease speech rate] - -|FenrirKey + Alt + Right |link:#increase speech pitch[increase speech -pitch] - -|FenrirKey + Alt + Left |link:#decrease speech pitch[decrease speech -pitch] - -|FenrirKey + Alt + Up |link:#increase sound volume[increase sound -volume] - -|FenrirKey + Alt + Down |link:#decrease sound volume[decrease sound -volume] - -|FenrirKey + CTRL + Up |increases Alsa volume - -|FenrirKey + CTRL + Down |decreases Alsa volume - -|link:#Spellchecker[Spell checker] | - -|FenrirKey + S |link:#spell check[spell check] - -|FenrirKey + S +S |link:#add word to spell check[add word to spell -check] - -|FenrirKey + Shift + S |link:#removes word from spell check[removes word -from spell check] - -|FenrirKey + Backspace |link:#forward keypress[forward keypress] +|Shortcut |Action +|Fenrir{plus}Shift{plus}X |Read marked text +|Fenrir{plus}Control{plus}Shift{plus}X |Remove marks +|Fenrir{plus}C |Copy marked text +|Fenrir{plus}Control{plus}C |Copy last presented text +|Fenrir{plus}Shift{plus}C |Read selected clipboard +|Fenrir{plus}Control{plus}Shift{plus}C |Clear selected clipboard +|Fenrir{plus}Home / End |First / last clipboard +|Fenrir{plus}PageUp / PageDown |Previous / next clipboard +|Fenrir{plus}V |Paste selected clipboard +|Fenrir{plus}F5 / F6 |Import from / export to file +|Fenrir{plus}F7 / F8 |Import from / export to X clipboard |=== -=== General - -==== quit Fenrir - -Just stops fenrir. - -==== shut up - -Interrupt the current spoken. - -=== Review Modes - -Fenrir provides a virtual cursor, with it you can navigate all over the -screen without changing the text cursor. + -Using the review feature will open the review mode automatically. + -The review cursor always starts from the text cursor. Attention: after -using the review mode, the review cursor will stay open until you use -the `+exit review+` shortcut. + -Think when using clipboard operations and similar. The review cursor is -always preferred over the text cursor. + -Fenrir sounds a bell sound if the used review command jumps to another -line or end of screen. - -==== exit review - -You can leave the review mode by pressing the `+exit review+` shortcut. - -==== review bottom - -Set the review cursor to first column in the last line. - -==== review top - -Set the review cursor to the first column in the first line - -==== review current line - -Set the review cursor to the beginn of the the current line and review -it. - -==== review previous line - -Set the review cursor to the previous line and review it. - -==== review next line - -Set the review cursor to the next line and review it. - -==== review line beginning - -Set the review cursor to the begin of the current line - -==== review line ending - -Set the review cursor to the end of the current line - -==== review line first character - -Set the review cursor the first char (that is not space) in the current -line and review it. - -==== review line last character - -Set the review cursor the last char (that is not space) in the current -line and review it. - -==== review current word - -Sets the review cursor to the beginning of the current word and review -it. - -==== review previous word - -Sets the review cursor to the beginning of the previous word and review -it. - -==== review next word - -Sets the review cursor to the beginning of the next word and review it. - -==== review current word phonetic - -Sets the review cursor to the beginning of the current word and spell it -phonetic. - -==== review previous word phonetic - -Sets the review cursor to the beginning of the previous word and spell -it phonetic. - -==== review next word phonetic - -Sets the review cursor to the beginning of the next word and spell it -phonetic. - -==== review current character - -Does not change the review cursor. Just announce the current char. - -==== review previous character - -Sets review cursor to the previous column and review it - -==== review next character - -Sets review cursor to the next column and review it - -==== review current character phonetic - -Does not change the review cursor. Just announce the current char -phonetic. - -==== review previous character phonetic - -Sets review cursor to the previous column and announce the char -phonetic. - -==== review next character phonetic - -Sets review cursor to the next column and announce the char phonetic. - -==== review up - -Set the review cursor in the same column one line above the current one -and review it. - -==== review down - -Set the review cursor in the same column one line below the current one -and review it. A mark defines a point of origin or end to prepare to -copy or paste a block of text. + -Examples where you need marks are: - -* copy to clipboard -* set window application -* set bookmark 1 - X - -==== Set mark - -How to set a mark: - -. navigate with review or textcursor to the position you want to set the -mark. Attention: if a review cursor is set, that is the prefered. If you -want to use text cursor, be sure that you are not in review mode. -. press shortcut for `+set mark+` - -you can set two marks (begin and end). Some commands allow some simpler -usecases just using the whole line if only one mark is set. you may want -to try this out. - -==== Get text between marks - -To get the text that is currently between your marks press shortcut for -`+marked text+`. + -=== Remove Marks === You can remove all current marks by pressing the -shortcut for `+remove marks+`. Changing the screen also removes the -marks. - -=== Screen Interaction - -Fenrir provides several methods to interact with the current screen. - -==== forward keypress - -This just forwards the next shortcut to the screen Fenrir shortcut or -not. This is useful if the currently pressed shortcut is also in use by -Fenrir. - -==== Clipboard - -Fenrir provides a clipboard with multible items represented by a list. -You navigate throught the list and paste the selected clipboard. - -===== copy marked to clipboard - -To copy something to the clipboard you need to set one or two marks. if -you set one mark, the text between the mark and your current cursor is -copied to clipboard. Setting two marks just copies the text between the -marks into the clipboard. If you copy something it is always placed as -the first item on your clipboard. - -===== clear clipboard - -You can remove all items from the current clipboard by -`+clear clipboard+` functionality. - -===== first clipboard - -This moves quick to the first item of the clipboard. - -===== last clipboard - -This moves quick to the last item of the clipboard. - -===== previous clipboard - -Go to previous item in the clipboard. - -===== next clipboard - -Go to next item on the clipboard. - -===== read current clipboard - -Read the content of the current item of the clipboard. - -===== paste clipboard - -Pass whatever item is currently selected by first, last, prev or next -clipboard commands. if no special clipboard is selected the (last -copied) is used. - -===== export clipboard to file - -This allows you to export the current clipboard to a configurable -filepath. This is useful to share the clipboard with a graphical -desktop. - -===== import clipboard from file - -Import a clipboard from a configurable file. This is useful to share the -clipboard with a graphical desktop. - -=== Quick Settings: toggle or switch - -Fenrir provides shortcuts to change settings temporarily and on the fly -without the need to permanently change the `+settings.conf+` file. - -==== switch language - -switch between the languages listed in the line beginning with langages= -in `+setting.conf+` during run time. The next language after the current -one will be used. - -==== toggle braille - -Enables and disables Braille. This is not persistent stored in your -`+settings.conf+` but during run time. - -==== toggle sound - -Enables and disables sound. This is not persistent stored in your -`+settings.conf+` but during run time. - -==== toggle speech - -Enables and disables speech. This is not persistent stored in your -`+settings.conf+` but during run time. - -==== disable speech temporarily - -Disables the speech until next key press. it might be useful if you want -to listen to music or similar. As soon as a key is pressed it is going -to be enabled again. - -==== toggle punctuation level - -Cycle between all available punctuation levels. This is not persistent -stored in your `+settings.conf+` but during run time. - -==== toggle auto spell check - -Enables and disables automatic spellchecker (when typing). This is not -persistent stored in your `+settings.conf+` but during run time. - -==== toggle emoticons - -Enables and disables emoticons. This is not persistent stored in your -`+settings.conf+` but during runtime. - -==== toggle output - -Enables and disables all output at once (sound, Braille, speech). This -is not persistent stored in your `+settings.conf+` but during run time. - -==== toggle auto read - -Enables and disables what is automatically spoken. This is not -persistent stored in your `+settings.conf+` but during run time. - -==== toggle auto time - -Enables and disables auto time functionality. This is not persistent -stored in your `+settings.conf+` but during run time. - -==== toggle highlight tracking - -Enables and disables highlight tracking. This is not persistent stored -in your `+settings.conf+` but during run time. - -=== Quick Settings: speech and sound - -==== increase speech volume - -Increase the volume of the speech. This is not persistent stored in your -`+settings.conf+` but during runtime. - -==== decrease speech volume - -Decrease the volume of the speech. This is not persistent stored in your -`+settings.conf+` but during runtime. - -==== increase speech rate - -Increase the rate of the speech. This is not persistent stored in your -`+settings.conf+` but during runtime. - -==== decrease speech rate - -Decrease the rate of the speech. This is not persistent stored in your -`+settings.conf+` but during runtime. - -==== increase speech pitch - -Increase the pitch of the speech. This is not persistent stored in your -`+settings.conf+` but during runtime. - -==== decrease speech pitch - -Decrease the pitch of the speech. This is not persistent stored in your -`+settings.conf+` but during runtime. - -==== increase sound volume - -Increase the volume of the sound. This is not persistent stored in your -`+settings.conf+` but during runtime. - -==== decrease sound volume - -Decrease the volume of the sound. This is not persistent stored in your -`+settings.conf+` but during runtime. - -=== Window Mode - -Fenrir supports window mode, a window is a partial area of the screen. - -==== Create Window - -To create a window you need to do the following: - -. set a beginning mark (as the start of the window) -. set an end mark (where the window should end) -. press `+set window application+` shortcut. - -Now Fenrir ignores anything outside of the window. + -=== Remove Window === You can remove the window by pressing -`+the clear window application+` shortcut. Now Fenrir will read -everything on the screen again. - -=== Tracking Modes - -Different types of tracking are currently supported See section -link:#Focus[Focus] in `+settings.conf+` for more information. - -==== Cursor Tracking - -This follows the text cursor. This is the typical way an application -works. This is used by: - -* almost any shell such as (Bash, Zsh, sh) -* vim -* nano -* emacs -* mutt -* tintin++ - -==== Highlight Tracking - -In some applications there are no text cursors. In those applications -cursor changes are represented by different colors or attributes -(underlined or bold). This mode tracks and announces these changes for -you. This is used by: - -.... - * wifi-menu - * dialog - * alpine -.... - -=== Tutorial Mode - -Fenrir provides a Tutorial mode. When you enter tutorial mode, screen -reader commands are intercepted and explained instead of executing them. -`+Arrow up+` and `+Arrow Down+` let you navigate through a list of all -available commands with shortcuts and description. Pressing escape -leaves the tutorial mode. - -=== Information - -==== Time - -Announces the current Time. - -==== Date - -Announces the current Date. - -==== Bookmarks - -Bookmarks provide quick access to part of the screen without the need to -navigate to the area. By default Fenrir provides 10 bookmarks. Those can -be set and accessed via shortcut. This is useful for status lines or -other information where the position does not change. - -===== set Bookmark - -You need to set the bookmark first. For that you have to set one or two -lines for use. - -. Set marks (one or two) -. press shortcut for `+set bookmark +`. represents the number 1 - -10 (set bookmark 0 for the tenth bookmark). - -===== read Bookmark - -If a bookmark is set you can access the area just by pressing the -`+bookmark +` shortcut. represents the number 1 - 10. Bookmarks -are dynamic. That means the content changes with the screen. - -===== clear Bookmark - -to remove a bookmark just press the `+clear bookmark +` shortcut. -represents the number 1 - . Afterward the bookmark is no longer -available. - -==== cursor position - -You can get information about the current cursor and its position by -using the "cursor position" functionality. - -==== indent current line - -Announce the current indent level of the current line. It represents the -number of trailing spaces of the line. - -==== current screen - -Reads all the current screen from the beginning to the end. - -==== current screen before cursor - -Reads current screen from the beginning of the screen to the current -cursor position. - -==== current screen after cursor - -Read anything after current cursor position to the end. - -==== cursor read to end of line - -Read from the current cursor position to the end of the current line. - -==== cursor column - -Read the current X position of a cursor (column of the current line). - -==== cursor line number - -Read the current Y position of a cursor (line number). - -==== present first line - -Reads just the first line. this is maybe useful for status information. - -==== present last line - -Presets the last line. This is maybe useful for status information. - -==== last incoming - -Repeat the last automatically incoming text. - -=== Input - -==== Echo - -Fenrir provides different methods of echoing content: - -* Word: Will speak each word after you push space -* Character: speak any letter you type on the screen -* Delete Character: speaks the character prior to the cursor when you -push backspace - -==== Silence on Key press - -==== Spellchecker - -Fenrir has a built-in spellchecker, it can invoke automatically while -typing or be called by a shortcut. Commands to add or remove the current -word to the dictionary are included. As using the spellchecker is -enhanced usage. You will need dictionary aspell-. See section -link:#General[General] in `+settings.conf+` for more information. - -===== spell check - -Invokes the spellcheck on the word that contains the Review or text -cursor. - -===== add word to spell check - -Adds the word under the Review or Text cursor to the dictionary. - -===== removes word from spell check - -Removes the word under the Review or Text cursor from the dictionary. - -=== Announcements - -==== Emoticons - -If you want to replace ":)" emoticons with "smile" in speech you can use -this feature. It can be toggled on or off. You can define emoticons in a -dictionary, please see Emoticon Dictionary. See section -link:#General[General] in `+settings.conf+` to see how to enable or -disable this feature. - -==== Time - -Announce the time at periodical increments, To track the time easily. -You can define 2 different ways of time announcements. - -. periodic -. on fix minutes - -The settings proposed below can be implemented editing in the -link:#Configuration file[configuration file] - -Example periodic, every 20 minutes "delaySec=20": - -.... -[time] -enabled=True -presentTime=True -presentDate=True -delaySec=20 -onMinutes= -announce=True -interrupt=False -.... - -Example on fix minutes in an hour. example every quarter "delaySec=0" -and "onMinutes=00,15,30,45": - -.... -[time] -enabled=True -presentTime=True -presentDate=True -#delaySec is respected before onMinutes so it need to be set to 0 -delaySec=0 -onMinutes=00,15,30,45 -announce=True -interrupt=False -.... - -=== Dictionary - -You can make use of different kinds of built-in dictionary's. A -dictionary has a name and list of keys and values separated by :===: -Example to be set in the link:#Configuration file[configuration file] - -.... -[customDict] -Chrys:===:Chrys is cool -lollipop:===:lolli -.... - -that means that every instance "chrys" is displayed, speech will say -Chrys is cool. "lollipop" is spoken as "lolli". Before making changes to -a dictionary we recommend making a backup of your current dictionary in -case future updates overwrite your local changes. - -==== Punctuation - -The default punctuation settings are recorded in thd directory -/etc/fenrirscreenreader/punctuation/default.conf - -===== Level - -The punctuation level dict contains lists with "what punctuation is -spoken in what level". the default one looks like this: - -.... -[levelDict] -none:===: -some:===:.-$~+*-/\@ -most:===:.,:-$~+*-/\@!#%^&*()[]}{<>; -all:===:!"#$%& \'()*+,-./:;<=>?@[\\]^_`{|}~ -.... - -the level "none" has no values. so it should not speak any punctuation -(sadly this is not respected by every TTS system) if "some" is the -current level the following are spoken: dot dash dollar tilde plus star -slash backslash at. same for most and all, you can add new levels. if -you cycle punctuation levels they are recognized. the default -punctuation level is set in settings.conf. The default is "some". - -===== Punctuation - -The punctuation dictionary "[punctDict]" contains how the punctuation is -spoken. Example: - -.... -[punctDict] -_:===:line -.... - -speaks an _ as "line". - -.... -[punctDict] -_:===:underscore -.... - -speaks an _ as underscore. for question mark an ? is appended to the -word that the TTS system can announce the question correctly. - -==== Custom - -The dict "[customDict]" is just for your own use, it just replace the -key with the value without any special functionality. This might be used -to fix incorrectly spoken words, make words more common, shorter or just -for fun. :) - -==== Emoticons - -The Emoticons dictionary "[emoticonDict]" by default contains some -emoticons. it can replace ":)" with "smile" or "XD" with "loool" Making -chat more colorful. A nice feature with this dictionary is that you can -toggle the substitution on or off during run time or in settings.conf. -This is useful because while doing programming or other serious work you -want to hear colons and perryns not smiles. - -== Configuration - -You can configure Fenrir in the following places (ordered by priority): - -. Commandline Parameters `+-o+` see link:#Set settings options[Set -settings options] -. /etc/fenrirscreenreader/settings/settings.conf see -link:#Settings[Settings] -. hard coded defaults - -=== Commandline Arguments - -Fenrir supports several command-line options: - -.... -fenrir [OPTIONS] -.... - -==== Available Options - -`+-h, --help+`:: -Show help message and exit. - -`+-v, --version+`:: -Show version information and exit. - -`+-f, --foreground+`:: -Run Fenrir in the foreground instead of as a daemon. - -`+-s, --setting SETTING-FILE+`:: -Path to a custom settings file. - -`+-o, --options SECTION#SETTING=VALUE;..+`:: -Override settings file options (see below for details). - -`+-d, --debug+`:: -Enable debug mode. Debug information will be logged. - -`+-p, --print+`:: -Print debug messages to screen in addition to logging them. - -`+-F, --force-all-screens+`:: -Force Fenrir to respond on all screens, ignoring the ignore_screen setting. This temporarily overrides screen filtering for the current session. - -`+-i, -I, --ignore-screen +`:: -Ignore specific screen(s). Can be used multiple times to ignore multiple screens. This is equivalent to setting ignore_screen in the configuration file and will be combined with any existing ignore settings. - -==== Set settings options - -You can specify options that overwrite the setting.conf. This is done -with `+-o +` parameter. The list of options have the -following syntax - -.... -fenrir -o "section#setting=value;section#setting=value" -.... - -For example changing the sound driver to gstreamer and disabling Braille - -.... -fenrir -o "sound#driver=gstreamerDriver;braille#enabled=False=False" -.... - -or change the debug level to verbose - -.... -fenrir -o "general#debugLevel=3" -.... - -Example using force all screens option: - -.... -fenrir -F -.... - -You can find the available sections and variables here #Settings See -Syntax link:#settings.conf syntax[#settings.conf syntax] - -=== Remote Control - -Fenrir includes a powerful remote control system that allows external applications and scripts to control Fenrir through Unix sockets or TCP connections. - -==== Configuration - -Enable remote control in settings.conf: - -.... -[remote] -enable=True -driver=unixDriver -enable_settings_remote=True -enable_command_remote=True -.... - -==== Using socat with Unix Sockets - -The `+socat+` command provides the easiest way to send commands to Fenrir: - -===== Instance Discovery - -.... -# List registered Fenrir instances and their socket paths +`clipboard.number++_++of++_++clipboards` limits history; the default is +200. `clipboard.export++_++path` selects the import/export file, +initially `/tmp/fenrirClipboard`. `clipboard.sync` enables automatic X +clipboard synchronization, which requires `xclip` and access to the X +display. + +Persistent history is optional and off by default. Set +`clipboard.persistent` to retain unencrypted history across launches. +Terminal sessions use `~/.local/state/fenrir/clipboard/terminal.json`; +console sessions use `/var/lib/fenrir/clipboard/tty.json`. Same-user +readers of the same mode share persistent history. + +=== Spell checking and emoji + +Automatic spell checking uses Enchant 2 and a dictionary matching the +session language. Reading settings control word repetition, spoken +misspelling feedback, and misspelling sounds. + +Press *Fenrir{plus}S* to open the Spellcheck Menu for the current word. +The Suggestions tab lets you edit the word and choose a suggested +spelling. The Exceptions tab lets you add words, remove selected entries +with Delete, and undo a removal. Selecting a suggestion copies it to +Fenrir’s clipboard; paste it with Fenrir{plus}V. + +Press *Fenrir{plus}Control{plus}E* to open the Emoji Menu. Choose a +category at the tab selector, then Tab to the emoji grid. Arrows +navigate, typing filters by name prefix, and Control{plus}Backspace +clears the filter. Enter copies the selected emoji to Fenrir’s +clipboard. Escape closes the menu. + +=== Reading windows and live regions + +Reading regions belong to the current terminal and last for the reader +session. A reading window restricts automatic reading to a rectangle. +Live regions exclude changing areas from automatic speech while allowing +explicit reading and progress monitoring. + +Outside table mode, place two marks with *Fenrir{plus}X* to define +opposite corners. Press *Fenrir{plus}Keypad Slash* on desktop or +*Fenrir{plus}Control{plus}8* on laptop to set a reading window. Press +the shortcut twice quickly to clear it. + +To create a live region, place one mark for the rest of that line, or +two marks for a rectangle, then press *Fenrir{plus}B*. Fenrir assigns +the first free slot, up to ten. Region creation clears the marks. + +* *Fenrir{plus}1* through *Fenrir{plus}0* read live regions 1 through +10. +* *Fenrir{plus}Shift{plus}1* through *Fenrir{plus}Shift{plus}0* clear +individual live regions. +* *Fenrir{plus}Shift{plus}B* lists the current reading regions. +* *Fenrir{plus}Control{plus}B* clears all live regions. +* *Fenrir{plus}Control{plus}Shift{plus}B* clears both the reading window +and live regions. + +=== Sound and progress + +Sound output uses `pulse` for PulseAudio or PipeWire’s PulseAudio +service, or `alsa` for an ALSA PCM device. Select the driver and theme +in Sound settings. The ALSA device name is set with +`presentation.sound.device` in the file. + +Personal themes are searched under `~/.local/stormux/fenrir/sounds/` +before bundled and system themes. A theme contains WAV files and +`soundicons.toml`. + +Progress tones are controlled separately from speech and automatic +reading. Press *Keypad Plus* on desktop or *Fenrir{plus}Shift{plus}P* on +laptop to toggle them. Fenrir recognizes percentages, fractions, +progress bars, and activity indicators; tones rise with progress. +Startup behavior is set by `presentation.progress.enabled`. + +=== Configuration files + +Settings are TOML. The annotated +link:../config/settings/settings.toml[settings.toml] lists all available +options. Fenrir loads one settings file rather than merging files. + +* Regular users: first +`~/.local/share/stormux/fenrirscreenreader/settings/settings.toml`, then +`/etc/fenrirscreenreader/settings/settings.toml`. +* Root: `/etc/fenrirscreenreader/settings/settings.toml`. +* `--config PATH`: use that file explicitly. + +If default files are absent, Fenrir uses built-in defaults. An +explicitly selected file must exist. Saving targets the selected file; +if startup used built-in defaults, saving creates the first default path +for that account. + +Create a personal settings file and validate it without opening devices: + +[source,bash] +---- +./fenrir --write-config ~/.local/share/stormux/fenrirscreenreader/settings/settings.toml +./fenrir --config ~/.local/share/stormux/fenrirscreenreader/settings/settings.toml --check-config +---- + +Named keyboard layouts are searched in the regular user’s +`~/.local/share/stormux/fenrirscreenreader/keyboard/`, then +`/etc/fenrirscreenreader/keyboard/`, then `config/keyboard/` beside the +binary. Root searches the system and bundled locations. An explicit TOML +path selects one file. Custom layouts replace the complete layout; they +are not overlays. See the link:../config/keyboard/Readme.md[keyboard +guide] for an example. + +=== Speech synthesizers + +The default driver is `speech-dispatcher`. Select its module, language, +and voice in Speech settings; empty values use server defaults. + +Hardware driver IDs are `dectalk`, `dectalk-usb`, `litetalk`, +`doubletalk`, and `tripletalk`. Serial drivers require +`presentation.speech.hardware++_++device`, for example `/dev/ttyUSB0`, +and default to 9600 baud when `hardware++_++baud++_++rate = 0`. +DoubleTalk support targets the external LT device. TripleTalk USB +devices need to expose a serial tty. + +Native `dectalk-usb` uses libusb 1.0 and ignores serial settings. The +process needs access to the device. The Speech form’s *Test synthesizer* +button previews hardware choices before saving. Driver and port changes +apply at launch. + +=== Script shortcuts + +Fenrir searches `~/.local/stormux/fenrir/`, the configured +`general.script++_++path` (default +`/usr/share/fenrirscreenreader/scripts`), and the bundled +`config/scripts/` beside the binary. Earlier directories take priority. + +A filename such as `example++__++-++__++key++_++y.sh` assigns the script +key plus Y. The script key defaults to Compose and is configured by +`general.script++_++keys`. Scripts must be executable to run. Fenrir +invokes them directly and passes the current account name as the first +argument. Commands appear in the tutorial’s script list. + +=== Remote control + +Unix socket remote control is enabled by default. The standard socket is +`/tmp/fenrirscreenreader-daemon.sock`, and instances also have private +sockets `/tmp/fenrirscreenreader-++<++pid++>++.sock`. Set +`remote.socket++_++file` for a custom socket. + +Use `ls` to discover instances. Use a private socket to address one +reader: + +[source,bash] +---- echo "ls" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -.... - -In X terminal mode (`+fenrir -x+`), multiple Fenrir instances can run at the -same time. Each instance has a private socket at -`+/tmp/fenrirscreenreader-.sock+`, and one instance may also own the -standard control socket. Use `+ls+` or `+command ls+` on the standard socket to -find the private socket for a specific instance. Commands sent to the standard -socket are handled by its owner when possible; otherwise they are forwarded to a -registered private socket, preferring the sender's Fenrir ancestor when one can -be found. - -===== Basic Speech Control - -.... -# Interrupt current speech +echo "command say Hello" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock echo "command interrupt" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Speak custom text -echo "command say Hello, this is a test message" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Temporarily disable speech (until next keystroke) -echo "command tempdisablespeech" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -.... - -===== Settings Control - -.... -# Enable highlight tracking mode -echo "setting set focus#highlight=True" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Change speech rate -echo "setting set speech#rate=0.8" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Change punctuation level (none/some/most/all) -echo "setting set general#punctuation_level=all" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Voice and TTS control -echo "setting set speech#voice=en-us+f3" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Multiple settings at once -echo "setting set speech#rate=0.8;sound#volume=0.7;general#punctuation_level=most" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Reset all settings to defaults -echo "setting reset" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -.... - -===== Clipboard Operations - -.... -# Place text into clipboard -echo "command clipboard This text will be copied to clipboard" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Export clipboard to file -echo "command exportclipboard" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -.... - -===== Application Control - -.... -# Quit Fenrir -echo "command quitapplication" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -.... - -==== Command Reference - -===== Available Commands - -*Speech Commands:* - -* `+command say +` - Speak the specified text -* `+command interrupt+` - Stop current speech -* `+command tempdisablespeech+` - Disable speech until next key press -* `+ls+` / `+list+` / `+command ls+` / `+command list+` - List registered Fenrir instances - -*Clipboard Commands:* - -* `+command clipboard +` - Add text to clipboard -* `+command exportclipboard+` - Export clipboard to file - -*Window Commands:* - -* `+command window +` - Define window area -* `+command resetwindow+` - Reset to full screen - -*VMenu Commands:* - -* `+command vmenu +` - Set virtual menu context -* `+command resetvmenu+` - Reset virtual menu - -*Application Commands:* - -* `+command quitapplication+` - Quit Fenrir - -===== Available Settings - -*Settings Commands:* - -* `+setting set
#=+` - Set configuration value -* `+setting reset+` - Reset all settings to defaults -* `+setting save [path]+` - Save current settings - -*Key Settings You Can Control:* - -*Speech Settings:* -* `+speech#enabled=True/False+` - Enable/disable speech -* `+speech#rate=0.1-1.0+` - Speech rate (speed) -* `+speech#pitch=0.1-1.0+` - Speech pitch (tone) -* `+speech#volume=0.1-1.0+` - Speech volume -* `+speech#voice=voice_name+` - Voice selection (e.g., "en-us+f3") -* `+speech#module=module_name+` - TTS module (e.g., "espeak-ng") - -*General Settings:* -* `+general#punctuation_level=none/some/most/all+` - Punctuation verbosity -* `+general#auto_spell_check=True/False+` - Automatic spell checking -* `+general#emoticons=True/False+` - Enable emoticon replacement - -*Sound Settings:* -* `+sound#enabled=True/False+` - Enable/disable sound -* `+sound#volume=0.1-1.0+` - Sound volume - -*Focus Settings:* -* `+focus#cursor=True/False+` - Follow text cursor -* `+focus#highlight=True/False+` - Follow text highlighting - -*Keyboard Settings:* -* `+keyboard#char_echo_mode=0-2+` - Character echo (0=none, 1=always, 2=capslock only) -* `+keyboard#word_echo=True/False+` - Echo complete words - -*Screen Settings:* -* `+screen#ignore_screen=1,2,3+` - TTY screens to ignore - -==== settings.conf syntax - -the syntax of the link:#Settings[settings.conf] is quite simple and -similar to a "*.ini" file, there are 4 different elements. - -. Sections -. Settings -. Values -. Comments - -A comment starts with a # and is ignored by Fenrir. - -.... -# this is a comment -.... - -To group settings we have sections. A section can look like this: - -.... -[Section] -.... - -A setting looks like this: - -.... -settingName=Value -.... - -Example: - -.... -[sound] -# Turn sound on or off: -enabled=True -# Select the driver used to play sounds, choices are genericDriver and gstreamerDriver. -# Sox is default. -driver=genericDriver -.... - -=== Settings - -==== Sound - -The sound is configured in section `+[sound]+`. - -Turn sound on or off: - -.... -enabled=True -.... - -Values: on=`+True+`, off=`+False+` - -Select the driver used to play sounds. The genericDriver using Sox is -the default. - -.... -driver=genericDriver -.... - -Available Drivers: - -* `+genericDriver+` using the generic driver, for Fenrir <1.5 just use -`+generic+` -* `+gstreamerDriver+` using the gstreamer, for Fenrir <1.5 just use -`+gstreamer+` - -These are the pack of sounds used for sound icons. - -.... -theme=default -.... - -By default we ship two sound packs. - -. `+default+` opus encoded, for newer Sox versions -. `+default-wav+` wav encoded, just for compatibility - -Sound packs are located at /usr/share/sounds/fenrirscreenreader/ -User sound packs in `+~/.local/stormux/fenrir/sounds/+` are loaded before -system sound packs. - -Sound volume controls how loud the sounds for your selected sound pack -are. - -.... -volume=1.0 -.... - -Values: `+0.0+` is quietest, `+1.0+` is loudest. - -===== Generic Driver - -The generic sound driver uses shell commands for play sound and -frequencies. - -`+generic_play_file_command+` defines the command that is used to play a -sound file. - -.... -generic_play_file_command= -.... - -`+generic_frequency_command+` defines the command that is used playing -frequencies. - -.... -generic_frequency_command= -.... - -The following variables are substituted in `+generic_play_file_command+` -and `+generic_frequency_command+`: - -* `+fenrir_volume+` = the current volume setting -* `+fenrir_sound_file+` = the sound file for an sound icon -* `+fenrir_frequency+` = the frequency to play -* `+fenrir_duration+` = the duration of the frequency - -Example generic_play_file_command (default) - -.... -generic_play_file_command=play -q -v fenrir_volume fenrir_sound_file -.... - -Example generic_frequency_command (default) - -.... -generic_frequency_command=play -q -v fenrir_volume -n -c1 synth fenrir_duration sine fenrir_frequency -.... - -==== Speech - -Speech is configured in section `+[speech]+`. Turn speech on or off: - -.... -enabled=True -.... - -Values: on=`+True+`, off=`+False+` - -# Select speech driver, options are speechdDriver (default), -genericDriver, dectalkDriver, dectalkUsbDriver, litetalkDriver, -doubletalkDriver or tripletalkDriver: driver=speechdDriver -#driver=genericDriver -#driver=dectalkDriver -#driver=dectalkUsbDriver -#driver=litetalkDriver -#driver=doubletalkDriver -#driver=tripletalkDriver - -This Selects the driver used to generate speech output. - -We recommend top keep the default in Slint to benefit of all available -synthesizers and associated voices - -The rate selects how fast Fenrir will speak. - -.... -rate=0.5 -.... - -Values: Range Minimum:`+0.0+` is slowest, Maximum:`+1.0+` is fastest. - -Pitch controls the pitch of the voice. - -.... - pitch=0.5 -.... - -Values: Range Minimum:`+0.0+` is lowest, Maximum:`+1.0+` is highest. - -A Pitch for capital letters can be set. - -.... -capital_pitch=0.9 -.... - -Values: Range Minimum:`+0.0+` is lowest, Maximum:`+1.0+` is highest. - -The Volume controls the loudness of the voice. - -.... -volume=1.0 -.... - -Values: Range Minimum:`+0.0+` is quietest, Maximum:`+1.0+` is loudest. - -The Module sets here selects the synthesizer to use by -speech-dispatcher. If not set, the one set in -/etc/speech-dispatcher/speechd.conf will be used. + -TO list the available modules, type: - -.... -spd-list -s -.... - -To be able to switch languages on the fly, set below a module that -supports all languages between which you want to be able to switch. + -To make this choice type: - -.... -spd-list -.... - -Example of module setting: - -.... -module=espeak-ng -.... - -Voice selects the voice you want to use. This setting won't hold if you -switch languages on the fly (see below) or also set the language. + -To find out which voices are available, for a given module, type: - -.... -spd-say -o -L -.... - -For instance: - -.... -spd-say -o rhvoice -L -.... - -If you use the module espeak-ng or espak-ng-mbrola-generic , you can -also run: - -.... -espeak-ng-list-voices -.... - -Example using the pico module: - -.... -voice=virginie -.... - -Languages lists the languages among which to switch pressing: - -.... -Compose+l -.... - -The Compose key is the one between AltrGr and Ctrl on the right of the -space bar. + -For the module in use, the languages available can be listed with -typing: - -.... -spd-list -ls -.... - -For instance: - -.... -spd-list -ls espeak-ng-mbrola-generic -.... - -Be careful: all languages listed below should be provided by the module -in use, else switching languages on the fly won't be possible. Example -using the pico module: - -.... -languages=en-GB fr-FR es-ES it-IT -.... - -You can also set the language to use by default, which doesn't need to -be listed among the ones you might want to switch (but then you will -need to restart fenrir to get it back). + -It will supersede the voice that you might have also set. Example using -the pico module: - -.... -language=de-DE -.... - -Serial hardware speech drivers use a serial device. Set an explicit path. - -.... -hardware_device=/dev/ttyACM0 -hardware_device=/dev/ttyUSB0 -hardware_device=/dev/ttyS0 -.... - -Hardware speech drivers use 9600 baud by default. - -.... -hardware_baud_rate=9600 -.... - -The `+doubletalkDriver+` targets DoubleTalk LT-style serial devices. It does -not support the internal DoubleTalk PC ISA card. -The `+dectalkUsbDriver+` autodetects the native Access Solutions DECtalk USB, -USB ID `+0dd0:2001+`. It requires PyUSB and a libusb backend and ignores the -serial device and baud-rate settings. From a source checkout, install the USB -dependencies with `+python3 -m pip install '.[dectalk_usb]'+`. A non-root -Fenrir process needs a local udev rule granting its account read/write access -to `+0dd0:2001+`; do not make the device world-writable. Other USB hardware -speech synthesizers are supported only when Linux exposes them as a serial tty -such as `+/dev/ttyACM0+` or `+/dev/ttyUSB0+`. - -Read new text as it occurs auto_read_incoming=True Values: on=`+True+`, -off=`+False+` - -==== Screen - -The settings for screen access are configured in the `+[screen]+` -section. `+vcsaDriver+` is used for Linux TTYs, and `+ptyDriver+` is -used by X11 terminal mode. - -The driver to get the information from the screen: - -.... -driver=vcsaDriver -.... - -Available Drivers: - -* `+vcsaDriver+` using the VCSA driver (for TTYs), for Fenrir <1.5 just -use `+vcsa+` - -The encoding of the screen - -.... -encoding=cp850 -.... - -Values:`+cp850+` is used for Western languages like USA or Europe. - -The driver updates Fenrir with changes on the screen. - -.... -screen_update_delay=0.05 -.... - -Values: in Seconds - -If you want Fenrir to not be active on any screen for various reasons. -Maybe an X server or Wayland is running on that screen. You can make -Fenrir ignore it or multiple screens seperated by `+,+` with: - -.... -suspendingScreen= -.... - -Values: Depends on driver: - -* VCSA: the number of the TTY. TTY6 is `+6+`. - -Example ignore TTY1 and TTY2: - -.... -suspendingScreen=1,2 -.... - -There is also the ability to let Fenrir auto detect screens that are -running an X server. So Screens running an GUI can be ignored. - -.... -autodetectSuspendingScreen=True -.... - -Values: on=`+True+`, off=`+False+` - -==== Keyboard - -The settings for keyboard and input related configuration is located in -the section `+[keyboard]+` of the `+settings.conf+` file. - -Select the driver used for grabbing keybord input and for recieving -shortcuts. - -.... -driver=evdevDriver -.... - -Values: Text, available Driver Available Drivers: - -* `+evdevDriver+` uses the evdev input system of linux, for Fenrir <1.5 -just use `+evdev+` - -You can let Fenrir know about what input devices are to be used. - -.... -device=ALL -.... - -Values: - -* `+ALL+` use all devices with key capabilities. -* `+NOMICE+` Exclude mices from handling. -* `++` just use the device with the given name. - -Gives Fenrir exclusive access to the keyboard and lets it control -keystrokes. This is needed to intercept Fenrir related shortcuts. - -.... -grab_devices=True -.... - -Values: on=`+True+`, off=`+False+` - -The following makes sense if you are using a second screenreader and -want to have some hooked events. Fenrir ignores all shortcuts then. - -.... -ignore_shortcuts=False -.... - -Values: on=`+True+`, off=`+False+` - -The current keyboard layout used for shortcuts. - -.... -keyboard_layout=desktop -.... - -Values: An absolute Path to a Keyboard definition file or a Filename -without extension located in `+/etc/fenrirscreenreader/keyboard+` - -Announce characters while typing. - -.... -charEcho=False -.... - -Values: on=`+True+`, off=`+False+` - -Announce deleted characters - -.... -char_delete_echo=True -.... - -Values: on=`+True+`, off=`+False+` - -Announce word after pressing space - -.... -word_echo=False -.... - -Values: on=`+True+`, off=`+False+` - -Interrupt speech on any keypress - -.... -interrupt_on_key_press=False -.... - -Values: on=`+True+`, off=`+False+` - -You can filter the keys that speech should interrupt - -.... -interrupt_on_key_press_filter= -.... - -Values: (List) empty = all keys, otherwise interrupt with specified keys - -The timeout that is used for double tap shortcuts - -.... -double_tap_timeout=0.2 -.... - -Values: Seconds - -==== General - -Overall settings can be configured from the section `+[general]+`. - -Set the current debug level: - -.... -debugLevel=1 -.... - -Values: off=0, error=1, warning=2, info=3 - -the current punctuation and dict file in use: - -.... -punctuation_profile=default -.... - -Values: Text, see available profiles in `+/etc/fenrirscreenreader/punctuation+` or -in `+sourceTree/config/punctuation+` - -The current punctuation level in use: - -.... -punctuation_level=some -.... - -Values: Text, See available levels in the used punctuation file. - -Respect pause for punctuations: - -.... -respect_punctuation_pause=True -.... - -Values: on=`+True+`, off=`+False+` - -Add a pause on Line break: - -.... -new_line_pause=True -.... - -Values: on=`+True+`, off=`+False+` - -Specify the path where the clipboard should be exported to. See -link:#export clipboard to file[export clipboard to file]. The variable -`+$user+` is replaced by the current logged username. - -.... -[clipboard] -clipboard_export_path=/tmp/fenrirClipboard -.... - -Values: Text, Systemfilepath - -The number of available clipboards: - -.... -[clipboard] -number_of_clipboards=10 -.... - -Values: Integer, 1 - 999 - -Replace emoticons like :) or ;) with text insertions: - -.... -emoticons=True -.... - -Values: on=`+True+`, off=`+False+` - -Define the current Fenrir keys: - -.... -fenrir_keys=KEY_KP0,KEY_META,KEY_INSERT -.... - -Values, Text list, separated by comma. - -Define the current script keys: - -.... -scriptKey=KEY_COMPOSE -.... - -Values, Text list, separated by comma. - -The time format to be used for (time command) output: - -.... -timeFormat=%H:%M:%P -.... - -Values: see python specification for -https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior[datetime.strftime] - -The date format to be used for (date command) output: - -.... -dateFormat=%A, %B %d, %Y -.... - -Values: see python specification for -https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior[datetime.strftime] - -Enable or Disable spellcheck whilst typing: - -.... -auto_spell_check=True -.... - -Values: on=`+True+`, off=`+False+` - -The use of the dictionary with spellcheck: - -.... -spell_check_language=en_US -.... - -Values: Text, see aspell dictionary's. - -Folder Path for your scripts "scriptKey" functionality: - -.... -script_path=/usr/share/fenrirscreenreader/scripts -.... - -Values: Text, Existing path on file system. User scripts in -`+~/.local/stormux/fenrir/+` are loaded before this configured path. - -Override commands or create new ones without changing the Fenrir -defaults: - -.... -command_path=/usr/share/fenrirscreenreader/commands -.... - -Values: Text, Existing path on file system. Subfolders in command_path -are: - -* `+commands+` = to create shortcut commands -* `+onInput+` = executed while typing -* `+onScreenChange+` = executed on change the screen (change from TTY4 -to TTY6) -* `+onScreenUpdate+` = executed when the screen is captured - -==== Focus - -The configuration for basic focus is in the section `+[focus]+`. Follow -the text cursor: - -.... -cursor=True -.... - -Values: on=`+True+`, off=`+False+` - -Follow highlighted text changes (Highlight Tracking): - -.... -highlight=False -.... - -Values: on=`+True+`, off=`+False+` - -==== Review - -Configurations for the review mode are in the section `+[review]+`. - -If "next word/ char" or "prev word/char" create a linebreak, announce -it: - -.... -lineBreak=True -.... - -Values: on=`+True+`, off=`+False+` - -If "next word/ char" or "prev word/char" cannot be performed because you -reached the end of the screen, announce it: - -.... -endOfScreen=True -.... - -Values: on=`+True+`, off=`+False+` - -Leave the review mode when pressing a key: - -.... -leaveReviewOnKeypress=False -.... - -Values: on=`+True+`, off=`+False+` - -Leave the review mode when changing the screen (From TTY3 to TTY4): - -.... -leave_review_on_screen_change=True -.... - -Values: on=`+True+`, off=`+False+` - -==== Time - -The automated time announcement is configured in the section `+[time]+`. -Time announcement is disabled by default. Turn time announcement on or -off: - -.... -enabled=True -.... - -Values: on=`+True+`, off=`+False+` - -Should the time be announced: - -.... -presentTime=True -.... - -Values: on=`+True+`, off=`+False+` - -Should the date be announced (just on date change): - -.... -presentDate=True -.... - -Values: on=`+True+`, off=`+False+` - -Announce after a given period of seconds: - -.... -delaySec=0 -.... - -Value: in Seconds, 0 = Deactivated - -Announce after fixed minutes in an hour. if delaySec is >0 onMinutes is -ignored: - -.... -onMinutes=00,30 -.... - -Example every 15 minutes: - -.... -onMinutes=00,15,30,45 -.... - -Just play a soundicon, (not interrupting): - -.... -announce=True -.... - -Values: on=`+True+`, off=`+False+` - -Interrupt current speech for time announcement: - -.... -interrupt=False -.... - -Values: on=`+True+`, off=`+False+` - -== Customization - -=== Scripting - -Scripts can be in any language, bash, python, sh or others. Place your -personal scripts in `+~/.local/stormux/fenrir/+`, or place system scripts in -the directory /usr/share/fenrirscreenreader/scripts/ (the path is configurable -in settings.conf). The script key is the -applications key. Usually this key can be found on the keyboard located -just left of the right most control key. When you name a script, the key -name appears in the script seperated by the sequence [.underline]#-#. -So, for example, if you have a python weather script you want assigned -to the script key plus the letter w you would name the script -~/.local/stormux/fenrir/weather[.underline]##-##key_w.py -Then, to access the script, simply press the script key and the letter -w. Scripts must be executable. So, make sure to chmod 755 your script -when you place it in the scripts directory. The script gets some -parameters from fenrir when it is executed. So that information is -available in your script then. - -==== Parameterlist - -[cols=",",options="header",] +echo "setting set reading#mode=highlight" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock +---- + +Remote requests use `section++#++setting=value` syntax independently of +TOML. Remote speech rate, pitch, and volume use *0.0 to 1.0*, mapped to +the -100 to 100 scale used in settings files and menus. For example, +`speech++#++rate=0.8` selects rate 60. + +Other supported operations include: + +* `command tempdisablespeech`: temporarily silence speech. +* `command clipboard TEXT`: add text to the clipboard. +* `command exportclipboard`: export the selected clipboard. +* `command window X1 Y1 X2 Y2`: set a reading window, using zero-based, +inclusive coordinates. +* `command resetwindow`: clear the window. +* `setting save`: save settings. +* `setting reset`: clear quick and remote overrides back to the last +loaded or successfully saved settings. +* `command quitapplication`: quit Fenrir. + +Set `remote.enabled = false` to disable the service. Command and setting +requests have separate switches, `enable++_++command++_++remote` and +`enable++_++settings++_++remote`. Requests are authorized against the +caller’s account; console self-voicing also allows an account logged +into the active console. + +=== Command-line options + +Fenrir runs as `fenrir ++[++options++]++`. Use `--help` for the built-in +reference. + +[width="100%",cols="50%,50%",options="header",] |=== -|Parameter |Content -|$1 |Username of the current logged in user +|Option |Purpose +|`--help` |Show usage and options + +|`--version` |Print version and release channel + +|`-x` |Start a shell inside this X11 terminal + +|`--config PATH` |Load a specific TOML settings file + +|`--keyboard-layout NAME++_++OR++_++PATH` |Select a named layout or TOML +file + +|`--punctuation-profile NAME++_++OR++_++PATH` |Select a punctuation +profile + +|`--check-config` |Validate settings, layout, and punctuation without +opening devices + +|`--write-config PATH` |Write effective settings to a file and exit + +|`--speech-driver ID` |Override the configured speech driver + +|`--speech-rate NUMBER` |Override rate, from -100 to 100 + +|`--speech-module NAME` |Select a Speech Dispatcher module + +|`--input-device PATH` |Select a console keyboard event device; may be +repeated + +|`--debug-file PATH` |Append timing and reader-decision diagnostics |=== -==== Examples +=== Troubleshooting -Script that just speaks the current username when pressing ScriptKey + -H. + -File: `+/usr/share/fenrirscreenreader/scripts/helloWorld__-__key_h.sh+`: +==== Speech or sound is missing -.... -#!/bin/bash -echo $1 -.... +Check that speech and sound are enabled, and that the selected backend +is available. Speech Dispatcher needs a configured synthesizer. Pulse +output needs access to a running PulseAudio service, including +PipeWire’s PulseAudio service; ALSA needs access to its selected PCM +device. Root console sessions may need separate audio configuration; see +the README’s setup section. -=== Commands +For hardware speech, check the driver, device path, device permissions, +and serial baud rate. Use *Test synthesizer* before saving a new +hardware selection. -You can place your own commands in -"/usr/share/fenrirscreenreader/commands" (path is configurable in -settings.conf). Commands are python files with a special scheme. You can -assign them to a shortcut using the filename without an extension or -place them in a hook trigger like OnInput or OnScreenChange. For further -information see developer guide. Good Examples: -https://git.stormux.org/storm/fenrir/src/branch/master/src/fenrirscreenreader/commands/commands/date.py["date.py"] -(announce the Date), -https://git.stormux.org/storm/fenrir/src/branch/master/src/fenrirscreenreader/commands/commands/shut_up.py["shut_up.py"] -(interrupt output) the basic scheme for a command is as follows: +==== Keyboard input or X11 mode fails -.... -from core import debug -.... +In console mode, check access to keyboard event devices and +`/dev/uinput`. In X11 mode, check `DISPLAY`, `WINDOWID`, and competing +grabs on the terminal. Use NumLock off for bare keypad review. A +configured `keyboard.devices` list or `--input-device` applies to +console mode and cannot be used with `-x`. -.... -class command(): - def __init__(self): - pass - def initialize(self, environment): - self.env = environment - def shutdown(self): - pass - def getDescription(self): - return _('No description found') - def run(self): - pass - def setCallback(self, callback): - pass -.... +==== Check configuration and collect diagnostics -* https://git.stormux.org/storm/fenrir/src/branch/master/src/fenrirscreenreader/commands/command_template.py[Template -lives here] -* The class needs to have the name "command". -* "initialize" is running once whilst loading the command. -* "shutdown" is running on unload like the command (quit fenrir) -* "getDescriptsion" just returns an string. That String is used in -Tutorial Mode. -* "run" is executed when the command is invoked. (shortcut is pressed, -or trigger isn't running) -* setCAllback is currently not used. and has no functionality yet. +Validate an edited settings file with `--config PATH --check-config`. +For reader diagnostics, add `--debug-file /tmp/fenrir-debug.log` to the +launch command. This appends timing and reader decisions without screen +text or key values. `./fenrir --version` identifies the build when +reporting a problem. -== Troubleshooting +=== Documentation maintenance and support -Below are fenric instructions that do not all apply to Slint. +`docs/user.md` is the shared manual source. With Pandoc installed, run +`./docs/create++_++manpage.sh` to regenerate `docs/user.txt`, +`docs/fenrir.adoc`, and `docs/fenrir.1`. The script can run from any +working directory. -Slint users may request help on the Slint mailing list. +Please review documentation and test instructions for the affected +workflow before submitting a change, as described in the README’s +contribution policy. -=== Fenrir does not start - -. Have you installed all the dependencies -link:#Support and Requirements[Support and Requirements] -. Try using master, a lot of changes take place there to make Fenrir -compatible with more systems - -=== Fenrir does not utilize the shortcuts - -. Make sure you have python3-evdev installed -. Use the latest Fenrir version -. Make sure that Fenrir has permission to /dev/input/* and /dev/uinput -(or run it as root) - -=== No sound at all - -. Run the script to configure Pulseaudio once as root and once as your -user. This will setup Pulseaudio but require a restart of Pulseaudio. -The script is located in `+tools/configure_pulse.sh+` -. Use ALSA -. https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SystemWide/[Configure -Pulse system wide] (Not recommended) -. Use gstreamerDriver: change `+settings.conf+` in the section `+sound+` -the line `+driver=genericDriver+` to `+driver=gstreamerDriver+` -. Use wave sound-icons: change `+settings.conf+` in the section -`+sound+` the line `+theme=default+` to `+theme=default-wav+` -. Use most current version of http://sox.sourceforge.net/[sox] with opus -support -. Try https://github.com/i-rinat/apulse[apulse] (not tested by myself -but might work). Please give me feedback if you try it out. - -=== You get sound-icons but no speech - -. If you are using speech-dispatcher run "spd-conf" once as user and as -root. -. You can test if speech-dispatcher works by invoking it as root + -`+sudo spd-say "hello world"+` - -=== Bugreports and feature requests - -Please report Bugs and feature requests to: -https://git.stormux.org/storm/fenrir/issues - -for bugs please provide a link:#Howto create a debug file[debug] file -that shows the issue. - -==== How-to create a debug file - -. Start fenrir in debug mode + -`+sudo fenrir -d+` -. Do your stuff to reproduce the problem -. Stop fenrir (`+fenrirKey + q+`) - -the debug file is located in `+/tmp/fenrir.log+`. If another Fenrir debug -instance is already using it, check `+/tmp/fenrir2.log+`, -`+/tmp/fenrir3.log+`, etc. - -Please be as precise as possible to make it easy to solve the problem. +* https://git.stormux.org/storm/fenrir[Project repository and issue +tracker] +* https://git.stormux.org/storm/fenrir/wiki[Fenrir Wiki] +* Email list: `stormux{plus}subscribe@groups.io`, with the subject +`subscribe`. +* IRC: `irc.stormux.org`, channel `++#++stormux`. diff --git a/docs/user.md b/docs/user.md index a5534b6e..3ee33057 100644 --- a/docs/user.md +++ b/docs/user.md @@ -1,455 +1,381 @@ # Fenrir User Manual -Fenrir is a modern command line screen reader written in Python 3. - -It has a modular structure, a flexible driver-based architecture, is highly configurable and easy to customize and extend. +Fenrir is a Linux console screen reader written in Go. It reads Linux text +consoles and can run in an X11 terminal as a regular user. **Current maintainer:** Storm Dragon -**Previous developer:** Chrys +**Original creator:** Chrys (see [CREDITS](../CREDITS)) -## Quick Start +For build requirements and setup, see the [README](../README.md). -1. **Installation**: See the [README.md](../README.md) for installation instructions -2. **First run**: `sudo fenrir` (or `sudo systemctl start fenrir` if installed) -3. **Tutorial mode**: Press `Fenrir + H` to learn all commands interactively -4. **Basic navigation**: Use numeric keypad for review (desktop layout) -5. **Stop speech**: Press `Ctrl` at any time -6. **Quit**: Press `Fenrir + Q` +## Starting and stopping -## Key Concepts +Run these commands from the checkout root after building `fenrir`: + +```bash +# Linux text console, with console and keyboard device access +sudo ./fenrir + +# X11 terminal, as your regular user +./fenrir -x + +# Either mode can select the laptop layout +./fenrir -x --keyboard-layout laptop +``` + +Fenrir runs in the foreground. Press **Fenrir+Q** to quit. Run only one reader +on a given Linux console. Separate X11 terminal instances can run at once. + +X11 mode starts a shell in a new PTY. The launching terminal must supply valid +`DISPLAY` and `WINDOWID` environment variables. Keyboard interception is scoped +to that terminal window; a desktop screen reader can handle other windows. + +Console mode needs access to console devices, keyboard event devices, and +`/dev/uinput`. It releases keyboard input on graphical virtual terminals and +on text consoles selected in `screen.ignored_vts`. + +## Keyboard layouts and help + +The **Fenrir key** is Insert, Super/Windows, or keypad 0 with NumLock off. +Hold it while pressing the other keys in a shortcut. Bare keypad review keys +also require NumLock off. + +The desktop layout uses the numeric keypad. The laptop layout uses Fenrir +chords on the main keyboard. Select a layout with `--keyboard-layout desktop` +or `--keyboard-layout laptop`, or set `keyboard.layout` in the settings file. + +Press **Fenrir+H** or **Fenrir+F1** to enter the tutorial. Command shortcuts are +announced and described instead of executed. Up and Down browse commands; +Left and Right switch between active actions, unbound actions, and scripts. +Space repeats the current item. Escape or Fenrir+F1 exits. + +The complete layouts are [desktop.toml](../config/keyboard/desktop.toml) and +[laptop.toml](../config/keyboard/laptop.toml). + +## Screen review + +Review moves Fenrir's reading position without moving the application's cursor. +Return to the application cursor with the Follow cursor shortcut. By default, +application cursor movement or a screen change also leaves review. + +| Action | Desktop | Laptop | +| --- | --- | --- | +| Previous / current / next line | Keypad 7 / 8 / 9 | Fenrir+U / I / O | +| Previous / current / next word | Keypad 4 / 5 / 6 | Fenrir+J / K / L | +| Previous / current / next character | Keypad 1 / 2 / 3 | Fenrir+M / Comma / Period | +| Top / bottom of screen | Fenrir+Keypad 7 / 9 | Fenrir+Shift+U / O | +| Line start / end | Fenrir+Keypad 4 / 6 | Fenrir+Shift+J / L | +| First / last text on line | Fenrir+Keypad 1 / 3 | Fenrir+Control+J / L | +| Read screen | Fenrir+Keypad 5 | Fenrir+Shift+K | +| Screen before / after cursor | Fenrir+Keypad 8 / 2 | Fenrir+Shift+I / Comma | +| Character above / below | Fenrir+Control+Keypad 8 / 2 | Fenrir+Control+I / Comma | +| Follow cursor | Fenrir+Keypad Period | Fenrir+Slash | +| Review position | Keypad Period | Fenrir+Shift+Period | + +Press the current-line or current-word shortcut twice quickly to spell the +text, or three times for phonetic reading. Press the current-character shortcut +twice for its phonetic name. The default interval between presses is 200 ms; +`keyboard.multi_press_timeout_ms` changes it at launch. + +## Tracking modes + +Cycle through **cursor**, **table**, and **highlight** with +**Fenrir+Keypad Asterisk** on desktop or **Fenrir+Y** on laptop. +The startup selection is `reading.mode`. + +- **Cursor**: follows application cursor movement. +- **Table**: treats delimited or space-aligned text as cells. +- **Highlight**: follows changes to highlighted text, such as menu selections. + +In table mode, word navigation moves between cells, line start/end moves to the +first/last cell, and first/last text moves to the first/last character in the +current cell. Place review on a header row and press **Fenrir+X** to use its +cells as column headers. Outside table mode, Fenrir+X places a text-selection +mark. + +## Speech and automatic reading + +- **Control** interrupts speech. +- **Fenrir+F4** toggles mute. +- **Keypad Enter** on desktop temporarily silences speech. Speech can return on + the next keypress or a newly recognized prompt or completion. +- **Fenrir+Keypad Enter** on desktop, or **Fenrir+Enter** on laptop, toggles + automatic reading of new text. +- **Fenrir+Backspace** passes the next key through to the application. + +Character echo, word echo, and cursor echo can be configured separately. +Punctuation levels are `none`, `some`, `most`, and `all`. Character review still +names punctuation. Capital indicators, emoticons, repeated-symbol summaries, +indentation feedback, and attribute feedback are configurable in Reading. + +**Fenrir+T** announces the time; press twice quickly for the date. +**Fenrir+Shift+V** announces the Fenrir version. + +## Fenrir Menu and quick settings + +Press **Fenrir+F** to open the Fenrir Menu. It contains settings tabs for +presentation, speech, sound, reading, keyboard, clipboard, and other options. +The form captures its navigation keys until it closes. + +- At the tab selector, use arrows to choose a tab. +- Tab and Shift+Tab move between controls and the tab selector. +- Space or Enter toggles a checkbox. +- Arrows change list selections and numeric values. +- Activate **OK** to save, or **Cancel** or Escape to discard the form's changes. + +Speech rate, pitch, and volume use a scale from -100 to 100. Sound volume is +between 0.0 and 1.0. Backend, device, keyboard layout, sound theme, and other +launch-only settings take effect on the next start. + +Quick settings work without opening the form: + +| Shortcut | Action | +| --- | --- | +| Fenrir+Space | Announce current setting | +| Fenrir+Left / Right | Previous / next setting | +| Fenrir+Control+Left / Right | Previous / next category | +| Fenrir+Up / Down | Change value | +| Fenrir+Control+S | Save settings | + +Quick changes apply to the current session. Save to retain them for future +launches. Session controls such as mute and temporary silence are separate +from saved startup preferences. + +## Clipboard + +Use review navigation to place two marks around text with **Fenrir+X**, then +press **Fenrir+C** to copy it. In table mode Fenrir+X sets headers instead. + +| Shortcut | Action | +| --- | --- | +| Fenrir+Shift+X | Read marked text | +| Fenrir+Control+Shift+X | Remove marks | +| Fenrir+C | Copy marked text | +| Fenrir+Control+C | Copy last presented text | +| Fenrir+Shift+C | Read selected clipboard | +| Fenrir+Control+Shift+C | Clear selected clipboard | +| Fenrir+Home / End | First / last clipboard | +| Fenrir+PageUp / PageDown | Previous / next clipboard | +| Fenrir+V | Paste selected clipboard | +| Fenrir+F5 / F6 | Import from / export to file | +| Fenrir+F7 / F8 | Import from / export to X clipboard | + +`clipboard.number_of_clipboards` limits history; the default is 200. +`clipboard.export_path` selects the import/export file, initially +`/tmp/fenrirClipboard`. `clipboard.sync` enables automatic X clipboard +synchronization, which requires `xclip` and access to the X display. + +Persistent history is optional and off by default. Set `clipboard.persistent` +to retain unencrypted history across launches. Terminal sessions use +`~/.local/state/fenrir/clipboard/terminal.json`; console sessions use +`/var/lib/fenrir/clipboard/tty.json`. Same-user readers of the same mode share +persistent history. + +## Spell checking and emoji + +Automatic spell checking uses Enchant 2 and a dictionary matching the session +language. Reading settings control word repetition, spoken misspelling feedback, +and misspelling sounds. + +Press **Fenrir+S** to open the Spellcheck Menu for the current word. The +Suggestions tab lets you edit the word and choose a suggested spelling. +The Exceptions tab lets you add words, remove selected entries with Delete, +and undo a removal. Selecting a suggestion copies it to Fenrir's clipboard; +paste it with Fenrir+V. + +Press **Fenrir+Control+E** to open the Emoji Menu. Choose a category at the tab +selector, then Tab to the emoji grid. Arrows navigate, typing filters by name +prefix, and Control+Backspace clears the filter. Enter copies the selected +emoji to Fenrir's clipboard. Escape closes the menu. + +## Reading windows and live regions + +Reading regions belong to the current terminal and last for the reader session. +A reading window restricts automatic reading to a rectangle. Live regions +exclude changing areas from automatic speech while allowing explicit reading +and progress monitoring. + +Outside table mode, place two marks with **Fenrir+X** to define opposite corners. +Press **Fenrir+Keypad Slash** on desktop or **Fenrir+Control+8** on laptop to set a +reading window. Press the shortcut twice quickly to clear it. + +To create a live region, place one mark for the rest of that line, or two marks +for a rectangle, then press **Fenrir+B**. Fenrir assigns the first free slot, +up to ten. Region creation clears the marks. + +- **Fenrir+1** through **Fenrir+0** read live regions 1 through 10. +- **Fenrir+Shift+1** through **Fenrir+Shift+0** clear individual live regions. +- **Fenrir+Shift+B** lists the current reading regions. +- **Fenrir+Control+B** clears all live regions. +- **Fenrir+Control+Shift+B** clears both the reading window and live regions. + +## Sound and progress + +Sound output uses `pulse` for PulseAudio or PipeWire's PulseAudio service, or +`alsa` for an ALSA PCM device. Select the driver and theme in Sound settings. +The ALSA device name is set with `presentation.sound.device` in the file. + +Personal themes are searched under `~/.local/stormux/fenrir/sounds/` before +bundled and system themes. A theme contains WAV files and `soundicons.toml`. + +Progress tones are controlled separately from speech and automatic reading. +Press **Keypad Plus** on desktop or **Fenrir+Shift+P** on laptop to toggle them. +Fenrir recognizes percentages, fractions, progress bars, and activity indicators; +tones rise with progress. Startup behavior is set by +`presentation.progress.enabled`. + +## Configuration files + +Settings are TOML. The annotated +[settings.toml](../config/settings/settings.toml) lists all available options. +Fenrir loads one settings file rather than merging files. + +- Regular users: first + `~/.local/share/stormux/fenrirscreenreader/settings/settings.toml`, then + `/etc/fenrirscreenreader/settings/settings.toml`. +- Root: `/etc/fenrirscreenreader/settings/settings.toml`. +- `--config PATH`: use that file explicitly. + +If default files are absent, Fenrir uses built-in defaults. An explicitly +selected file must exist. Saving targets the selected file; if startup used +built-in defaults, saving creates the first default path for that account. + +Create a personal settings file and validate it without opening devices: + +```bash +./fenrir --write-config ~/.local/share/stormux/fenrirscreenreader/settings/settings.toml +./fenrir --config ~/.local/share/stormux/fenrirscreenreader/settings/settings.toml --check-config +``` + +Named keyboard layouts are searched in the regular user's +`~/.local/share/stormux/fenrirscreenreader/keyboard/`, then +`/etc/fenrirscreenreader/keyboard/`, then `config/keyboard/` beside the binary. +Root searches the system and bundled locations. An explicit TOML path selects +one file. Custom layouts replace the complete layout; they are not overlays. +See the [keyboard guide](../config/keyboard/Readme.md) for an example. + +## Speech synthesizers + +The default driver is `speech-dispatcher`. Select its module, language, and +voice in Speech settings; empty values use server defaults. + +Hardware driver IDs are `dectalk`, `dectalk-usb`, `litetalk`, `doubletalk`, and +`tripletalk`. Serial drivers require `presentation.speech.hardware_device`, +for example `/dev/ttyUSB0`, and default to 9600 baud when +`hardware_baud_rate = 0`. DoubleTalk support targets the external LT device. +TripleTalk USB devices need to expose a serial tty. + +Native `dectalk-usb` uses libusb 1.0 and ignores serial settings. The process +needs access to the device. The Speech form's **Test synthesizer** button +previews hardware choices before saving. Driver and port changes apply at launch. + +## Script shortcuts + +Fenrir searches `~/.local/stormux/fenrir/`, the configured +`general.script_path` (default `/usr/share/fenrirscreenreader/scripts`), and the +bundled `config/scripts/` beside the binary. Earlier directories take priority. + +A filename such as `example__-__key_y.sh` assigns the script key plus Y. +The script key defaults to Compose and is configured by `general.script_keys`. +Scripts must be executable to run. Fenrir invokes them directly and passes the +current account name as the first argument. Commands appear in the tutorial's +script list. + +## Remote control + +Unix socket remote control is enabled by default. The standard socket is +`/tmp/fenrirscreenreader-daemon.sock`, and instances also have private sockets +`/tmp/fenrirscreenreader-.sock`. Set `remote.socket_file` for a custom socket. + +Use `ls` to discover instances. Use a private socket to address one reader: -### Fenrir Key -The Fenrir Key is used to invoke screen reader commands. By default: -- Insert -- Keypad Insert -- Meta (Super/Windows key) - -You can configure multiple Fenrir keys to suit your preference. - -### Keyboard Layouts -- **Desktop Layout**: Uses numeric keypad (recommended for desktop users) -- **Laptop Layout**: Alternative bindings for keyboards without numeric keypad - -### Review Mode -Navigate the screen without moving the text cursor. Essential for examining content without disrupting your workflow. - -## Essential Commands - -### Navigation (Desktop Layout) -- `Ctrl` - Stop speech (shut up) -- `Fenrir + H` - Tutorial mode -- `Fenrir + Ctrl + H` - Speech history -- `Fenrir + Q` - Quit Fenrir -- `Fenrir + Keypad 5` - Read current screen -- `Keypad 8` - Read current line -- `Keypad 5` - Read current word -- `Keypad 2` - Read current character - -### Review Commands -- `Keypad 7/9` - Previous/next line -- `Keypad 4/6` - Previous/next word -- `Keypad 1/3` - Previous/next character -- `Fenrir + Keypad dot` - Exit review mode - -### Table Navigation -- `Fenrir + Keypad *` - Toggle table mode / highlight tracking -- `Keypad 4/6` - Previous/next column (in table mode) -- `Fenrir + Keypad 4/6` - First/last column (in table mode) -- `Fenrir + X` - Set column headers (in table mode) - -### Information -- `Fenrir + T` - Announce time -- `Fenrir + T T` - Announce date -- `Keypad dot` - Cursor position - -### Clipboard -- `Fenrir + X` - Set mark -- `Fenrir + C` - Copy marked text -- `Fenrir + V` - Paste clipboard -- `Fenrir + Shift + C` - Read current clipboard - -### Settings (Runtime Changes) -- `Fenrir + F3` - Toggle sound -- `Fenrir + F4` - Toggle speech -- `Fenrir + Up/Down` - Speech volume -- `Fenrir + Right/Left` - Speech rate -- `Fenrir + Ctrl + P` - Punctuation level - -## Configuration - -### Settings File -Main configuration: -- **System-wide**: `/etc/fenrirscreenreader/settings/settings.conf` -- **User-local**: `~/.local/share/stormux/fenrirscreenreader/settings/settings.conf` - -When Fenrir runs as a regular user, including `fenrir -x`, it loads the user-local settings file if it exists. If it does not exist, Fenrir falls back to the system settings file, but saving settings creates or updates the user-local file. When Fenrir runs as root, settings save to the system-wide file by default. - -User sound themes are loaded before system themes from `~/.local/stormux/fenrir/sounds/`. User scripts are loaded before configured system scripts from `~/.local/stormux/fenrir/`. - -### Key Sections -- `[speech]` - Speech synthesis settings -- `[sound]` - Sound output and icons -- `[keyboard]` - Input and key bindings -- `[screen]` - Screen reading configuration -- `[general]` - General settings - -### Common Settings -```ini -[speech] -enabled=True -driver=speechdDriver -rate=0.5 -pitch=0.5 -volume=1.0 -hardware_device=/dev/ttyS0 -hardware_baud_rate=9600 -history_size=50 - -[sound] -enabled=True -driver=genericDriver -volume=0.7 - -[keyboard] -driver=evdevDriver -keyboard_layout=desktop - -[screen] -driver=vcsaDriver -ignore_screen= - -[remote] -enable=True -driver=unixDriver -enable_settings_remote=True -enable_command_remote=True -``` - -## Remote Control - -Fenrir includes a powerful remote control system for automation and integration with external applications. - -### Configuration -Enable remote control in settings: -```ini -[remote] -enable=True -driver=unixDriver # or tcpDriver -port=22447 # for TCP driver -enable_settings_remote=True # allow settings changes -enable_command_remote=True # allow command execution -``` - -### Basic Usage with socat - -#### Instance Discovery ```bash -# List registered Fenrir instances and their socket paths echo "ls" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -``` - -In X terminal mode (`fenrir -x`), multiple Fenrir instances can run at the same -time. Each instance has a private socket at `/tmp/fenrirscreenreader-.sock`, -and one instance may also own the standard control socket. Use `ls` or -`command ls` on the standard socket to find the private socket for a specific -instance. Commands sent to the standard socket are handled by its owner when -possible; otherwise they are forwarded to a registered private socket, -preferring the sender's Fenrir ancestor when one can be found. - -#### Speech Control -```bash -# Interrupt current speech +echo "command say Hello" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock echo "command interrupt" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Speak custom text -echo "command say Hello, this is a test" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Temporarily disable speech -echo "command tempdisablespeech" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock +echo "setting set reading#mode=highlight" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock ``` -#### Settings Control -```bash -# Enable highlight tracking -echo "setting set focus#highlight=True" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock +Remote requests use `section#setting=value` syntax independently of TOML. +Remote speech rate, pitch, and volume use **0.0 to 1.0**, mapped to the +-100 to 100 scale used in settings files and menus. For example, +`speech#rate=0.8` selects rate 60. -# Change speech parameters -echo "setting set speech#rate=0.8" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -echo "setting set speech#pitch=0.6" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -echo "setting set speech#volume=0.9" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock +Other supported operations include: -# Change punctuation level (none/some/most/all) -echo "setting set general#punctuation_level=all" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock +- `command tempdisablespeech`: temporarily silence speech. +- `command clipboard TEXT`: add text to the clipboard. +- `command exportclipboard`: export the selected clipboard. +- `command window X1 Y1 X2 Y2`: set a reading window, using zero-based, + inclusive coordinates. +- `command resetwindow`: clear the window. +- `setting save`: save settings. +- `setting reset`: clear quick and remote overrides back to the last loaded or + successfully saved settings. +- `command quitapplication`: quit Fenrir. -# Voice and TTS control -echo "setting set speech#voice=en-us+f3" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -echo "setting set speech#module=espeak-ng" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock +Set `remote.enabled = false` to disable the service. Command and setting +requests have separate switches, `enable_command_remote` and +`enable_settings_remote`. Requests are authorized against the caller's account; +console self-voicing also allows an account logged into the active console. -# Multiple settings at once -echo "setting set speech#rate=0.8;sound#volume=0.7;general#punctuation_level=most" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock +## Command-line options -# Reset all settings -echo "setting reset" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock +Fenrir runs as `fenrir [options]`. Use `--help` for the built-in reference. -# Save settings -echo "setting save" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -echo "setting saveas /tmp/my-settings.conf" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -``` - -#### Clipboard Operations -```bash -# Add text to clipboard -echo "command clipboard Text to copy" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock - -# Export clipboard to file -echo "command exportclipboard" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -``` - -#### Application Control -```bash -# Quit Fenrir -echo "command quitapplication" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -``` - -### Command Reference - -**Speech Commands:** -- `command say ` - Speak text -- `command interrupt` - Stop speech -- `command tempdisablespeech` - Disable until next key -- `ls` / `list` / `command ls` / `command list` - List registered Fenrir instances - -**Settings Commands:** -- `setting set
#=` - Change setting -- `setting reset` - Reset to defaults -- `setting save` - Save current settings - -**Other Commands:** -- `command clipboard ` - Add to clipboard -- `command exportclipboard` - Export clipboard to file -- `command window ` - Define window -- `command resetwindow` - Reset window -- `command vmenu ` - Set virtual menu -- `command resetvmenu` - Reset virtual menu - -**Key Settings You Can Change:** -- Punctuation level: `setting set general#punctuation_level=all` -- Speech parameters: `setting set speech#rate=0.8;speech#pitch=0.6` -- Voice selection: `setting set speech#voice=en-us+f3` -- Character echo: `setting set keyboard#char_echo_mode=1` -- Screen ignore: `setting set screen#ignore_screen=1,2,3` - -### Scripting Integration - -#### Bash Helper Function -```bash -fenrir_say() { - echo "command say $1" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock -} - -# Usage -fenrir_say "Build completed" -``` - -#### Python Integration -```python -import socket -import os - -def send_fenrir_command(command): - socket_path = "/tmp/fenrirscreenreader-daemon.sock" - if os.path.exists(socket_path): - sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) - try: - sock.connect(socket_path) - sock.send(command.encode('utf-8')) - finally: - sock.close() - -send_fenrir_command("command say Process complete") -``` - -## Advanced Features - -### Table Navigation Mode - -Fenrir includes advanced table navigation capabilities for working with tabular data in terminal applications, CSV files, and formatted text output. - -#### Entering Table Mode -1. Press `Fenrir + Keypad *` (desktop) or `Fenrir + Y` (laptop) -2. Cycle through: Highlight tracking → Cursor tracking → Table mode -3. Listen for "table mode enabled" announcement - -#### Table Navigation Commands -- **Column navigation**: `Keypad 4/6` - Move between columns -- **Row boundaries**: `Fenrir + Keypad 4/6` - Jump to first/last column -- **Cell characters**: `Fenrir + Keypad 1/3` - First/last character in cell -- **Set headers**: `Fenrir + X` - Mark current line as column headers - -#### Table Features -- **Automatic detection**: Supports CSV, pipe-separated, space-aligned columns -- **Column headers**: Set and announce headers for better context -- **Boundary feedback**: Audio cues when reaching row boundaries -- **Cell-by-cell navigation**: Precise positioning within tables - -### Progress Bar Monitoring - -Fenrir automatically detects and provides audio feedback for progress indicators. - -#### Progress Detection -- **Percentage**: 45%, 67.5%, 100% -- **Fractions**: 15/100, 3 of 10, Step 7/15 -- **Progress bars**: [#### ], [====> ] -- **Activity indicators**: Loading..., Processing... - -#### Audio Feedback -- **Progress tones**: Ascending 400Hz-1200Hz frequency range -- **Activity beeps**: 800Hz tone every 2 seconds -- **Non-intrusive**: Doesn't interrupt speech or other audio - -#### Usage -- **Enable**: Use `progress_bar_monitor` command (assign key binding) -- **Automatic**: Works with downloads, compilations, installations -- **Remote control**: Enable via socket commands - -Fenrir detects stable progress structures rather than application-specific -status formats, which change too frequently to support reliably. - -### Spell Checking -- `Fenrir + S` - Spell check current word -- `Fenrir + S S` - Add word to dictionary -- `Fenrir + Shift + S` - Remove word from dictionary - -### Bookmarks (1-10) -- `Fenrir + Shift + [1-0]` - Set bookmark -- `Fenrir + [1-0]` - Go to bookmark -- `Fenrir + Ctrl + [1-0]` - Clear bookmark - -### Multiple Clipboards -- `Fenrir + Home/End` - First/last clipboard -- `Fenrir + PageUp/PageDown` - Previous/next clipboard - -### Window Mode -1. Set marks to define window area -2. `Fenrir + Keypad /` - Set window -3. `Fenrir + Keypad / /` - Clear window - -## Drivers - -### Speech Drivers -- **speechdDriver** - Speech-dispatcher (recommended) -- **genericDriver** - Command-line TTS (espeak, etc.) -- **dectalkDriver** - Serial DECtalk-compatible hardware speech -- **dectalkUsbDriver** - Native Access Solutions DECtalk USB (`0dd0:2001`) -- **litetalkDriver** - Serial LiteTalk-compatible hardware speech -- **doubletalkDriver** - Serial DoubleTalk LT-compatible hardware speech -- **tripletalkDriver** - Serial TripleTalk-compatible hardware speech - -For serial hardware speech, set `speech#hardware_device` to an explicit path. -RPITalk gadget mode usually appears as `/dev/ttyACM0`; USB serial adapters -usually appear as `/dev/ttyUSB0`; built-in serial ports may be `/dev/ttyS0`. -The default baud rate is `9600`. `doubletalkDriver` targets -DoubleTalk LT-style serial devices, not the internal DoubleTalk PC ISA card. -The `dectalkUsbDriver` autodetects the native Access Solutions DECtalk USB and -ignores both serial settings. It requires PyUSB and a libusb backend. From a -source checkout, install them with -`python3 -m pip install '.[dectalk_usb]'`. A non-root Fenrir process also needs -a local udev rule granting its account read/write access to USB ID -`0dd0:2001`; do not make the device world-writable. USB TripleTalk devices work -only if Linux exposes them as a serial tty such as `/dev/ttyACM0` or -`/dev/ttyUSB0`. - -### Sound Drivers -- **genericDriver** - Sox-based (default) -- **gstreamerDriver** - GStreamer-based - -### Input Drivers -- **evdevDriver** - Linux evdev (recommended for Linux) -- **x11Driver** - X11 terminal-scoped input for `fenrir -x` - -### Screen Drivers -- **vcsaDriver** - Linux VCSA devices (TTY) -- **ptyDriver** - Terminal emulation - -### Remote Drivers -- **unixDriver** - Unix socket remote control (recommended) -- **tcpDriver** - TCP socket remote control (localhost only) - -## Command Line Options - -``` -fenrir [OPTIONS] -``` - -- `-h, --help` - Show help -- `-v, --version` - Show version -- `-f, --foreground` - Run in foreground -- `-s, --setting FILE` - Custom settings file -- `-o, --options SECTION#SETTING=VALUE;..` - Override settings -- `-d, --debug` - Enable debug mode -- `-p, --print` - Print debug to screen -- `-x, --x11` - PTY + X11 keyboard input scoped to the terminal window -- `--x11-window-id WINDOWID` - X11 window id to use for `--x11` terminal mode -- `-F, --force-all-screens` - Ignore ignore_screen setting -- `-i, -I, --ignore-screen SCREEN` - Ignore specific screen(s), can be used multiple times - -### X11 Terminal Mode - -Use `fenrir -x` to run Fenrir in an X11 terminal as a normal user: - -```bash -fenrir -x -``` - -This mode uses PTY screen monitoring and X11 keyboard input. It is intended for GUI terminals such as xterm and VTE-based terminals, while keeping Fenrir key handling scoped to that terminal window. Desktop screen readers keep their global bindings outside the focused terminal. - -Fenrir normally detects the target terminal from `WINDOWID` or the active X11 window. If needed, pass a window id explicitly: - -```bash -fenrir -x --x11-window-id 0x123456 -``` - -X11 terminal mode uses the same keyboard layout files as TTY Fenrir. Supported Fenrir keys include numpad Insert/`KEY_KP0`, CapsLock/`KEY_CAPSLOCK`, Insert/`KEY_INSERT`, and Super/Windows/`KEY_META`. Compose script keys are exposed as `KEY_COMPOSE`. - -In this mode Fenrir runs as a regular user. Settings are loaded from `~/.local/share/stormux/fenrirscreenreader/settings/settings.conf` when present, otherwise from `/etc/fenrirscreenreader/settings/settings.conf`; saving settings creates or updates the user-local file. User sound themes and scripts are read first from `~/.local/stormux/fenrir/sounds/` and `~/.local/stormux/fenrir/`. - -This mode requires `python-xlib`. - -For a dedicated PTY/terminal screen reader, see TDSR: https://github.com/tspivey/tdsr +| Option | Purpose | +| --- | --- | +| `--help` | Show usage and options | +| `--version` | Print version and release channel | +| `-x` | Start a shell inside this X11 terminal | +| `--config PATH` | Load a specific TOML settings file | +| `--keyboard-layout NAME_OR_PATH` | Select a named layout or TOML file | +| `--punctuation-profile NAME_OR_PATH` | Select a punctuation profile | +| `--check-config` | Validate settings, layout, and punctuation without opening devices | +| `--write-config PATH` | Write effective settings to a file and exit | +| `--speech-driver ID` | Override the configured speech driver | +| `--speech-rate NUMBER` | Override rate, from -100 to 100 | +| `--speech-module NAME` | Select a Speech Dispatcher module | +| `--input-device PATH` | Select a console keyboard event device; may be repeated | +| `--debug-file PATH` | Append timing and reader-decision diagnostics | ## Troubleshooting -### No Speech -1. Test speech-dispatcher: `sudo spd-say "hello"` -2. Check driver setting in configuration -3. Verify speech-dispatcher is running +### Speech or sound is missing -### No Sound -1. Run audio configuration script: `configure_pulse.sh` or `configure_pipewire.sh` -2. Check sound driver setting -3. Verify sox installation +Check that speech and sound are enabled, and that the selected backend is +available. Speech Dispatcher needs a configured synthesizer. Pulse output needs +access to a running PulseAudio service, including PipeWire's PulseAudio service; +ALSA needs access to its selected PCM device. Root console sessions may need +separate audio configuration; see the README's setup section. -### No Input Response -1. Check permissions: `/dev/input/*` and `/dev/uinput` -2. Verify evdev driver setting -3. Run as root for testing +For hardware speech, check the driver, device path, device permissions, and +serial baud rate. Use **Test synthesizer** before saving a new hardware selection. -### Debug Mode -```bash -sudo fenrir -f -d -# Debug output goes to /tmp/fenrir.log -``` +### Keyboard input or X11 mode fails -## Getting Help +In console mode, check access to keyboard event devices and `/dev/uinput`. +In X11 mode, check `DISPLAY`, `WINDOWID`, and competing grabs on the terminal. +Use NumLock off for bare keypad review. A configured `keyboard.devices` list +or `--input-device` applies to console mode and cannot be used with `-x`. -- **Tutorial Mode**: `Fenrir + H` (interactive help) -- **Wiki**: https://git.stormux.org/storm/fenrir/wiki -- **Email**: stormux+subscribe@groups.io -- **IRC**: irc.stormux.org #stormux +### Check configuration and collect diagnostics -## See Also +Validate an edited settings file with `--config PATH --check-config`. For +reader diagnostics, add `--debug-file /tmp/fenrir-debug.log` to the launch +command. This appends timing and reader decisions without screen text or key +values. `./fenrir --version` identifies the build when reporting a problem. -- [README.md](../README.md) - Installation and basic setup -- [diff_review_mode.md](./diff_review_mode.md) - Diff review workflow and key bindings -- [settings.conf](../config/settings/settings.conf) - Configuration reference -- `man fenrir` - Manual page +## Documentation maintenance and support + +`docs/user.md` is the shared manual source. With Pandoc installed, run +`./docs/create_manpage.sh` to regenerate `docs/user.txt`, `docs/fenrir.adoc`, and +`docs/fenrir.1`. The script can run from any working directory. + +Please review documentation and test instructions for the affected workflow +before submitting a change, as described in the README's contribution policy. + +- [Project repository and issue tracker](https://git.stormux.org/storm/fenrir) +- [Fenrir Wiki](https://git.stormux.org/storm/fenrir/wiki) +- Email list: `stormux+subscribe@groups.io`, with the subject `subscribe`. +- IRC: `irc.stormux.org`, channel `#stormux`. diff --git a/docs/user.txt b/docs/user.txt index d8c0c771..69c249d1 100644 --- a/docs/user.txt +++ b/docs/user.txt @@ -1,1329 +1,433 @@ -====== Fenrir User Manual ====== - -Fenrir is a modern command line screen reader written in Python3. - -It has a modular structure, a flexible based driver model, is highly configurable and easy to customize and extend ([[fenrir_development_manual|see Developer Manual]]). - -Please see the following pages for the [[fenrir_current_version|current]] and [[fenrir_git_version|Git]] version of Fenrir. - - -====== Support and Requirements ====== - -Fenrir requires several drivers to interact with the operating system. - -===== Speech Drivers ===== - -A speech driver is for communication with the text to speech system like [[#SpeechDispatcher|Speech-Dispatcher]] or [[http://espeak.sourceforge.net|Espeak]]. \\ -See section [[#Speech|Speech]] in ''settings.conf'' for more information. - - -==== SpeechDispatcher ==== - -This driver is used by default. -It uses Speech-dispatcher as its backend. - -Dependencies: - - * Speech-dispatcher (installed and configured, [[https://devel.freebsoft.org/speechd#sec2|Documentation]]) - * Python-speechd - -==== Espeak ==== - -Uses Espeak via Python bindings. - -Dependencies: - * Espeak or Espeak-ng - * [[https://launchpad.net/python-espeak|python-espeak]] - -==== Generic ==== - -This invokes speech via a sub-process. This is almost the same as using the commandline. The performance depends on the overhead of the speech synthesis application but it is really flexible. - -Dependencies: - * Espeak or Espeak-ng - -The Requirements are flexible, they depend on the configuration in settings.conf. - -==== Dummy ==== - -this is just for debugging, logs are output to the screen and logged as well. - -===== Sound Drivers ===== - -To play sound icons and similar.\\ -See section [[#Sound|Sound]] in ''settings.conf'' for more information. - -==== Generic ==== - -This driver is used by default. - -Dependencies: - - * [[http://sox.sourceforge.net/|Sox]] with opus support -The Requirements are flexible, they depend on the configuration in settings.conf. - -==== Gstreamer ==== - -if you prefer to use Gstreamer for sound output. - -Dependencies: - * Gstreamer >= 1.x - * Glibc - -==== Dummy ==== - -this is just for debugging, logs are output to the screen and logged as well. - -===== Input Drivers ===== - -Input drivers are to capture keyboard shortcuts issued to the screen reader \ -See section [[#Keyboard|Keyboard]] in ''settings.conf'' for more information. - -==== Evdev ==== - -This driver is used by default. - -Evdev is the low level input device framework for Linux. - -Dependencies: - - * python-evdev >=0.6.3 - * pyudev - * loaded uinput kernel module - * exclusive access to the input devices -Read permission to the following files and services: - * /dev/input - * /dev/uinput - -===== Screen Drivers ===== - -The job of a screen driver is to get the information of current screen content.\\ -See section [[#Screen|Screen]] in ''settings.conf'' for more information. - -==== VCSA ==== - -This driver is used by default. -For Linux VCSA devices. These exist on any current standard installation of Linux. - -Dependencie -s: - - * python-dbus -Read permission to the following files and services (or run as root): - * /sys/devices/virtual/tty/tty0/active - * /dev/tty[1 - 64] - * /dev/vcsa[1 - 64] ([[https://linux.die.net/man/4/vcsa|VCSA manpage]]) - * read Logind DBUS - -===== Braille Drivers ===== -This is for Braille support. -Braille is currently a work in progress and is planned for the Fenrir 2.0 release.\\ -See section [[#Braille|Braille]] in ''settings.conf'' for more information. - - -==== BRLTTY ==== - -This driver is used by default. -It uses [[brltty|BrlTTY]] to communicate with with a Braille device. - -Dependencies: - - * BrlTTY (configured and running, [[http://mielke.cc/brltty/doc/Manual-BRLTTY/English/BRLTTY.html|Documentation]]) - * python-brlapi (configured, [[http://mielke.cc/brltty/doc/Manual-BrlAPI/English/BrlAPI.html|Documentation]]) -===== Currently supported platforms ===== - -Currently Fenrir completely supports the following Platforms: - * Linux TTY -Support for further Systems are planned. - -====== Installation ====== - -Fenrir can run without installation. It just requires the dependencies are installed first. - -We recommend to try it out before installation to be sure everything works and prevent yourself from experiencing a non-talking environment. - -===== Try Out ===== -Fenrir does not require installation. You can try it and make sure everything works before you decide to install. In this way you can be sure that your system doesnt break or stop talking. -for that you can just grab the code and run as root ''src/fenrir/fenrir'' (in foreground) or ''src/fenrir/fenrir-daemon'' (in background, used by systemd for autostart) - -===== Install it ===== - -==== Documented operating systems ==== - -==== Arch Linux ==== - -For Arch there are PKGBUILDs in the AUR: - * [[https://aur.archlinux.org/packages/fenrir/|fenrir]] - * [[https://aur.archlinux.org/packages/fenrir-git/|fenrir-git]] - -==== Manual ==== - - - Download the latest stable version from the [[https://linux-a11y.org/index.php?page=fenrir-screenreader|Fenrir-Project]] site. - - Unpack the archive - - Check the needed Dependencys by running [[https://git.stormux.org/storm/fenrir/src/branch/master/check-dependencies.py|check-dependencys.py]] script - - install the missing dependencies an standard installation requires the following: - * python3 >= 3.3 (and all the following is needed for python3 ) - * python3-speechd (screen) - * python3-dbus (screen) - * python3-evdev >= 0.6.4(input) - * python3-daemonize (background service) - * python3-brlapi (braille) - * python3-pyenchant (spellchecker) - * your language for aspell (aspell-) (spellchecker) - * sox (sound) - * For an individual installation see [[#Support and Requirements|Support and Requirements]] or consult the [[https://git.stormux.org/storm/fenrir/src/branch/master/README.md|Readme]]) - - run "install.sh" as root - -this installs Fenrir as the following - * Application:''/opt/fenrir'' - * Settings:''/etc/fenrir'' - * Sound Icons:''/usr/share/fenrirscreenreader/'' - -to remove Fenrir just run uninstall.sh as root - -==== Git ==== - -if you want to get the latest code you can use git to get a development snapshot: - - git clone https://git.stormux.org/storm/fenrir.git - -===== Auto Start ===== - -To start Fenrir once: - systemctl start fenrir - -To enable auto start on system boot: - systemctl enable fenrir - -====== First Steps ====== - -If you are using Fenrir for the first time you may want to take a look at these resources: - * [[#Keybindings|Keybindings]] - * [[#Tutorial Mode|Tutorial Mode]] - -====== Features ====== - -===== Commands ===== - -==== Keybindings ==== - -Normal commands can be invoked in two ways: - - Using a Metakey ([[#Fenrir Key|FenrirKey]]) - - Shortcuts with a single key - -See section [[#Keyboard|Keyboard]] in ''settings.conf'' for more information. -=== Fenrir Key === -The Fenrir Key is for invoking screen reader commands. Fenrir can utilize more than one FenrirKey at the same time. -By default the following keys are used: - - Insert - - KeyPad Insert - - Meta (Super, Windows) - -=== Script Key === -To invoke "Scripts" the Script Key is mandatory. The shortcut is encoded in the filename of the script. See [[#Scripting|Scripting]] -=== Desktop Layout === -^Shortcut ^Command ^ -|FenrirKey + H|[[#Tutorial Mode|toggle tutorial mode]]| -|CTRL|[[#shut up|shut up (interrupts speech)]]| -|FenrirKey + KeyPad 9|[[#review bottom|reviews bottom]]| -|FenrirKey + KeyPad 7|[[#review top|reviews top]]| -|KeyPad 8|[[#review current line|reviews current line]]| -|KeyPad 7|[[#review previous line|reviews previous line]]| -|KeyPad 9|[[#review next line|reviews next line]]| -|FenrirKey + KeyPad 4|[[#review line beginning|reviews line beginning]]| -|FenrirKey + KeyPad 6|[[#review line ending|reviews line ending]]| -|FenrirKey + KeyPad 1|[[#review line first character|reviews line first character]]| -|FenrirKey + KeyPad 3|[[#review line last character|reviews line last character]]| -|FenrirKey + Alt + 1|[[#present first line|presents first line]]| -|FenrirKey + Alt + 2|[[#present last line|presents last line]]| -|KeyPad 5|[[#review current word|reviews current word]]| -|KeyPad 4|[[#review previous word|reviews previous word]]| -|KeyPad 6|[[#review next word|reviews next word]]| -|FenrirKey + Shift + KeyPad 5|[[#review current word phonetic|reviews current word phonetic]]| -|FenrirKey + Shift + KeyPad 4|[[#review previous word phonetic|reviews previous word phonetic]]| -|FenrirKey + Shift + KeyPad 6|[[#review next word phonetic|reviews next word phonetic]]| -|KeyPad 2|[[#review current character|reviews current char]]| -|KeyPad 1|[[#review previous character|reviews previous char]]| -|KeyPad 3|[[#review next character|reviews next char]]| -|FenrirKey + Shift + KeyPad 2|[[#review current character phonetic|reviews current character phonetic]]| -|FenrirKey + Shift + KeyPad 1|[[#review previous character phonetic|reviews previous character phonetic]]| -|FenrirKey + Shift + KeyPad 3|[[#review next character phonetic|reviews next character phonetic]]| -|FenrirKey + CTRL + KeyPad 8|[[#review up|reviews up]]| -|FenrirKey + CTRL + KeyPad 2|[[#review down|reviews down]]| -|FenrirKey + KeyPad dot|[[#exit review|exit review]]| -|KeyPad dot|[[#cursor position|cursor position]]| -|FenrirKey + I|[[#indent current line|indent curr line]]| -|FenrirKey + KeyPad 5|[[#current screen|current screen]]| -|FenrirKey + KeyPad 8|[[#current screen before cursor|current screen before cursor]]| -|FenrirKey + KeyPad 2|[[#current screen after cursor|current screen after cursor]]| -||[[#cursor read to end of line|cursor read to end of line]]| -||[[#cursor column|cursor column]]| -||[[#cursor line number|cursor line number]]| -||[[#braille flush|Braille flush]]| -||[[#braille pan left|Braille pan left]]| -||[[#braille pan right|Braille pan right]]| -||[[#braille return to cursor|Braille return to cursor]]| -|FenrirKey + CTRL + 1|[[#clear Bookmark X|clear bookmark 1]]| -|FenrirKey + Shift + 1|[[#set Bookmark X|set bookmark 1]]| -|FenrirKey + 1|[[#read Bookmark X|bookmark 1]]| -|FenrirKey + CTRL + 2|[[#clear Bookmark X|clear bookmark 2]]| -|FenrirKey + Shift + 2|[[#set Bookmark X|set bookmark 2]]| -|FenrirKey + 2|[[#read Bookmark X|bookmark 2]]| -|FenrirKey + CTRL + 3|[[#clear Bookmark X|clear bookmark 3]]| -|FenrirKey + Shift + 3|[[#set Bookmark X|set bookmark 3]]| -|FenrirKey + 3|[[#read Bookmark X|bookmark 3]]| -|FenrirKey + CTRL + 4|[[#clear Bookmark X|clear bookmark 4]]| -|FenrirKey + Shift + 4|[[#set Bookmark X|set bookmark 4]]| -|FenrirKey + 4|[[#read Bookmark X|bookmark 4]]| -|FenrirKey + CTRL + 5|[[#clear Bookmark X|clear bookmark 5]]| -|FenrirKey + Shift + 5|[[#set Bookmark X|set bookmark 5]]| -|FenrirKey + 5|[[#read Bookmark X|bookmark 5]]| -|FenrirKey + CTRL + 6|[[#clear Bookmark X|clear bookmark 6]]| -|FenrirKey + Shift + 6|[[#set Bookmark X|set bookmark 6]]| -|FenrirKey + 6|[[#read Bookmark X|bookmark 6]]| -|FenrirKey + CTRL + 7|[[#clear Bookmark X|clear bookmark 7]]| -|FenrirKey + Shift + 7|[[#set Bookmark X|set bookmark 7]]| -|FenrirKey + 7|[[#read Bookmark X|bookmark 7]]| -|FenrirKey + CTRL + 8|[[#clear Bookmark X|clear bookmark 8]]| -|FenrirKey + Shift + 8|[[#set Bookmark X|set bookmark 8]]| -|FenrirKey + 8|[[#read Bookmark X|bookmark 8]]| -|FenrirKey + CTRL + 9|[[#clear Bookmark X|clear bookmark 9]]| -|FenrirKey + Shift + 9|[[#set Bookmark X|set bookmark 9]]| -|FenrirKey + 9|[[#read Bookmark X|bookmark 9]]| -|FenrirKey + CTRL + 0|[[#clear Bookmark X|clear bookmark 10]]| -|FenrirKey + Shift + 0|[[#set Bookmark X|set bookmark 10]]| -|FenrirKey + 0|[[#read Bookmark X|bookmark 10]]| -|FenrirKey + KeyPad Slash|[[#Create Window|set window application]]| -|2 * FenrirKey + KeyPad Slash|[[#Remove Window|clear window application]]| -|KeyPad Plus|[[#last incoming|read last incoming]]| -|FenrirKey + F2|[[#toggle braille|toggles braille]]| -|FenrirKey + F3|[[#toggle sound|toggles sound]]| -|FenrirKey + F4|[[#toggle speech|toggles speech]]| -|KeyPad Enter|[[#disable speech temporarily|temporarily disables speech]]| -|FenrirKey + CTRL + P|[[#toggle punctuation level|toggles punctuation level]]| -|FenrirKey + RightBrace|[[#toggle auto spell check|toggle auto spell check]]| -|FenrirKey + Backslash|[[#toggle output|toggles output]]| -|FenrirKey + CTRL + E|[[#toggle emoticons|toggles emoticons]]| -|FenrirKey + KeyPad Enter|[[#toggle auto read|toggles auto read]]| -|FenrirKey + CTRL + T|[[#toggle auto time|toggles auto time]]| -|FenrirKey + KeyPad ASTERISK|[[#toggle highlight tracking|toggles highlight tracking]]| -|FenrirKey + Q|[[#quit Fenrir|quits fenrir]]| -|FenrirKey + T|[[#Time|Announce time]]| -|2 * FenrirKey + T|[[#Date|Announce date]]| -|FenrirKey + S|[[#spell check|spell check]]| -|2 * FenrirKey + S|[[#add word to spell check|add word to spell check]]| -|FenrirKey + Shift + S|[[#removes word from spell check|removes word from spell check]]| -|FenrirKey + Backspace|[[#forward keypress|forward keypress]]| -|FenrirKey + Up|[[#increase speech volume|increase speech volume]]| -|FenrirKey + Down|[[#decrease speech volume|decrease speech volume]]| -|FenrirKey + Right|[[#increase speech rate|increase speech rate]]| -|FenrirKey + Left|[[#decrease speech rate|decrease speech rate]]| -|FenrirKey + Alt + Right|[[#increase speech pitch|increase speech pitch]]| -|FenrirKey + Alt + Left|[[#decrease speech pitch|decrease speech pitch]]| -|FenrirKey + Alt + Up|[[#increase sound volume|increase sound volume]]| -|FenrirKey + Alt + Down|[[#decrease sound volume|decrease sound volume]]| -|FenrirKey + CTRL + Shift + C|[[#clear clipboard|clears clipboard]]| -|FenrirKey + Home|[[#first clipboard|first clipboard]]| -|FenrirKey + End|[[#last clipboard|last clipboard]]| -|FenrirKey + PageUp|[[#previous clipboard|previous clipboard]]| -|FenrirKey + PageDown|[[#next clipboard|next clipboard]]| -|FenrirKey + Shift + C|[[#read current clipboard|current clipboard]]| -|FenrirKey + C|[[#copy marked to clipboard|copy marked text to clipboard]]| -|FenrirKey + V|[[#paste clipboard|paste clipboard contents]]| -|FenrirKey + P|[[#import clipboard from file|import clipboard from file]]| -|FenrirKey + Alt + Shift +C|[[#export clipboard to file|export clipboard to file]]| -|FenrirKey + CTRL + Shift + X|[[#Remove Marks|remove marks]]| -|FenrirKey + X|[[#Set mark|set mark]]| -|FenrirKey + Shift + X|[[#Get text between marks|announce marked text]]| -^Linux specific ^ -||export clipboard to X| -|FenrirKey + CTRL + Up|include Alsa volume| -|FenrirKey + CTRL + Down|decrease Alsa volume| - -=== Laptop Layout === -^Shortcut ^Command ^ -|FenrirKey + H|[[#Tutorial Mode|toggle tutorial mode]]| -|CTRL|[[#shut up|shut up (interrupts speech)]]| -|FenrirKey + Shift + O|[[#review bottom|reviews bottom]]| -|FenrirKey + Shift + U|[[#review top|reviews top]]| -|FenrirKey + I|[[#review current line|reviews current line]]| -|FenrirKey + U|[[#review previous line|reviews previous line]]| -|FenrirKey + O|[[#review next line|reviews next line]]| -|FenrirKey + Shift + J|[[#review line beginning|reviews line beginning]]| -|FenrirKey + Shift + L|[[#review line ending|reviews line ending]]| -|FenrirKey + CTRL + J|[[#review line first character|reviews line first character]]| -|FenrirKey + CTRL + L|[[#review line last character|reviews line last character]]| -|FenrirKey + Alt + 1|[[#present first line|presents first line]]| -|FenrirKey + Alt + 2|[[#present last line|presents last line]]| -|FenrirKey + K|[[#review current word|reviews current word]]| -|FenrirKey + J|[[#review previous word|reviews previous word]]| -|FenrirKey + L|[[#review next word|reviews next word]]| -|FenrirKey + CTRL + ALT + K|[[#review current word phonetic|reviews current word phonetic]]| -|FenrirKey + CTRL + ALT + J|[[#review previous word phonetic|reviews previous word phonetic]]| -|FenrirKey + CTRL + ALT + L|[[#review next word phonetic|reviews next word phonetic]]| -|FenrirKey + comma|[[#review current character|reviews current character]]| -|FenrirKey + M|[[#review previous character|reviews previous character]]| -|FenrirKey + dot|[[#review next character|reviews next character]]| -|FenrirKey + CTRL + ALT + comma|[[#review current character phonetic|reviews current character phonetic]]| -|FenrirKey + CTRL + ALT + M|[[#review previous character phonetic|reviews previous character phonetic]]| -|FenrirKey + CTRL + ALT + dot|[[#review next character phonetic|reviews next character phonetic]]| -|FenrirKey + CTRL + I|[[#review up|reviews up]]| -|FenrirKey + CTRL + comma|[[#review down|reviews down]]| -|FenrirKey + Slash|[[#exit review|exit review]]| -|FenrirKey + Shift + dot|[[#cursor position|cursor position]]| -|2 * FenrirKey + I|[[#indent current line|indent curr line]]| -|FenrirKey + Shift + K|[[#current screen|current screen]]| -|FenrirKey + Shift + I|[[#current screen before cursor|current screen before cursor]]| -|FenrirKey + Shift + comma|[[#current screen after cursor|current screen after cursor]]| -||[[#cursor read to end of line|cursor read to end of line]]| -||[[#cursor column|cursor column]]| -||[[#cursor line number|cursor line number]]| -||[[#braille flush|Braille flush]]| -||[[#braille pan left|Braille pan left]]| -||[[#braille pan right|Braille pan right]]| -||[[#braille return to cursor|Braille return to cursor]]| -|FenrirKey + CTRL + 1|[[#clear Bookmark X|clear bookmark 1]]| -|FenrirKey + Shift + 1|[[#set Bookmark X|set bookmark 1]]| -|FenrirKey + 1|[[#read Bookmark X|bookmark 1]]| -|FenrirKey + CTRL + 2|[[#clear Bookmark X|clear bookmark 2]]| -|FenrirKey + Shift + 2|[[#set Bookmark X|set bookmark 2]]| -|FenrirKey + 2|[[#read Bookmark X|bookmark 2]]| -|FenrirKey + CTRL + 3|[[#clear Bookmark X|clear bookmark 3]]| -|FenrirKey + Shift + 3|[[#set Bookmark X|set bookmark 3]]| -|FenrirKey + 3|[[#read Bookmark X|bookmark 3]]| -|FenrirKey + CTRL + 4|[[#clear Bookmark X|clear bookmark 4]]| -|FenrirKey + Shift + 4|[[#set Bookmark X|set bookmark 4]]| -|FenrirKey + 4|[[#read Bookmark X|bookmark 4]]| -|FenrirKey + CTRL + 5|[[#clear Bookmark X|clear bookmark 5]]| -|FenrirKey + Shift + 5|[[#set Bookmark X|set bookmark 5]]| -|FenrirKey + 5|[[#read Bookmark X|bookmark 5]]| -|FenrirKey + CTRL + 6|[[#clear Bookmark X|clear bookmark 6]]| -|FenrirKey + Shift + 6|[[#set Bookmark X|set bookmark 6]]| -|FenrirKey + 6|[[#read Bookmark X|bookmark 6]]| -|FenrirKey + CTRL + 7|[[#clear Bookmark X|clear bookmark 7]]| -|FenrirKey + Shift + 7|[[#set Bookmark X|set bookmark 7]]| -|FenrirKey + 7|[[#read Bookmark X|bookmark 7]]| -|FenrirKey + CTRL + 8|[[#clear Bookmark X|clear bookmark 8]]| -|FenrirKey + Shift + 8|[[#set Bookmark X|set bookmark 8]]| -|FenrirKey + 8|[[#read Bookmark X|bookmark 8]]| -|FenrirKey + CTRL + 9|[[#clear Bookmark X|clear bookmark 9]]| -|FenrirKey + Shift + 9|[[#set Bookmark X|set bookmark 9]]| -|FenrirKey + 9|[[#read Bookmark X|bookmark 9]]| -|FenrirKey + CTRL + 0|[[#clear Bookmark X|clear bookmark 10]]| -|FenrirKey + Shift + 0|[[#set Bookmark X|set bookmark 10]]| -|FenrirKey + 0|[[#read Bookmark X|bookmark 10]]| -|FenrirKey + CTRL + 8|[[#Create Window|set window application]]| -|2 * FenrirKey + CTRL + 8|[[#Remove Window|clear window application]]| -|FenrirKey + Semicolon|[[#last incoming|read last incoming]]| -|FenrirKey + F2|[[#toggle braille|toggles braille]]| -|FenrirKey + F3|[[#toggle sound|toggles sound]]| -|FenrirKey + F4|[[#toggle speech|toggles speech]]| -|FenrirKey + Enter|[[#disable speech temporarily|temporarily disables speech]]| -|FenrirKey + Shift + CTRL + P|[[#toggle punctuation level|toggles punctuation level]]| -|FenrirKey + RightBrace|[[#toggle auto spell check|toggle auto spell check]]| -|FenrirKey + Shift + Enter|[[#toggle output|toggles output]]| -|FenrirKey + Shift + E|[[#toggle emoticons|toggles emoticons]]| -|FenrirKey + Enter|[[#toggle auto read|toggles auto read]]| -|FenrirKey + CTRL + T|[[#toggle auto time|toggles auto time]]| -|FenrirKey + Y|[[#toggle highlight tracking|toggles highlight tracking]]| -|FenrirKey + Q|[[#quit Fenrir|quits fenrir]]| -|FenrirKey + T|[[#Time|Announce time]]| -|2 * FenrirKey + T|[[#Date|Announce date]]| -|FenrirKey + S|[[#spell check|spell check]]| -|2 * FenrirKey + S|[[#add word to spell check|add word to spell check]]| -|FenrirKey + Shift + S|[[#removes word from spell check|removes word from spell check]]| -|FenrirKey + Backspace|[[#forward keypress|forward keypress]]| -|FenrirKey + Up|[[#increase speech volume|increase speech volume]]| -|FenrirKey + Down|[[#decrease speech volume|decrease speech volume]]| -|FenrirKey + Right|[[#increase speech rate|increase speech rate]]| -|FenrirKey + Left|[[#decrease speech rate|decrease speech rate]]| -|FenrirKey + Alt + Right|[[#increase speech pitch|increase speech pitch]]| -|FenrirKey + Alt + Left|[[#decrease speech pitch|decrease speech pitch]]| -|FenrirKey + Alt + Up|[[#increase sound volume|increase sound volume]]| -|FenrirKey + Alt + Down|[[#decrease sound volume|decrease sound volume]]| -|FenrirKey + CTRL + Shift + C|[[#clear clipboard|clears clipboard]]| -|FenrirKey + Home|[[#first clipboard|first clipboard]]| -|FenrirKey + End|[[#last clipboard|last clipboard]]| -|FenrirKey + PageUp|[[#previous clipboard|previous clipboard]]| -|FenrirKey + PageDown|[[#next clipboard|next clipboard]]| -|FenrirKey + Shift + C|[[#read current clipboard|current clipboard]]| -|FenrirKey + C|[[#copy marked to clipboard|copy marked text to clipboard]]| -|FenrirKey + V|[[#paste clipboard|paste clipboard contents]]| -|FenrirKey + F5|[[#import clipboard from file|import clipboard from file]]| -|FenrirKey + Alt + Shift +C|[[#export clipboard to file|export clipboard to file]]| -|FenrirKey + CTRL + Shift + X|[[#Remove Marks|remove marks]]| -|FenrirKey + X|[[#Set mark|set mark]]| -|FenrirKey + Shift + X|[[#Get text between marks|announce marked text]]| -^Linux specific ^ -||export clipboard to X| -|FenrirKey + CTRL + Up|increases Alsa volume| -|FenrirKey + CTRL + Down|decreases Alsa volume| -==== General ==== -=== quit Fenrir === -Just stops fenrir. -=== shut up === -Interrupt the current spoken. -==== Review Modes ==== -Fenrir provides a virtual cursor, with it you can navigate all over the screen without changing the text cursor. - -Using the review feature will open the review mode automatically. - -The review cursor always starts from the text cursor. Attention: after using the review mode, the review cursor will stay open until you use the ''exit review'' shortcut. - -Think when using clipboard operations and similar. The review cursor is always prefered over the text cursor. - -Fenrir sounds a bell sound if the used review command jumps to another line or end of screen. -=== exit review === -You can leave the review mode by pressing the ''exit review'' shortcut. -=== review bottom === -Set the review cursor to first column in the last line. -=== review top === -Set the review cursor to the first column in the first line -=== review current line === -Set the review cursor to the beginn of the the current line and review it. -=== review previous line === -Set the review cursor to the previous line and review it. -=== review next line === -Set the review cursor to the next line and review it. -=== review line beginning === -Set the review cursor to the begin of the current line -=== review line ending === -Set the review cursor to the end of the current line -=== review line first character === -Set the review cursor the first char (that is not space) in the current line and review it. -=== review line last character === -Set the review cursor the last char (that is not space) in the current line and review it. -=== review current word === -Sets the review cursor to the beginning of the current word and review it. -=== review previous word === -Sets the review cursor to the beginning of the previous word and review it. -=== review next word === -Sets the review cursor to the beginning of the next word and review it. -=== review current word phonetic === -Sets the review cursor to the beginning of the current word and spell it phonetic. -=== review previous word phonetic === -Sets the review cursor to the beginning of the previous word and spell it phonetic. -=== review next word phonetic === -Sets the review cursor to the beginning of the next word and spell it phonetic. -=== review current character === -Does not change the review cursor. Just announce the current char. -=== review previous character === -Sets review cursor to the previous column and review it -=== review next character === -Sets review cursor to the next column and review it -=== review current character phonetic === -Does not change the review cursor. Just announce the current char phonetic. -=== review previous character phonetic === -Sets review cursor to the previous column and announce the char phonetic. -=== review next character phonetic === -Sets review cursor to the next column and announce the char phonetic. -=== review up === -Set the review cursor in the same column one line above the current one and review it. -=== review down === -Set the review cursor in the same column one line below the current one and review it. -==== Handling marking ==== -A mark defines a point of origin or end to prepare to copy or paste a block of text. -\\ -Examples where you need marks are: - * copy to clipboard - * set window application - * set bookmark 1 - X -=== Set mark === -How to set a mark: - - navigate with review or textcursor to the position you want to set the mark. Attention: if a review cursor is set, that is the prefered. If you want to use text cursor, be sure that you are not in review mode. - - press shortcut for ''set mark'' -you can set two marks (begin and end). Some commands allow some simpler usecases just using the whole line if only one mark is set. you may want to try this out. -=== Get text between marks === -To get the text that is currently between your marks press shortcut for ''marked text''.\\ -=== Remove Marks === -You can remove all current marks by pressing the shortcut for ''remove marks''. -Changing the screen also removes the marks. -==== Screen Interaction ==== -Fenrir provides several methods to interact with the current screen. -=== forward keypress === -This just forwards the next shortcut to the screen Fenrir shortcut or not. This is useful if the currently pressed shortcut is also in use by Fenrir. -=== Clipboard === -Fenrir provides a clipboard with multible items represented by a list. You navigate throught the list and paste the selected clipboard. -== copy marked to clipboard == -To copy something to the clipboard you need to set one or two marks. if you set one mark, the text between the mark and your current cursor is copied to clipboard. Setting two marks just copies the text between the marks into the clipboard. If you copy something it is always placed as the first item on your clipboard. -== clear clipboard == -You can remove all items from the current clipboard by ''clear clipboard'' functionality. -== first clipboard == -This moves quick to the first item of the clipboard. -== last clipboard == -This moves quick to the last item of the clipboard. -== previous clipboard == -Go to previous item in the clipboard. -== next clipboard == -Go to next item on the clipboard. -== read current clipboard == -Read the content of the current item of the clipboard. -== paste clipboard == -Pass whatever item is currently selected by first, last, prev or next clipboard commands. -if no special clipboard is selected the (last copied) is used. -== export clipboard to file == -This allows you to export the current clipboard to a configurable filepath. This is useful to share the clipboard with a graphical desktop. -== import clipboard from file == -Import a clipboard from a configurable file. This is useful to share the clipboard with a graphical desktop. -==== Quick Settings ==== -Fenrir provides shortcuts to change settings temporarily and on the fly without the need to permanently change the ''settings.conf'' file. -=== toggle braille === -Enables and disables Braille. This is not persistent stored in your ''settings.conf'' but during run time. -=== toggle sound === -Enables and disables sound. This is not persistent stored in your ''settings.conf'' but during run time. -=== toggle speech === -Enables and disables speech. This is not persistent stored in your ''settings.conf'' but during run time. -=== disable speech temporarily === -Disables the speech until next key press. it might be useful if you want to listen to music or similar. As soon as a key is pressed it is going to be enabled again. -=== toggle punctuation level === -Cycle between all available punctuation levels. This is not persistent stored in your ''settings.conf'' but during run time. -=== toggle auto spell check === -Enables and disables automatic spellchecker (when typing). This is not persistent stored in your ''settings.conf'' but during run time. -=== toggle emoticons === -Enables and disables emoticons. This is not persistent stored in your ''settings.conf'' but during runtime. -=== toggle output === -Enables and disables all output at once (sound, Braille, speech). This is not persistent stored in your ''settings.conf'' but during run time. -=== toggle auto read === -Enables and disables what is automatically spoken. This is not persistent stored in your ''settings.conf'' but during run time. -=== toggle auto time === -Enables and disables auto time functionality. This is not persistent stored in your ''settings.conf'' but during run time. -=== toggle highlight tracking === -Enables and disables highlight tracking. This is not persistent stored in your ''settings.conf'' but during run time. -=== increase speech volume === -Increase the volume of the speech. This is not persistent stored in your ''settings.conf'' but during runtime. -=== decrease speech volume === -Decrease the volume of the speech. This is not persistent stored in your ''settings.conf'' but during runtime. -=== increase speech rate === -Increase the rate of the speech. This is not persistent stored in your ''settings.conf'' but during runtime. -=== decrease speech rate === -Decrease the rate of the speech. This is not persistent stored in your ''settings.conf'' but during runtime. -=== increase speech pitch === -Increase the pitch of the speech. This is not persistent stored in your ''settings.conf'' but during runtime. -=== decrease speech pitch === -Decrease the pitch of the speech. This is not persistent stored in your ''settings.conf'' but during runtime. -=== increase sound volume === -Increase the volume of the sound. This is not persistent stored in your ''settings.conf'' but during runtime. -=== decrease sound volume === -Decrease the volume of the sound. This is not persistent stored in your ''settings.conf'' but during runtime. -==== Window Mode ==== -Fenrir supports window mode, a window is a partial area of the screen. -=== Create Window === -To create a window you need to do the following: - - set a beginning mark (as the start of the window) - - set an end mark (where the window should end) - - press ''set window application'' shortcut. -Now Fenrir ignores anything outside of the window.\\ -=== Remove Window === -You can remove the window by pressing ''the clear window application'' shortcut. -Now Fenrir will read everything on the screen again. -==== Tracking Modes ==== -Different types of tracking are currently supported -See section [[#Focus|Focus]] in ''settings.conf'' for more information. -=== Cursor Tracking === -This follows the text cursor. This is the typical way an application works. This is used by: - * almost any shell such as (Bash, Zsh, sh) - * vim - * nano - * emacs - * mutt - * tintin++ -=== Highlight Tracking === -In some applications there are no text cursors. In those applications cursor changes are represented by different colors or attributes (underlined or bold). This mode tracks and announces these changes for you. This is used by: - * wifi-menu - * dialog - * alpine -==== Tutorial Mode ==== -Fenrir provides a Tutorial mode. -When you enter tutorial mode, screen reader commands are intercepted and explained instead of executing them. ''Arrow up'' and ''Arrow Down'' let you navigate through a list of all available commands with shortcuts and description. Pressing escape leaves the tutorial mode. - -==== Information ==== -=== Time === -Announces the current Time. -=== Date === -Announces the current Date. -=== Bookmarks === -Bookmarks provide quick access to part of the screen without the need to navigate to the area. -By default Fenrir provides 10 bookmarks. Those can be set and accessed via shortcut. -This is useful for status lines or other information where the position does not change. -== set Bookmark X == -You need to set the bookmark first. For that you have to set one or two lines for use. - - Set marks (one or two) - - press shortcut for ''set bookmark X''. X represents the number 1 - 10. -== read Bookmark X == -If a bookmark is set you can access the area just by pressing the ''bookmark X'' shortcut. X represents the number 1 - 10. Bookmarks are dynamic. That means the content changes with the screen. -== clear Bookmark X == -to remove a bookmark just press the ''clear bookmark X'' shortcut. X represents the number 1 - 10. -Afterward the bookmark is no longer available. -=== cursor position === -You can get information about the current cursor and its position by using the "cursor position" functionality. -=== indent current line === -Announce the current indent level of the current line. It represents the number of trailing spaces of the line. -=== current screen === -Reads all the current screen from the beginning to the end. -=== current screen before cursor === -Reads current screen from the beginning of the screen to the current cursor position. -=== current screen after cursor === -Read anything after current cursor position to the end. -=== cursor read to end of line === -Read from the current cursor position to the end of the current line. -=== cursor column === -Read the current X position of a cursor (column of the current line). -=== cursor line number === -Read the current Y position of a cursor (line number). -=== present first line === -Reads just the first line. this is maybe useful for status information. -=== present last line === -Presets the last line. This is maybe useful for status information. -=== last incoming === -Repeat the last automatically incoming text. -===== Input ===== -==== Echo ==== -Fenrir provides different methods of echoing content: - * Word: Will speak each word after you push space - * Character: speak any letter you type on the screen - * Delete Character: speaks the character prior to the cursor when you push backspace -==== Silence on Key press ==== -==== Spellchecker ==== -Fenrir has a built-in spellchecker, it can invoke automatically while typing or be called by a shortcut. -Commands to add or remove the current word to the dictionary are included. -As using the spellchecker is enhanced usage. You will need dictionary aspell-. -See section [[#General|General]] in ''settings.conf'' for more information. -=== spell check === -Invokes the spellcheck on the word that contains the Review or text cursor. -=== add word to spell check === -Adds the word under the Review or Text cursor to the dictionary. -=== removes word from spell check === -Removes the word under the Review or Text cursor from the dictionary. -===== Announcements ===== -==== Emoticons ==== -If you want to replace ":)" emoticons with "smile" in speech you can use this feature. -It can be toggled on or off. -You can define emoticons in a dictionary, please see Emoticon Dictionary. -See section [[#General|General]] in ''settings.conf'' to see how to enable or disable this feature. - -==== Time ==== -Announce the time at periodical increments, To track the time easily. -You can define 2 different ways of time announcements. - - periodic - - on fix minutes - -Example periodic, every 20 minutes "delaySec=20": - - [time] - enabled=True - presentTime=True - presentDate=True - delaySec=20 - onMinutes= - announce=True - interrupt=False - -Example on fix minutes in an hour. example every quarter "delaySec=0" and "onMinutes=00,15,30,45": - - [time] - enabled=True - presentTime=True - presentDate=True - #delaySec is repected bevore onMinutes so it need to be set to 0 - delaySec=0 - onMinutes=00,15,30,45 - announce=True - interrupt=False -==== Punctuation ==== -Fenrir handles punctuation levels and names for you with several provided dictionaries. - -See levelDict -See punctuationDict -===== Braille ===== -Fenrir provides Braille support in Version >= 2.0. -See section [[#Braille|Braille]] in ''settings.conf'' for more information. -==== braille flush ==== -If a message appears on the Braille device you can flush it to get back to the review- or system cursor -==== Braille pan left ==== -If a line is longer than your Braille devices you can move the view (called panning) to the left. -So you can read stuff without the need to move the review- or system cursor. -==== Braille pan right ==== -If a line is longer than your Braille devices you can move the view (called panning) to the right. -So you can read stuff without the need to move the review- or system cursor. -==== braille return to cursor ==== -When you have finished reading the line on the Braille device using panning, the focus can be returned to the current used cursor by using "return to cursor" command. -===== Dictionary ===== -You can make use of different kinds of built-in dictionary's. -A dictionary has a name and list of keys and values separated by :===: -Example: - [customDict] - Chrys:===:Chrys is cool - lollipop:===:lolli -that means that every instance "chrys" is displayed, speech will say Chrys is cool. -"lollipop" is spoken as "lolli". -Before making changes to a dictionary we recommend making a backup of your current dictionary in case future updates overwrite your local changes. -==== Punctuation ==== -=== Level === -The punctuation level dict contains lists with "what punctuation is spoken in what level". -the default one looks like this: - [levelDict] - none:===: - some:===:.-$~+*-/\@ - most:===:.,:-$~+*-/\@!#%^&*()[]}{<>; - all:===:!"#$%& \'()*+,-./:;<=>?@[\\]^_`{|}~ -the level "none" has no values. so it should not speak any punctuation (sadly this is not respected by every TTS system) -if "some" is the current level the following are spoken: dot dash dollar tilde plus star slash backslash at. -same for most and all, you can add new levels. if you cycle punctuation levels they are recognized. the default punctuation level is set in settings.conf. The default is "some". -=== Punctuation === -The punctuation dictionary "[punctDict]" contains how the punctuation is spoken. -Example: - [punctDict] - _:===:line -speaks an _ as "line". - [punctDict] - _:===:underscore -speaks an _ as underscore. -for question mark an ? is appended to the word that the TTS system can announce the question correctly. -==== Custom ==== -The dict "[customDict]" is just for your own use, it just replace the key with the value without any special functionality. This might be used to fix incorrectly spoken words, make words more common, shorter or just for fun. :) -==== Emoticons ==== -The Emoticons dictionary "[emoticonDict]" by default contains some emoticons. it can replace ":)" with "smile" or "XD" with "loool" Making chat more colorful. -A nice feature with this dictionary is that you can toggle the substitution on or off during run time or in settings.conf. This is useful because while doing programming or other serious work you want to hear colons and perryns not smiles. -====== Configuration ====== -You can configure Fenrir in the following places (ordered by priority): - - Commandline Parameters ''-o'' see [[#Set settings coption|Set settings coption]] - - /etc/fenrir/settings/settings.conf see [[#Settings|Settigns]] - - /config/settings/settings.conf see [[#Settings|Settigns]] - - hard coded defaults -===== Commandline Arguments ===== -==== Set settings option ==== -You can specify options that overwrite the setting.conf. -This is done with ''-o '' parameter. -The list of options have the following syntax - fenrir -o "section#setting=value;section#setting=value" - -For example changing the sound driver to gstreamer and disabling Braille - fenrir -o "sound#driver=gstreamerDriver;braille#enabled=False=False" -or change the debug level to verbose - fenrir -o "general#debugLevel=3" -You can find the available sections and variables here [[#Settings]] -See Syntax [[#settings.conf syntax]] -==== settings.conf syntax ==== -the syntax of the [[#Settings|settings.conf]] is quite simple and similar to a "*.ini" file, there are 4 different elements. - - Sections - - Settings - - Values - - Comments - -A comment starts with a # and is ignored by Fenrir. - # this is a comment -To group settings we have sections. -A section can look like this: - [Section] -A setting looks like this: - settingName=Value - -Example: - [sound] - # Turn sound on or off: - enabled=True - # Select the driver used to play sounds, choices are genericDriver and gstreamerDriver. - # Sox is default. - driver=genericDriver - -===== Settings ===== -==== Sound ==== -The sound is configured in section ''[sound]''. - -Turn sound on or off: - enabled=True -Values: on=''True'', off=''False'' - -Select the driver used to play sounds. -The genericDriver using Sox is the default. - - driver=genericDriver - -Available Drivers: - * ''genericDriver'' using the generic driver, for Fenrir <1.5 just use ''generic'' - * ''gstreamerDriver'' using the gstreamer, for Fenrir <1.5 just use ''gstreamer'' - -These are the pack of sounds used for sound icons. - theme=default -By default we ship two sound packs. - - ''default'' opus encoded, for newer Sox versions - - ''default-wav'' wav encoded, just for compatibility -Sound packs are located at /usr/share/sounds/fenrirscreenreader/ - -Sound volume controls how loud the sounds for your selected sound pack are. - volume=1.0 -Values: ''0.0'' is quietest, ''1.0'' is loudest. - -=== Generic Driver === -The generic sound driver uses shell commands for play sound and frequencies. - -''generic_play_file_command'' defines the command that is used to play a sound file. - generic_play_file_command= -''generic_frequency_command'' defines the command that is used playing frequencies. - generic_frequency_command= - -The following variables are substituted in ''generic_play_file_command'' and ''generic_frequency_command'': - * ''fenrir_volume'' = the current volume setting - * ''fenrir_sound_file'' = the sound file for an sound icon - * ''fenrir_frequency'' = the frequency to play - * ''fenrir_duration'' = the duration of the frequency - -Example generic_play_file_command (default) - generic_play_file_command=play -q -v fenrir_volume fenrir_sound_file -Example generic_frequency_command (default) - generic_frequency_command=play -q -v fenrir_volume -n -c1 synth fenrir_duration sine fenrir_frequency -==== Speech ==== -Speech is configured in section ''[speech]''. -Turn speech on or off: - enabled=True -Values: on=''True'', off=''False'' - -# Select speech driver, options are speechdDriver (default), genericDriver, dectalkDriver, dectalkUsbDriver, litetalkDriver, doubletalkDriver or tripletalkDriver: -driver=speechdDriver -#driver=genericDriver -#driver=dectalkDriver -#driver=dectalkUsbDriver -#driver=litetalkDriver -#driver=doubletalkDriver -#driver=tripletalkDriver - -Select the driver used to generate speech output. - - driver=speechdDriver - -Available Drivers: - * ''genericDriver'' using the generic driver, for Fenrir <1.5 this is not available - * ''speechdDriver'' using speech-dispatcher, for Fenrir <1.5 just use ''speechd'' - * ''dectalkDriver'' using DECtalk-compatible serial hardware or RPITalk - * ''dectalkUsbDriver'' using the native Access Solutions DECtalk USB - * ''litetalkDriver'' using LiteTalk-compatible serial hardware or RPITalk - * ''doubletalkDriver'' using DoubleTalk LT-compatible serial hardware - * ''tripletalkDriver'' using TripleTalk-compatible serial hardware - -The rate selects how fast Fenrir will speak. - rate=0.65 -Values: Range Minimum:''0.0'' is slowest, Maximum:''1.0'' is fastest. - -Pitch controls the pitch of the voice. - pitch=0.5 -Values: Range Minimum:''0.0'' is lowest, Maximum:''1.0'' is highest. - -A Pitch for capital letters can be set. - capital_pitch=0.9 -Values: Range Minimum:''0.0'' is lowest, Maximum:''1.0'' is highest. - -The Volume controls the loudness of the voice. - volume=1.0 -Values: Range Minimum:''0.0'' is quietest, Maximum:''1.0'' is loudest. - -Some speech drivers like speechdDriver can support various modules. these can be set here. - module=espeak -Values: Text, Consult speech-dispatcher's configuration to see what modules are available. - -Voice selects the varient you want to use, for example, f5 will use the female voice #5 in Espeak, -or if using the Espeak module in Speech-dispatcher. To find out which voices are available, consult the documentation provided with your selected synthesizer. - voice= -Values: Text, see your TTS synths documentation what is available. - -Select the language you want Fenrir to use. - language=english-us -Values: Text, see your TTS synths documentation what is available. - -Serial hardware speech drivers use a serial device. Set an explicit path. - hardware_device=/dev/ttyACM0 - hardware_device=/dev/ttyUSB0 - hardware_device=/dev/ttyS0 - -Hardware speech drivers use 9600 baud by default. - hardware_baud_rate=9600 - -The doubletalkDriver targets DoubleTalk LT-style serial devices. It does not support the internal DoubleTalk PC ISA card. -The dectalkUsbDriver autodetects the native Access Solutions DECtalk USB, USB ID 0dd0:2001. It requires PyUSB and a libusb backend and ignores the serial device and baud-rate settings. Other USB hardware speech synthesizers are supported only when Linux exposes them as a serial tty such as /dev/ttyACM0 or /dev/ttyUSB0. - -Read new text as it occurs -auto_read_incoming=True -Values: on=''True'', off=''False'' - -=== Generic Driver === -The generic speech driver uses shell commands for speech synthisus. - -''generic_speech_command'' defines the command that is executed for creating speech -The following variables are substituted in ''generic_speech_command'': - * ''fenrir_text'' = is the text that should be spoken - * ''fenrir_module'' = may be the speech module like used in speech-dispatcher, not every TTY needs this - * ''fenrir_language'' = the language to speak in - * ''fenrir_voice'' = is the current voice that should be used - * ''fenrir_volume'' = is replaced with the current volume - * ''fenrir_pitch'' = is replaced with the current pitch - * ''fenrir_rate'' = is replaced with the current speed (speech rate) - -Example generic_speech_command (default): - generic_speech_command=espeak -a fenrir_volume -s fenrir_rate -p fenrir_pitch -v fenrir_voice "fenrir_text" - -These are the minimum and maximum values of the TTS system used in generic_speech_command. They are needed to calculate the abstract range in volume, rate and pitch 0.0 - 1.0. - - fenrir_min_volume=0 - fenrir_max_volume=200 - fenrir_min_pitch=0 - fenrir_max_pitch=99 - fenrir_min_rate=80 - fenrir_max_rate=450 - -The current volume, pitch and rate is calculated like this -value = min + [volume,pitch,rate] * (min - max ) -==== Braille ==== -Braille is a WIP and not ready yet. -Braille support can be configured in section ''[braille]''. - -Turn braille on or off: - enabled=False -Values: on=''True'', off=''False'' - -Select the driver used for communication with a braille device. - driver=brlapiDriver -Values: Text, available Driver -Available Drivers: - * ''brlttyDriver'' using brltty for braille communication, for Fenrir <1.5 just use ''brltty'' - -The Braille layout can be configured here - layout=en -Values: Text, see braille driver for layouts. - -What should the flush timeout relate to - flushMode=word -Values: Text, an flushMode -Existing flushModes: - * ''word'' = flush after (number of words to display) * seconds - * ''char'' = flush after (number of chars to display) * seconds - * ''fix'' = flush after X seconds - * ''none'' = no automatic flush (manual via shortcut) - -Seconds to flush (see flushMode) - flushTimeout=3 -Values: Integer, in Seconds or ''-1'' = no automatic flush (manual via shortcut) -The total flush time calculates in relation to flushMode. - -How should the Braille cursor focus be tracked? - cursorFocusMode=page -Values: Text, an existing cursor focus mode -Available cursor focus modes: - * ''page'' = if the cursor crosses the border move to next page and start at begin - * ''fixCell'' = ajust the cursor on a special cell where it is always placed. the display scroll here more smooth. - - -Define the cell on the Braille device where Fenrir should scroll and keep the cursor - fixCursorOnCell=-1 -Values: Integer - * ''0'' = first cell on device, - * ''-1'' = last cell on device - * ''>0'' = fix cell number - -What cursor should Fenrir show on the Braille device - cursorFollowMode=review -Values: Text, an exsiting cursor following mode. -Existing cursor following mode: - * ''none'' = no automatic toggle command used - * ''review'' = priority to review - * ''last'' = follow last used cursor - -number of cells in panning (horizontal). How many cell should be panned on press the routing key? - panSizeHorizontal=0 -Values: Integer, - * ''0'' = display size - * ''>0'' number of cells -==== Screen ==== -The settings for screen access are configured in the ''[screen]'' section. -''vcsaDriver'' is used for Linux TTYs, and ''ptyDriver'' is used by X11 terminal mode. - -The driver to get the information from the screen: - driver=vcsaDriver -Available Drivers: - * ''vcsaDriver'' using the VCSA driver (for TTYs), for Fenrir <1.5 just use ''vcsa'' -The encoding of the screen - encoding=cp850 -Values:''cp850'' is used for Western languages like USA or Europe. - -The driver updates Fenrir with changes on the screen. - screen_update_delay=0.05 -Values: in Seconds - -If you want Fenrir to not be active on any screen for various reasons. Maybe an X server or Wayland is running on that screen. You can make Fenrir ignore it or multiple screens seperated by '','' with: - suspendingScreen= -Values: Depends on driver: - * VCSA: the number of the TTY. TTY6 is ''6''. -Example ignore TTY1 and TTY2: - suspendingScreen=1,2 - -There is also the ability to let Fenrir auto detect screens that are running an X server. So Screens running an GUI can be ignored. - autodetectSuspendingScreen=True -Values: on=''True'', off=''False'' - -==== Keyboard ==== -The settings for keyboard and input related configuration is located in the section ''[keyboard]'' of the ''settings.conf'' file. - -Select the driver used for grabbing keybord input and for recieving shortcuts. - driver=evdevDriver -Values: Text, available Driver -Available Drivers: - * ''evdevDriver'' uses the evdev input system of linux, for Fenrir <1.5 just use ''evdev'' - -You can let Fenrir know about what input devices are to be used. - device=ALL -Values: - * ''ALL'' use all devices with key capabilities. - * ''NOMICE'' Exclude mices from handling. - * '''' just use the device with the given name. - -Gives Fenrir exclusive access to the keyboard and lets it control keystrokes. This is needed to intercept Fenrir related shortcuts. - grab_devices=True -Values: on=''True'', off=''False'' - -The following makes sense if you are using a second screenreader and want to have some hooked events. Fenrir ignores all shortcuts then. - ignore_shortcuts=False -Values: on=''True'', off=''False'' - -The current keyboard layout used for shortcuts. - keyboard_layout=desktop - Values: An absolute Path to a Keyboard definition file or a Filename without extension located in ''/etc/fenrir/keyboard'' - -Announce characters while typing. - charEcho=False -Values: on=''True'', off=''False'' - -Announce deleted characters - char_delete_echo=True -Values: on=''True'', off=''False'' - -Announce word after pressing space - word_echo=False -Values: on=''True'', off=''False'' - -Interrupt speech on any keypress - interrupt_on_key_press=False -Values: on=''True'', off=''False'' - -You can filter the keys that speech should interrupt - interrupt_on_key_press_filter= -Values: (List) empty = all keys, otherwise interrupt with specified keys - -The timeout that is used for double tap shortcuts - double_tap_timeout=0.2 -Values: Seconds -==== General ==== -Overall settings can be configured from the section ''[general]''. - -Set the current debug level: - debugLevel=1 -Values: off=0, error=1, warning=2, info=3 - -the current punctuation and dict file in use: - punctuation_profile=default -Values: Text, see available profiles in ''/etc/fenrir/punctuation'' or in ''sourceTree/config/punctuation'' - -The current punctuation level in use: - punctuation_level=some -Values: Text, See available levels in the used punctuation file. - -Respect pause for punctuations: - respect_punctuation_pause=True -Values: on=''True'', off=''False'' - -Add a pause on Line break: - new_line_pause=True -Values: on=''True'', off=''False'' - -Specify the path where the clipboard should be exported to. -See [[#export clipboard to file|export clipboard to file]]. -The variable ''$user'' is replaced by the current logged username. - [clipboard] - clipboard_export_path=/tmp/fenrirClipboard -Values: Text, Systemfilepath - -The number of available clipboards: - [clipboard] - number_of_clipboards=10 -Values: Integer, 1 - 999 - -Replace emoticons like :) or ;) with text insertions: - emoticons=True -Values: on=''True'', off=''False'' - -Define the current Fenrir keys: - fenrir_keys=KEY_KP0,KEY_META,KEY_INSERT -Values, Text list, separated by comma. - -Define the current script keys: - scriptKey=KEY_COMPOSE -Values, Text list, separated by comma. - -The time format to be used for (time command) output: - timeFormat=%H:%M:%P -Values: see python specification for [[https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior|datetime.strftime]] - -The date format to be used for (date command) output: - dateFormat=%A, %B %d, %Y -Values: see python specification for [[https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior|datetime.strftime]] - -Enable or Disable spellcheck whilst typing: - auto_spell_check=True -Values: on=''True'', off=''False'' - -The use of the dictionary with spellcheck: - spell_check_language=en_US -Values: Text, see aspell dictionary's. - -Folder Path for your scripts "scriptKey" functionality: - scriptPath=/usr/share/fenrirscreenreader/scripts -Values: Text, Existing path on file system. - -Override commands or create new ones without changing the Fenrir defaults: - commandPath=/usr/share/fenrirscreenreader/commands -Values: Text, Existing path on file system. -Subfolders in commandPath are: - * ''commands'' = to create shortcut commands - * ''onInput'' = executed while typing - * ''onScreenChange'' = executed on change the screen (change from TTY4 to TTY6) - * ''onScreenUpdate'' = executed when the screen is captured - -==== Focus ==== -The configuration for basic focus is in the section ''[focus]''. -Follow the text cursor: - cursor=True -Values: on=''True'', off=''False'' - -Follow highlighted text changes (Highlight Tracking): - highlight=False -Values: on=''True'', off=''False'' -==== Review ==== -Configurations for the review mode are in the section ''[review]''. - -If "next word/ char" or "prev word/char" create a linebreak, announce it: - lineBreak=True -Values: on=''True'', off=''False'' - -If "next word/ char" or "prev word/char" cannot be performed because you reached the end of the screen, announce it: - endOfScreen=True -Values: on=''True'', off=''False'' - -Leave the review mode when pressing a key: - leaveReviewOnKeypress=False -Values: on=''True'', off=''False'' - -Leave the review mode when changing the screen (From TTY3 to TTY4): - leave_review_on_screen_change=True -Values: on=''True'', off=''False'' -==== Time ==== -The automated time announcement is configured in the section ''[time]''. -Time announcement is disabled by default. -Turn time announcement on or off: - enabled=True -Values: on=''True'', off=''False'' - -Should the time be announced: - presentTime=True -Values: on=''True'', off=''False'' - -Should the date be announced (just on date change): - presentDate=True -Values: on=''True'', off=''False'' - -Announce after a given period of seconds: - delaySec=0 -Value: in Seconds, 0 = Deactivated - -Announce after fixed minutes in an hour. if delaySec is >0 onMinutes is ignored: - onMinutes=00,30 -Example every 15 minutes: - onMinutes=00,15,30,45 - -Just play a soundicon, (not interrupting): - announce=True -Values: on=''True'', off=''False'' - -Interrupt current speech for time announcement: - interrupt=False -Values: on=''True'', off=''False'' -====== Customization ====== -===== Scripting ===== -Scripts can be in any language, bash, python, sh or others. Place your scripts in the directory /usr/share/fenrirscreenreader/scripts/ (the path is configurable in settings.conf). -The script key is the applications key. Usually this key can be found on the keyboard located just left of the right most control key. -When you name a script, the key name appears in the script seperated by the sequence __-__. So, for example, if you have a python weather script you want assigned to the script key plus the letter w you would name the script /usr/share/fenrirscreenreader/scripts/weather__-__key_w.py -Then, to access the script, simply press the script key and the letter w. -Scripts must be executable. So, make sure to chmod 755 your script when you place it in the scripts directory. -The script gets some parameters from fenrir when it is executed. So that information is available in your script then. - -==== Parameterlist ==== -^Parameter ^Content ^ -|$1|Username of the current logged in user| - -==== Examples ==== -Script that just speaks the current username when pressing ScriptKey + H.\\ -File: ''/usr/share/fenrirscreenreader/scripts/helloWorld__-__key_h.sh'': - #!/bin/bash - echo $1 - - -===== Commands ===== -You can place your own commands in "/usr/share/fenrirscreenreader/commands" (path is configurable in settings.conf). -Commands are python files with a special scheme. You can assign them to a shortcut using the filename without an extension or place them in a hook trigger like OnInput or OnScreenChange. For further information see developer guide. -Good Examples: [[https://git.stormux.org/storm/fenrir/src/branch/master/src/fenrirscreenreader/commands/commands/date.py|"date.py"]] (announce the Date), [[https://git.stormux.org/storm/fenrir/src/branch/master/src/fenrirscreenreader/commands/commands/shut_up.py|"shut_up.py"]] (interrupt output) -the basic scheme for a command is as follows: - - from core import debug - - class command(): - def __init__(self): - pass - def initialize(self, environment): - self.env = environment - def shutdown(self): - pass - def getDescription(self): - return _('No description found') - def run(self): - pass - def setCallback(self, callback): - pass - - * [[https://git.stormux.org/storm/fenrir/src/branch/master/src/fenrirscreenreader/commands/command_template.py|Template lives here]] - * The class needs to have the name "command". - * "initialize" is running once whilst loading the command. - * "shutdown" is running on unload like the command (quit fenrir) - * "getDescriptsion" just returns an string. That String is used in Tutorial Mode. - * "run" is executed when the command is invoked. (shortcut is pressed, or trigger isn't running) - * setCAllback is currently not used. and has no functionality yet. - - -====== Troubleshooting ====== -===== Fenrir does not start ===== - - Have you installed all the dependencies [[#Support and Requirements|Support and Requirements]] - - Try using master, a lot of changes take place there to make Fenrir compatible with more systems -===== Fenrir does not utilize the shortcuts ===== - - Make sure you have python3-evdev installed - - Use the latest Fenrir version - - Make sure that Fenrir has permission to /dev/input/* and /dev/uinput (or run it as root) -===== No sound at all ===== - - Run the script to configure Pulseaudio once as root and once as your user. This will setup Pulseaudio but require a restart of Pulseaudio. The script is located in ''tools/configure_pulse.sh'' - - Use ALSA - - [[https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SystemWide/|Configure Pulse system wide]] (Not recommended) - - Use gstreamerDriver: change ''settings.conf'' in the section ''sound'' the line ''driver=genericDriver'' to ''driver=gstreamerDriver'' - - Use wave sound-icons: change ''settings.conf'' in the section ''sound'' the line ''theme=default'' to ''theme=default-wav'' - - Use most current version of [[http://sox.sourceforge.net/|sox]] with opus support - - Try [[https://github.com/i-rinat/apulse|apulse]] (not tested by myself but might work). Please give me feedback if you try it out. -===== You get sound-icons but no speech ===== - - If you are using speech-dispatcher run "spd-conf" once as user and as root. - - You can test if speech-dispatcher works by invoking it as root\\ ''sudo spd-say "hello world"'' -===== Bugreports and feature requests ===== -Please report Bugs and feature requests to: -[[https://git.stormux.org/storm/fenrir/issues|https://git.stormux.org/storm/fenrir/issues]] - -for bugs please provide a [[#Howto create a debug file|debug]] file that shows the issue. -==== How-to create a debug file ==== - - Start fenrir in debug mode\\ ''sudo fenrir -d'' - - Do your stuff to reproduce the problem - - Stop fenrir (''fenrirKey + q'') -the debug file is located in ''/tmp/fenrir.log''. If another Fenrir debug -instance is already using it, check ''/tmp/fenrir2.log'', -''/tmp/fenrir3.log'', etc. - -Please be as precise as possible to make it easy to solve the problem. +Fenrir User Manual + +Fenrir is a Linux console screen reader written in Go. It reads Linux +text consoles and can run in an X11 terminal as a regular user. + +Current maintainer: Storm Dragon +Original creator: Chrys (see CREDITS) + +For build requirements and setup, see the README. + +Starting and stopping + +Run these commands from the checkout root after building fenrir: + + # Linux text console, with console and keyboard device access + sudo ./fenrir + + # X11 terminal, as your regular user + ./fenrir -x + + # Either mode can select the laptop layout + ./fenrir -x --keyboard-layout laptop + +Fenrir runs in the foreground. Press Fenrir+Q to quit. Run only one +reader on a given Linux console. Separate X11 terminal instances can run +at once. + +X11 mode starts a shell in a new PTY. The launching terminal must supply +valid DISPLAY and WINDOWID environment variables. Keyboard interception +is scoped to that terminal window; a desktop screen reader can handle +other windows. + +Console mode needs access to console devices, keyboard event devices, +and /dev/uinput. It releases keyboard input on graphical virtual +terminals and on text consoles selected in screen.ignored_vts. + +Keyboard layouts and help + +The Fenrir key is Insert, Super/Windows, or keypad 0 with NumLock off. +Hold it while pressing the other keys in a shortcut. Bare keypad review +keys also require NumLock off. + +The desktop layout uses the numeric keypad. The laptop layout uses +Fenrir chords on the main keyboard. Select a layout with +--keyboard-layout desktop or --keyboard-layout laptop, or set +keyboard.layout in the settings file. + +Press Fenrir+H or Fenrir+F1 to enter the tutorial. Command shortcuts are +announced and described instead of executed. Up and Down browse +commands; Left and Right switch between active actions, unbound actions, +and scripts. Space repeats the current item. Escape or Fenrir+F1 exits. + +The complete layouts are desktop.toml and laptop.toml. + +Screen review + +Review moves Fenrir’s reading position without moving the application’s +cursor. Return to the application cursor with the Follow cursor +shortcut. By default, application cursor movement or a screen change +also leaves review. + + ----------------------------------------------------------------------- + Action Desktop Laptop + ----------------------- ----------------------- ----------------------- + Previous / current / Keypad 7 / 8 / 9 Fenrir+U / I / O + next line + + Previous / current / Keypad 4 / 5 / 6 Fenrir+J / K / L + next word + + Previous / current / Keypad 1 / 2 / 3 Fenrir+M / Comma / + next character Period + + Top / bottom of screen Fenrir+Keypad 7 / 9 Fenrir+Shift+U / O + + Line start / end Fenrir+Keypad 4 / 6 Fenrir+Shift+J / L + + First / last text on Fenrir+Keypad 1 / 3 Fenrir+Control+J / L + line + + Read screen Fenrir+Keypad 5 Fenrir+Shift+K + + Screen before / after Fenrir+Keypad 8 / 2 Fenrir+Shift+I / Comma + cursor + + Character above / below Fenrir+Control+Keypad 8 Fenrir+Control+I / + / 2 Comma + + Follow cursor Fenrir+Keypad Period Fenrir+Slash + + Review position Keypad Period Fenrir+Shift+Period + ----------------------------------------------------------------------- + +Press the current-line or current-word shortcut twice quickly to spell +the text, or three times for phonetic reading. Press the +current-character shortcut twice for its phonetic name. The default +interval between presses is 200 ms; keyboard.multi_press_timeout_ms +changes it at launch. + +Tracking modes + +Cycle through cursor, table, and highlight with Fenrir+Keypad Asterisk +on desktop or Fenrir+Y on laptop. The startup selection is reading.mode. + +- Cursor: follows application cursor movement. +- Table: treats delimited or space-aligned text as cells. +- Highlight: follows changes to highlighted text, such as menu + selections. + +In table mode, word navigation moves between cells, line start/end moves +to the first/last cell, and first/last text moves to the first/last +character in the current cell. Place review on a header row and press +Fenrir+X to use its cells as column headers. Outside table mode, +Fenrir+X places a text-selection mark. + +Speech and automatic reading + +- Control interrupts speech. +- Fenrir+F4 toggles mute. +- Keypad Enter on desktop temporarily silences speech. Speech can return + on the next keypress or a newly recognized prompt or completion. +- Fenrir+Keypad Enter on desktop, or Fenrir+Enter on laptop, toggles + automatic reading of new text. +- Fenrir+Backspace passes the next key through to the application. + +Character echo, word echo, and cursor echo can be configured separately. +Punctuation levels are none, some, most, and all. Character review still +names punctuation. Capital indicators, emoticons, repeated-symbol +summaries, indentation feedback, and attribute feedback are configurable +in Reading. + +Fenrir+T announces the time; press twice quickly for the date. +Fenrir+Shift+V announces the Fenrir version. + +Fenrir Menu and quick settings + +Press Fenrir+F to open the Fenrir Menu. It contains settings tabs for +presentation, speech, sound, reading, keyboard, clipboard, and other +options. The form captures its navigation keys until it closes. + +- At the tab selector, use arrows to choose a tab. +- Tab and Shift+Tab move between controls and the tab selector. +- Space or Enter toggles a checkbox. +- Arrows change list selections and numeric values. +- Activate OK to save, or Cancel or Escape to discard the form’s + changes. + +Speech rate, pitch, and volume use a scale from -100 to 100. Sound +volume is between 0.0 and 1.0. Backend, device, keyboard layout, sound +theme, and other launch-only settings take effect on the next start. + +Quick settings work without opening the form: + + Shortcut Action + ----------------------------- -------------------------- + Fenrir+Space Announce current setting + Fenrir+Left / Right Previous / next setting + Fenrir+Control+Left / Right Previous / next category + Fenrir+Up / Down Change value + Fenrir+Control+S Save settings + +Quick changes apply to the current session. Save to retain them for +future launches. Session controls such as mute and temporary silence are +separate from saved startup preferences. + +Clipboard + +Use review navigation to place two marks around text with Fenrir+X, then +press Fenrir+C to copy it. In table mode Fenrir+X sets headers instead. + + Shortcut Action + -------------------------- ------------------------------------- + Fenrir+Shift+X Read marked text + Fenrir+Control+Shift+X Remove marks + Fenrir+C Copy marked text + Fenrir+Control+C Copy last presented text + Fenrir+Shift+C Read selected clipboard + Fenrir+Control+Shift+C Clear selected clipboard + Fenrir+Home / End First / last clipboard + Fenrir+PageUp / PageDown Previous / next clipboard + Fenrir+V Paste selected clipboard + Fenrir+F5 / F6 Import from / export to file + Fenrir+F7 / F8 Import from / export to X clipboard + +clipboard.number_of_clipboards limits history; the default is 200. +clipboard.export_path selects the import/export file, initially +/tmp/fenrirClipboard. clipboard.sync enables automatic X clipboard +synchronization, which requires xclip and access to the X display. + +Persistent history is optional and off by default. Set +clipboard.persistent to retain unencrypted history across launches. +Terminal sessions use ~/.local/state/fenrir/clipboard/terminal.json; +console sessions use /var/lib/fenrir/clipboard/tty.json. Same-user +readers of the same mode share persistent history. + +Spell checking and emoji + +Automatic spell checking uses Enchant 2 and a dictionary matching the +session language. Reading settings control word repetition, spoken +misspelling feedback, and misspelling sounds. + +Press Fenrir+S to open the Spellcheck Menu for the current word. The +Suggestions tab lets you edit the word and choose a suggested spelling. +The Exceptions tab lets you add words, remove selected entries with +Delete, and undo a removal. Selecting a suggestion copies it to Fenrir’s +clipboard; paste it with Fenrir+V. + +Press Fenrir+Control+E to open the Emoji Menu. Choose a category at the +tab selector, then Tab to the emoji grid. Arrows navigate, typing +filters by name prefix, and Control+Backspace clears the filter. Enter +copies the selected emoji to Fenrir’s clipboard. Escape closes the menu. + +Reading windows and live regions + +Reading regions belong to the current terminal and last for the reader +session. A reading window restricts automatic reading to a rectangle. +Live regions exclude changing areas from automatic speech while allowing +explicit reading and progress monitoring. + +Outside table mode, place two marks with Fenrir+X to define opposite +corners. Press Fenrir+Keypad Slash on desktop or Fenrir+Control+8 on +laptop to set a reading window. Press the shortcut twice quickly to +clear it. + +To create a live region, place one mark for the rest of that line, or +two marks for a rectangle, then press Fenrir+B. Fenrir assigns the first +free slot, up to ten. Region creation clears the marks. + +- Fenrir+1 through Fenrir+0 read live regions 1 through 10. +- Fenrir+Shift+1 through Fenrir+Shift+0 clear individual live regions. +- Fenrir+Shift+B lists the current reading regions. +- Fenrir+Control+B clears all live regions. +- Fenrir+Control+Shift+B clears both the reading window and live + regions. + +Sound and progress + +Sound output uses pulse for PulseAudio or PipeWire’s PulseAudio service, +or alsa for an ALSA PCM device. Select the driver and theme in Sound +settings. The ALSA device name is set with presentation.sound.device in +the file. + +Personal themes are searched under ~/.local/stormux/fenrir/sounds/ +before bundled and system themes. A theme contains WAV files and +soundicons.toml. + +Progress tones are controlled separately from speech and automatic +reading. Press Keypad Plus on desktop or Fenrir+Shift+P on laptop to +toggle them. Fenrir recognizes percentages, fractions, progress bars, +and activity indicators; tones rise with progress. Startup behavior is +set by presentation.progress.enabled. + +Configuration files + +Settings are TOML. The annotated settings.toml lists all available +options. Fenrir loads one settings file rather than merging files. + +- Regular users: first + ~/.local/share/stormux/fenrirscreenreader/settings/settings.toml, then + /etc/fenrirscreenreader/settings/settings.toml. +- Root: /etc/fenrirscreenreader/settings/settings.toml. +- --config PATH: use that file explicitly. + +If default files are absent, Fenrir uses built-in defaults. An +explicitly selected file must exist. Saving targets the selected file; +if startup used built-in defaults, saving creates the first default path +for that account. + +Create a personal settings file and validate it without opening devices: + + ./fenrir --write-config ~/.local/share/stormux/fenrirscreenreader/settings/settings.toml + ./fenrir --config ~/.local/share/stormux/fenrirscreenreader/settings/settings.toml --check-config + +Named keyboard layouts are searched in the regular user’s +~/.local/share/stormux/fenrirscreenreader/keyboard/, then +/etc/fenrirscreenreader/keyboard/, then config/keyboard/ beside the +binary. Root searches the system and bundled locations. An explicit TOML +path selects one file. Custom layouts replace the complete layout; they +are not overlays. See the keyboard guide for an example. + +Speech synthesizers + +The default driver is speech-dispatcher. Select its module, language, +and voice in Speech settings; empty values use server defaults. + +Hardware driver IDs are dectalk, dectalk-usb, litetalk, doubletalk, and +tripletalk. Serial drivers require presentation.speech.hardware_device, +for example /dev/ttyUSB0, and default to 9600 baud when +hardware_baud_rate = 0. DoubleTalk support targets the external LT +device. TripleTalk USB devices need to expose a serial tty. + +Native dectalk-usb uses libusb 1.0 and ignores serial settings. The +process needs access to the device. The Speech form’s Test synthesizer +button previews hardware choices before saving. Driver and port changes +apply at launch. + +Script shortcuts + +Fenrir searches ~/.local/stormux/fenrir/, the configured +general.script_path (default /usr/share/fenrirscreenreader/scripts), and +the bundled config/scripts/ beside the binary. Earlier directories take +priority. + +A filename such as example__-__key_y.sh assigns the script key plus Y. +The script key defaults to Compose and is configured by +general.script_keys. Scripts must be executable to run. Fenrir invokes +them directly and passes the current account name as the first argument. +Commands appear in the tutorial’s script list. + +Remote control + +Unix socket remote control is enabled by default. The standard socket is +/tmp/fenrirscreenreader-daemon.sock, and instances also have private +sockets /tmp/fenrirscreenreader-.sock. Set remote.socket_file for a +custom socket. + +Use ls to discover instances. Use a private socket to address one +reader: + + echo "ls" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock + echo "command say Hello" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock + echo "command interrupt" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock + echo "setting set reading#mode=highlight" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock + +Remote requests use section#setting=value syntax independently of TOML. +Remote speech rate, pitch, and volume use 0.0 to 1.0, mapped to the -100 +to 100 scale used in settings files and menus. For example, +speech#rate=0.8 selects rate 60. + +Other supported operations include: + +- command tempdisablespeech: temporarily silence speech. +- command clipboard TEXT: add text to the clipboard. +- command exportclipboard: export the selected clipboard. +- command window X1 Y1 X2 Y2: set a reading window, using zero-based, + inclusive coordinates. +- command resetwindow: clear the window. +- setting save: save settings. +- setting reset: clear quick and remote overrides back to the last + loaded or successfully saved settings. +- command quitapplication: quit Fenrir. + +Set remote.enabled = false to disable the service. Command and setting +requests have separate switches, enable_command_remote and +enable_settings_remote. Requests are authorized against the caller’s +account; console self-voicing also allows an account logged into the +active console. + +Command-line options + +Fenrir runs as fenrir [options]. Use --help for the built-in reference. + + ------------------------------------------------------------------------ + Option Purpose + ------------------------------------ ----------------------------------- + --help Show usage and options + + --version Print version and release channel + + -x Start a shell inside this X11 + terminal + + --config PATH Load a specific TOML settings file + + --keyboard-layout NAME_OR_PATH Select a named layout or TOML file + + --punctuation-profile NAME_OR_PATH Select a punctuation profile + + --check-config Validate settings, layout, and + punctuation without opening devices + + --write-config PATH Write effective settings to a file + and exit + + --speech-driver ID Override the configured speech + driver + + --speech-rate NUMBER Override rate, from -100 to 100 + + --speech-module NAME Select a Speech Dispatcher module + + --input-device PATH Select a console keyboard event + device; may be repeated + + --debug-file PATH Append timing and reader-decision + diagnostics + ------------------------------------------------------------------------ + +Troubleshooting + +Speech or sound is missing + +Check that speech and sound are enabled, and that the selected backend +is available. Speech Dispatcher needs a configured synthesizer. Pulse +output needs access to a running PulseAudio service, including +PipeWire’s PulseAudio service; ALSA needs access to its selected PCM +device. Root console sessions may need separate audio configuration; see +the README’s setup section. + +For hardware speech, check the driver, device path, device permissions, +and serial baud rate. Use Test synthesizer before saving a new hardware +selection. + +Keyboard input or X11 mode fails + +In console mode, check access to keyboard event devices and /dev/uinput. +In X11 mode, check DISPLAY, WINDOWID, and competing grabs on the +terminal. Use NumLock off for bare keypad review. A configured +keyboard.devices list or --input-device applies to console mode and +cannot be used with -x. + +Check configuration and collect diagnostics + +Validate an edited settings file with --config PATH --check-config. For +reader diagnostics, add --debug-file /tmp/fenrir-debug.log to the launch +command. This appends timing and reader decisions without screen text or +key values. ./fenrir --version identifies the build when reporting a +problem. + +Documentation maintenance and support + +docs/user.md is the shared manual source. With Pandoc installed, run +./docs/create_manpage.sh to regenerate docs/user.txt, docs/fenrir.adoc, +and docs/fenrir.1. The script can run from any working directory. + +Please review documentation and test instructions for the affected +workflow before submitting a change, as described in the README’s +contribution policy. + +- Project repository and issue tracker +- Fenrir Wiki +- Email list: stormux+subscribe@groups.io, with the subject subscribe. +- IRC: irc.stormux.org, channel #stormux. diff --git a/internal/app/screen_policy_test.go b/internal/app/screen_policy_test.go index 31f64c9c..2973f4bb 100644 --- a/internal/app/screen_policy_test.go +++ b/internal/app/screen_policy_test.go @@ -7,6 +7,7 @@ import ( "context" "os" "reflect" + "strings" "testing" "git.stormux.org/storm/fenrir/internal/config" @@ -15,6 +16,51 @@ import ( "git.stormux.org/storm/fenrir/internal/screen" ) +func TestLoginPromptStartupAndDelayedActivation(t *testing.T) { + for _, terminal := range []int{1, 2} { + // tty1 already has its boot login prompt. tty2's login program + // opens the console later, without a keyboard or screen event. + prompt := screen.Snapshot{Terminal: terminal, Active: true, Rows: 1, Cols: 7, Cells: []rune("login: ")} + source := &fakeSource{snapshot: prompt} + if terminal == 2 { + source.snapshot = screen.Snapshot{Terminal: terminal} + } + voice := &fakeVoice{} + var modes []bool + keys := &fakeKeys{poll: func(active bool, _ func(input.Decision)) error { + modes = append(modes, active) + return nil + }} + a, err := new_application(context.Background(), source, keys, voice, RunOptions{Settings: config.Defaults()}) + if err != nil { + t.Fatal(err) + } + t.Cleanup(a.ui.close) + if err := a.read_screen(); err != nil { + t.Fatal(err) + } + if err := a.poll_input(true); err != nil { + t.Fatal(err) + } + if terminal == 2 { + if a.lastActive || len(voice.messages) != 0 { + t.Fatal("unused console was captured or read", a.lastActive, voice.messages) + } + source.snapshot = prompt + if err := a.poll_input(false); err != nil { + t.Fatal(err) + } + } + wantModes := []bool{true} + if terminal == 2 { + wantModes = []bool{false, true} + } + if !a.lastActive || !reflect.DeepEqual(modes, wantModes) || !strings.Contains(strings.Join(voice.messages, "|"), "login:") { + t.Fatal("login prompt did not resume input and speech", terminal, modes, voice.messages) + } + } +} + // Model the console's policy boundary independently of the shared application. type policySource struct { fakeSource diff --git a/internal/console/native_linux.go b/internal/console/native_linux.go index 909a851a..8f2e8e7d 100644 --- a/internal/console/native_linux.go +++ b/internal/console/native_linux.go @@ -25,6 +25,7 @@ package console #include #include #include +#include #include #include #include @@ -36,6 +37,13 @@ static int console_state(int fd, int *mode, unsigned char *leds) { return 0; } +static int console_usage(int fd, unsigned short *mask) { + struct vt_stat state; + if (ioctl(fd, VT_GETSTATE, &state) < 0) return -errno; + *mask = state.v_state; + return 0; +} + static int read_feedback(const struct libevdev_uinput *device, struct input_event *event) { ssize_t count = read(libevdev_uinput_get_fd(device), event, sizeof(*event)); if (count < 0) return -errno; @@ -69,6 +77,19 @@ func kernel_error(code C.int) error { return syscall.Errno(-code) } +func query_usage(path string) (uint16, error) { + file, err := os.OpenFile(path, os.O_RDONLY|syscall.O_NOCTTY, 0) + if err != nil { + return 0, err + } + defer file.Close() + var mask C.ushort + if err := kernel_error(C.console_usage(C.int(file.Fd()), &mask)); err != nil { + return 0, err + } + return uint16(mask), nil +} + func query_state(path string) (bool, bool, bool, error) { file, err := os.OpenFile(path, os.O_RDONLY|syscall.O_NOCTTY, 0) if err != nil { diff --git a/internal/console/paste_linux.go b/internal/console/paste_linux.go index af82788d..29542b79 100644 --- a/internal/console/paste_linux.go +++ b/internal/console/paste_linux.go @@ -41,6 +41,18 @@ import ( // mode and the active VT before each byte; never follow a VT switch mid-paste. // Kernels that deny TIOCSTI return their error without reporting success. func (s *Source) Paste(ctx context.Context, text string, terminal int) error { + if err := ctx.Err(); err != nil { + return err + } + // Check before opening the target: otherwise our own descriptor would + // make an unused console pass the occupancy check below. + number, textMode, _, _, err := s.active() + if err != nil { + return err + } + if number != terminal || !textMode { + return fmt.Errorf("clipboard paste stopped: active VT changed") + } path := filepath.Join(s.root, "dev", fmt.Sprintf("tty%d", terminal)) file, err := os.OpenFile(path, os.O_WRONLY|syscall.O_NOCTTY|syscall.O_NONBLOCK, 0) if err != nil { diff --git a/internal/console/paste_linux_test.go b/internal/console/paste_linux_test.go index b553f820..0fa06456 100644 --- a/internal/console/paste_linux_test.go +++ b/internal/console/paste_linux_test.go @@ -60,4 +60,17 @@ func TestConsolePasteRejectsChangedTargetAndFailedInjection(t *testing.T) { if err != nil || len(data) != 0 { t.Fatal("paste wrote to terminal output", data, err) } + source.Configure_ignored_vts(nil) + source.usage = func(string) (uint16, error) { return 3, nil } + source.state = func(string) (bool, bool, bool, error) { + t.Fatal("paste queried unused target") + return true, false, false, nil + } + // Missing target distinguishes a pre-open rejection from an open failure. + if err := os.Remove(filepath.Join(root, "dev/tty2")); err != nil { + t.Fatal(err) + } + if err := source.Paste(context.Background(), "text", 2); err == nil || !strings.Contains(err.Error(), "active VT changed") { + t.Fatal("paste opened unused console before checking usage", err) + } } diff --git a/internal/console/source_linux.go b/internal/console/source_linux.go index efd9459b..0f0e23c6 100644 --- a/internal/console/source_linux.go +++ b/internal/console/source_linux.go @@ -38,6 +38,7 @@ import ( type Source struct { root string state func(string) (bool, bool, bool, error) + usage func(string) (uint16, error) changes *os.File watcher *readinessWatcher ignoredVTs atomic.Uint64 // Paste checks policy from its background worker. @@ -64,7 +65,7 @@ func OpenSource() (*Source, error) { changes.Close() return nil, err } - source := &Source{root: "/", state: query_state, changes: changes, watcher: watcher} + source := &Source{root: "/", state: query_state, usage: query_usage, changes: changes, watcher: watcher} if err := watcher.add(int(changes.Fd())); err != nil { source.Close() return nil, fmt.Errorf("watch foreground console: %w", err) @@ -94,6 +95,21 @@ func (s *Source) active() (int, bool, bool, bool, error) { if s.ignoredVTs.Load()&(uint64(1)< 1 && number < 16 { + mask, err := s.usage(filepath.Join(s.root, "dev/tty1")) + if err != nil { + return number, false, false, false, fmt.Errorf("query console use: %w", err) + } + if mask&(uint16(1)<