fenrir/docs/user.txt

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

    # Linux console in the foreground (also use -f with service managers)
    sudo ./fenrir -f

    # X11 terminal, as your regular user
    ./fenrir -x

    # Either mode can select the laptop layout
    ./fenrir -x --keyboard-layout laptop

Console mode starts in the background by default. Add -f to keep it in
the foreground, including under a service manager. The launcher returns
after the reader initializes and reports startup failures in the
launching terminal. Use --debug-file PATH to retain diagnostics after
detaching. Help, version, and configuration-only commands always run in
the foreground.

X11 mode (-x) always stays in the foreground because it owns the
terminal and its child shell. Press Fenrir+Q to quit either mode. 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. Fenrir uses visible headings
automatically when a text heading is followed by a row with at least two
numeric fields. You can enter table mode, run free -h, and review its
cells without setting headers yourself. Aligned tables use shared column
boundaries so an unnamed heading or an empty field does not shift the
remaining columns. Multiword headings and values stay in their cells
when the visible alignment distinguishes them.

When you begin reviewing a recognized table at or immediately above the
application cursor, review starts at the first cell of its first data
row. For example, after free -h, current word reads Mem: and next word
reads the total memory value. The application cursor stays in place.
Existing review positions are preserved while output updates; manual
headers or clearing headers disable this automatic starting position.

Automatic headers are inferred from the visible output block being
reviewed; they are not remembered after the heading scrolls off screen.
Text-only tables, wrapped output, and ambiguous or grouped headings may
require manual selection. Place review on the desired header row and
press Fenrir+X to replace the automatic headers. For grouped headings,
select the row naming individual columns. Manual headers remain until
cleared, table mode is left, or the screen session changes.

Press Fenrir+Control+Shift+X to clear headers and use generic column
numbers. Automatic header assignment stays off until you leave and
re-enter table mode or the screen session changes; Fenrir+X can still
set headers manually. Outside table mode, Fenrir+X places a
text-selection mark instead.

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. At some and most,
punctuation inside words, URLs, email addresses, and filenames is also
named. Apostrophes within words and single numeric separators such as
those in 3.14, 1,000, and 12:30 follow the selected level. Sentence
punctuation follows the selected level too. Character review always
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, internal UI, 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. For speech
rate, Up and Down change the value by 10; Left and Right change it by 1.
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.

The Internal UI tab controls speech in Fenrir’s own menus and dialogs.
Announce grid row and column and Announce item position are independent
checkboxes, both enabled by default. Disable coordinates to omit “row 1,
column 2”; disable item position to omit “2 of 20”. Item names and grid
navigation remain available with both disabled. Saved changes apply
immediately to Emoji and Spellcheck grids and persist across launches.
These are global settings, so this tab is omitted from application
settings. The TOML keys are internal_ui.announce_grid_coordinates and
internal_ui.announce_item_position.

Settings saves use mode 644 for the standard system settings file at
/etc/fenrirscreenreader/settings/settings.toml, so other users can read
it as a startup fallback. Personal settings and application profiles use
mode 600.

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.

Application overrides

Press Fenrir+A to open Applications. Up and Down select an item; Enter
activates it and closes the menu. Escape or the Cancel button closes the
menu without changing the selection. Tab and Shift+Tab move between the
list, Copy alias to clipboard, Cancel, and the tab selector. The active
override is initially selected.

Type the start of a name to jump to it: n selects NetworkManager, then i
selects Ninjam. Searching ignores letter case and does not activate the
item. Backspace removes a search character; Control+Backspace clears the
search. Up, Down, or moving focus away from the list also clears the
search. Unmatched characters announce No matches and leave the last
matching search intact.

Start the application normally, then select its override. This menu does
not launch programs. Choose Default to restore the settings and reading
regions that were in effect before the override. Overrides are built
into Fenrir and are never selected automatically or remembered across
restarts.

To launch a program with its override, select its name in this list,
then Tab to Copy alias to clipboard and press Enter. This copies a Bash
alias into Fenrir’s clipboard without selecting the override or closing
the menu. Paste it into your Bash configuration, such as ~/.bashrc, and
load that configuration in a new shell. The aliases use the executable
names cninjam, nmtui, rogue, and codex; Default has no alias. Existing
aliases with those names are replaced when you load the definition.

