storm/fenrir
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated some documentation.

Browse Source
This commit is contained in:
Storm Dragon committed 2026-10-28 00:45:23 -04:00
1 parent 0e50de4c76
commit 4f5a875d0e
17 files changed
+2416 -6207
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/Howto Configure Pulse Systemwide.txt
+28 -1
View File
@@ -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.
docs/create_manpage.sh
+23 -8
View File
@@ -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
docs/diff_review_mode.md
-48
View File
@@ -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.
docs/fenrir.1
+672 -564
View File
File diff suppressed because it is too large. Load diff
docs/fenrir.adoc
+410 -2246
View File
File diff suppressed because it is too large. Load diff
docs/user.md
+352 -426
View File
@@ -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-<pid>.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-<pid>.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 <text>` - 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 <section>#<key>=<value>` - Change setting
- `setting reset` - Reset to defaults
- `setting save` - Save current settings
**Other Commands:**
- `command clipboard <text>` - Add to clipboard
- `command exportclipboard` - Export clipboard to file
- `command window <x1> <y1> <x2> <y2>` - Define window
- `command resetwindow` - Reset window
- `command vmenu <menu_path>` - 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`.
docs/user.txt
+433 -1329
View File
File diff suppressed because it is too large. Load diff