fenrir/docs/user.md

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 in the desktop layout. The laptop layout uses Caps Lock instead of Super/Windows; Insert and NumLock-off keypad 0 also work. Press Shift+Caps Lock on its own to toggle capitalization in the laptop layout. Shifted Fenrir shortcuts do not toggle capitalization. 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, choose Desktop or Laptop in the Keyboard tab of the Fenrir Menu, or set keyboard.layout in the settings file. Menu layout changes take effect on the next launch.

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 / 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. 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, without adding sentence pauses. 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. Multiple dots in numeric sequences are named, so 2026.10.31 is read as "2026 dot 10 dot 31" at some and most. A percent sign immediately after a digit is named at some and most, so 100% is read as "100 percent". Character review always names punctuation. Repeated-symbol summaries handle multiple runs in symbol-only tokens, including diffstats such as +++++----- and bracketed bars such as [#####-----]. Each run must reach the configured minimum length and be selected by the current punctuation level; shorter runs follow ordinary punctuation handling. 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. The Keyboard tab of the Fenrir Menu has separate Fenrir keys and Script keys checkbox groups for keypad Insert, Insert, Caps Lock, and Super; Compose is also available for scripts. Uncheck a key in one group before assigning it to the other. A physical key cannot serve both roles, including through an alias such as KEY_META and KEY_RIGHTMETA. At least one Fenrir key must remain selected. After OK saves the changes, modifier assignments apply when the menu closes and all held keys are released. Cancel leaves them unchanged. If X11 cannot acquire the new keys, Fenrir reports the failure and retains the previous active assignments. The saved choices remain in the file; reopen the menu to edit or retry them. Desktop/laptop layout changes still require a new launch.

The Fenrir-key checkboxes save keyboard.fenrir_keys, which overrides the layout's defaults. When that setting is omitted, the layout supplies defaults and explicitly configured script keys are excluded from them. Existing custom script keys remain unchanged when editing the checkboxes. Keypad Insert acts as a modifier only with NumLock off. Shift+Caps Lock toggles capitalization when Caps Lock serves either role. 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.