The alias requests the override through socat, then launches the real
program with the arguments you supplied. Errors remain visible, and the
program still launches if the request fails, remote control is disabled,
or Fenrir or socat is missing. Socket inactivity is limited to two
seconds. It uses the standard socket, or your configured
remote.socket_file, rather than a process-specific socket that changes
at restart. Paste with Fenrir’s clipboard command; desktop clipboard
synchronization follows your normal clipboard settings.

While an override is active, Fenrir+F opens its application settings,
with the application name in the title. OK, Fenrir+Control+S, and remote
SETTING SAVE save that application’s preferences. Quick and remote
changes remain temporary until saved. Default settings are kept
separately, including any unsaved adjustments made before activating the
override.

Profiles live in an applications/ subdirectory of the ordinary settings
save directory. For example:

- System settings:
  /etc/fenrirscreenreader/settings/applications/ninjam.toml.
- Personal settings:
  ~/.local/share/stormux/fenrirscreenreader/settings/applications/ninjam.toml.
- With --config /path/settings.toml: /path/applications/ninjam.toml.

NetworkManager uses networkmanager.toml; Rogue uses rogue.toml; Codex
uses codex.toml. The directory and file are created on the first
successful save. Files contain only customized settings; omitted values
inherit ordinary settings followed by the built-in application defaults.
A customized voice selection saves module, language, and voice together
so a later change to the ordinary voice does not break that selection.
Profiles are loaded when their override first recognizes the
application; restarting Fenrir still starts with Default. Reselect the
application to reload an edited file.

Application settings include voice, rate, pitch, volume, reading
behavior, sound enablement/volume, and typing echo. Startup settings
such as speech driver, serial device, keyboard layout, and sound theme
remain in the default menu; clipboard storage and console routing also
remain global. Session mute and the temporary automatic-reading toggle
are not implicitly saved. Remote SAVEAS and screen#ignore_screen are
unavailable while an application is active. Saving is blocked during
context transitions or failed voice restoration. A malformed profile or
unavailable voice leaves ordinary settings in effect and reports an
error. Select the application again after correcting the file.

For example, a rate-only profile contains current TOML setting names,
with no top-level version field:

    [presentation.speech]
    rate = 40

To make a saved value inherit again, remove that setting from the
application file and reselect the override. Removing the file restores
complete inheritance.

An override belongs to its terminal. Switching VTs or leaving the
terminal suspends its effects; returning resumes it when the application
screen is recognized. Unrecognized screens use ordinary reading. A fresh
shell prompt on the cursor row, with the application interface absent,
clears the selection and announces Default settings restored. This works
from screen contents, so it does not require access to remote processes
over SSH or inside GNU Screen. Unusual prompts may require selecting
Default manually. Password prompts, confirmation questions, and old
shell prompts in scrollback do not clear it. Split windows, heavily
customized application colors, and localized or unfamiliar layouts may
prevent recognition; Default is always available.

NetworkManager targets nmtui and temporarily selects highlight tracking.

Ninjam targets the cninjam curses client. It announces selected controls
with master, metronome, or channel context; mute, transmit, and receive
controls are spoken as states. While adjusting a volume/pan control,
Left/Right announces only the pan percentage and direction, or center;
Up/Down announces only the volume, with minus and plus spoken
explicitly. Peak meters and the interval bar remain quiet. Navigating
the application’s controls after manual review resumes tracking; passive
updates leave review in place. Incoming chat is announced independently
of control changes. The following shortcuts temporarily replace numbered
region reads:

  Shortcut   Ninjam information
  ---------- ---------------------------------------------------
  Fenrir+1   Latest new chat message received since activation
  Fenrir+2   Selected channel or control
  Fenrir+3   Connection, tempo, and interval position

Fenrir+Shift+B lists these application assignments. Existing user
regions are preserved and restored when the override ends. Review, Read
Screen, and copying continue to expose the actual terminal text,
including its literal X marks. Chat history is baselined on activation,
resize, buffer changes, and history paging to avoid announcing old
messages as new. Messages that appear and disappear between screen
captures cannot be recovered reliably.

The laptop shortcut for reading attributes is Fenrir+Shift+A; Fenrir+A
opens Applications in both layouts.

Rogue targets the classic English Rogue 5.4 terminal game, including the
5.4.4 package. Start rogue, then select Rogue with Fenrir+A (type r,
then Enter). The override announces messages and prompts, including
More; press Space, changes in health, hunger, dungeon level, strength,
armor, and experience level, and newly visible monsters, objects, doors,
stairs, and traps. Ordinary map redraws stay quiet. Moving monsters are
compared by letter and count to reduce repeated announcements. Their
current positions remain available on request. Appearing and
disappearing messages between captures, or one monster replacing another
of the same letter without a count change, cannot reliably be
distinguished from the visible display alone.

  Shortcut   Rogue information
  ---------- --------------------------------------------------------
  Fenrir+1   Health, for example “Health: 12 of 12”
  Fenrir+2   Full status line
  Fenrir+3   Latest message or prompt
  Fenrir+4   Eight neighboring cells, clockwise from north
  Fenrir+5   Visible monsters and their positions relative to you
  Fenrir+6   Visible objects and landmarks, with relative positions

These explicit reads include their region names. Names are supported by
the shared application-region API, so other overrides can use them as
needed. Fenrir+Shift+B lists the assignments. Slots 7 through 10 remain
available for manual regions. Existing user regions are preserved while
the override is active and restored when it ends, as with Ninjam.

Directions give cell offsets, for example “bat, north 2, east 3.”
Descriptions use only displayed symbols; they do not reveal hidden
monsters, secret doors, or unidentified items. Blank cells are described
as unseen, and hallucination or disguised monsters can make the
displayed symbols misleading. The playfield uses the first 24 rows and
80 columns even in a larger terminal, with status on row 24. Inventory,
help, and options pages use ordinary reading and review; map regions
report information unavailable on those pages. Slow inventory uses the
ordinary message region. Read Screen, review, and copying retain the
actual terminal text. Unrecognized screens return to ordinary reading.

Developers can exercise an installed classic Rogue in private PTYs
without touching the active reader:

    FENRIR_ROGUE_TEST_BINARY=/usr/bin/rogue go test ./internal/terminal -run TestRogueLiveOverride -v

Codex CLI

The Codex override replaces automatic terminal diffs with completed
assistant messages. It suppresses tool output, streaming fragments, and
redraws. Manual screen review remains available, and typing echo is
limited to the composer. Messages are retained in memory even while
speech is muted or automatic reading is disabled. Existing lifecycle
alerts remain separate from reply reading. Left/Right navigation retains
character feedback inside the composer. While Codex is working, the
existing activity tone sounds once every four seconds without requiring
redraws. It stops for approval/question waits and completion, respects
the sound and progress toggles, and remains independent of speech mute.

  -----------------------------------------------------------------------
  Shortcut                            Codex information
  ----------------------------------- -----------------------------------
  Fenrir+1 through Fenrir+9           Recent completed assistant
                                      messages, newest first

  Fenrir+0                            Working, ready, waiting for
                                      approval or an answer, finished, or
                                      interrupted
  -----------------------------------------------------------------------

Select Codex with Fenrir+A, type c, then Enter. Select Default to leave
the override. Without its bridge, the override suppresses automatic
screen changes and the status shortcut says Waiting for Codex bridge.

The optional bridge requires Python 3 and Fenrir remote command control
enabled. Merge a command hook invoking
python3 /absolute/path/to/fenrir/tools/codex_bridge.py into each of
these events in ~/.codex/hooks.json: SessionStart, UserPromptSubmit,
PermissionRequest, PostToolUse, Stop, Interrupt, and SessionEnd. For
example, one event entry is:

    {
      "hooks": {
        "SessionStart": [{"hooks": [{"type": "command", "command": "python3 /absolute/path/to/fenrir/tools/codex_bridge.py", "timeout": 3}]}]
      }
    }

Preserve existing hooks. Review and trust the added hooks through
Codex’s /hooks interface; restart or resume Codex if required by the
installed version. Starting or resuming a conversation starts a detached
bridge follower; submitting a prompt also restarts it if necessary. The
bridge never speaks or answers approvals.

The follower reads only the transcript path supplied by that
conversation’s hook and verifies its session identifier. It accepts
completed assistant events, never tool results, reasoning, or streamed
deltas. It keeps the nine latest replies in memory and writes only
status, conversation identifiers, and lock files to a private runtime
directory. Switching conversations replaces the terminal binding;
packets from an older conversation cannot overwrite the new history.
Existing history is loaded silently on attachment or bridge restart.
Long replies are transported in chunks and announced only after
assembly; the current per-message limit is 1 MiB. The worker stops when
Codex exits or a SessionEnd hook runs.

X11 routing requires the same WINDOWID as the Fenrir instance; Linux
console routing uses Codex’s controlling VT and the reader’s existing
authorization. Other windows and consoles do not receive the replies.
This local bridge does not forward SSH audio or attach a remote Codex
server to a local terminal.

The transcript parser was checked against Codex CLI 0.165.0. It uses
Codex’s local completed-event records, rather than a public subscription
API; a changed record format may require an update. Status comes from
hooks and recorded turn events, not the terminal’s animated activity
label. Check Fenrir+0 after resuming.

For a private protocol and keyboard test without live speech or Codex
requests:

    go build -o fenrir ./cmd/fenrir
    python3 -m unittest discover -s tests -p test_codex_bridge.py
    xvfb-run -a env FENRIR_PRIVATE_X11=1 python3 tests/native_codex.py

Real acceptance still needs a Codex reply spoken once after completion,
working status on demand, history review, composer typing,
approval/question handling, and returning to ordinary reading after
choosing Default or exiting Codex.

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.

Speech Dispatcher has its own synthesis and audio configuration,
separate from Fenrir’s sound cues. For an X11 terminal session, run
./fenrir -x as your regular user. With sudo, Fenrir uses SUDO_UID to
locate the invoking user’s PulseAudio socket. The default sound driver
tries the user session, then /tmp/pulse.sock, then /run/pulse/native.
Set PULSE_SERVER to select an explicit server; the sound driver does not
read PulseAudio’s client.conf. The sound service must already be running
and accessible to the reader. See Speech synthesizers for Speech
Dispatcher addresses and autostart behavior.

If root sound needs additional configuration, the checkout includes
configure_pulse.sh for PulseAudio and 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 scripts change system audio
configuration and are only needed when the existing audio setup does not
provide the required access.

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.

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. Python
settings.conf files are ignored. Regular users save to their personal
TOML file, including when startup loaded system defaults; root saves to
the system file. --config PATH explicitly selects both the load and save
path, and that file must exist at startup.

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.

Fenrir uses SPEECHD_ADDRESS when set: unix_socket:/absolute/path selects
a Unix socket, and inet_socket:HOST:PORT selects TCP (default host
127.0.0.1, port 6560). Invalid addresses report an error. Otherwise,
SPEECHD_SOCKET selects a Unix socket. Without either variable, Fenrir
uses $XDG_RUNTIME_DIR/speech-dispatcher/speechd.sock, falling back to
$XDG_CACHE_HOME/speech-dispatcher/speechd.sock or
~/.cache/speech-dispatcher/speechd.sock when the runtime directory is
unset. With sudo, the default remains
/run/user/$SUDO_UID/speech-dispatcher/speechd.sock. Sudo may remove
address variables; preserve them explicitly if needed.

When opening speech, Fenrir first tries the selected server. If its
socket is missing or refuses connections, Fenrir requests
speech-dispatcher --spawn and briefly retries. The daemon’s
configuration controls whether spawning is allowed. SPEECHD_CMD can
select another executable. Autostart is limited to Unix sockets and
local loopback TCP servers. When sudo changes the account, start Speech
Dispatcher as the invoking user first; Fenrir will not launch a
root-owned daemon for that user. Settings discovery never starts a
daemon or interrupts the active speaking client.

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:

    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 application ID: select default, networkmanager, ninjam, rogue,
  or codex for this reader’s active terminal, like Fenrir+A. This
  requires command remote control. An empty reply means selection
  succeeded; invalid IDs, busy settings, and restoration failures return
  an error. Application recognition and profile loading happen later,
  when the application appears; this command does not launch it. default
  restores ordinary settings. Use a private socket when targeting a
  particular reader.
- 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

  -f                                   Keep console mode in the foreground
                                       (always enabled with -x)

  -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 and docs/fenrir.1.
The script can run from any working directory. Edit the Markdown source
rather than the generated files. The bundled docs/man_tables.lua filter
renders man-page tables as labeled lists for narrow terminals.

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.