Scroll to navigation

FENRIR(1) User Commands FENRIR(1)

NAME

fenrir - A modern, modular console screen reader for Linux

SYNOPSIS

fenrir [-h] [-v] [-f] [-s SETTING-FILE] [-o SECTION#SETTING=VALUE;..] [-d] [-p] [-x] [--x11-window-id WINDOWID] [-F] [-i SCREEN]

DESCRIPTION

Fenrir is a modern, modular, flexible and fast console screen reader written in Python 3. It provides spoken feedback for Linux console applications and supports Linux TTYs plus X11 terminal mode.

Fenrir features a modular driver architecture supporting multiple speech synthesizers, sound systems, input methods, and screen reading techniques. It includes advanced features like review mode, multiple clipboards, spell checking, bookmarks, and configurable key bindings.

OPTIONS

Show help message and exit.

Show version information and exit.

Run Fenrir in the foreground instead of as a daemon. Useful for debugging and testing.

Path to a custom settings file. Default is /etc/fenrirscreenreader/settings/settings.conf for root and ~/.local/share/stormux/fenrirscreenreader/settings/settings.conf for regular-user saves.

Override settings file options. Format: SECTION#SETTING=VALUE;... (case sensitive). Multiple settings can be separated by semicolons.

Enable debug mode. Debug information will be logged to /tmp/fenrir.log by default. If another Fenrir debug instance is already using it, Fenrir uses /tmp/fenrir2.log, /tmp/fenrir3.log, etc.

Print debug messages to screen in addition to logging them.

Force Fenrir to respond on all screens, ignoring the ignore_screen setting. This temporarily overrides screen filtering for the current session.

Ignore specific screen(s). Can be used multiple times to ignore multiple screens. This is equivalent to setting ignore_screen in the configuration file and will be combined with any existing ignore settings.

Run in X11 terminal mode using PTY screen monitoring and X11 keyboard input scoped to the terminal window.

Use a specific X11 terminal window id for X11 terminal mode.

KEY CONCEPTS

Fenrir Key

The Fenrir Key is used to invoke screen reader commands. By default, the following keys act as Fenrir Keys:

•
Insert
•
Keypad Insert
•
Meta (Super/Windows key)

Keyboard Layouts

Fenrir supports two main keyboard layouts:

•
Desktop Layout - Uses numeric keypad for navigation (recommended for desktop users)
•
Laptop Layout - Alternative bindings for keyboards without numeric keypad

Review Mode

Fenrir provides a virtual cursor that allows navigation around the screen without changing the text cursor position. This is essential for reviewing content without disrupting your work.

BASIC COMMANDS

Essential Navigation

Stop speech (shut up)

Toggle tutorial mode (interactive help system)

Quit Fenrir

Read current screen

Read current line

Read current word

Read current character

Announce current time

Spell check current word

Review Commands (Desktop Layout)

Review previous line

Review next line

Review previous word

Review next word

Review previous character

Review next character

Exit review mode

Clipboard Operations

Copy marked text to clipboard

Paste clipboard contents

Read current clipboard

Set mark (for text selection)

Announce marked text

CONFIGURATION

Settings File

The main configuration file is located at:

•
/etc/fenrirscreenreader/settings/settings.conf (system-wide installation)
•
~/.local/share/stormux/fenrirscreenreader/settings/settings.conf (user-local settings)
•
config/settings/settings.conf (development/git version)

When Fenrir runs as a regular user, including fenrir -x, it loads the user-local settings file if it exists. If it does not exist, Fenrir falls back to the system settings file, but saving settings writes to the user-local path. When Fenrir runs as root, settings save to the system-wide path by default.

User sound themes are loaded before system themes from ~/.local/stormux/fenrir/sounds/. User scripts are loaded before configured system scripts from ~/.local/stormux/fenrir/.

Key Sections

[speech]
Configure speech synthesis (rate, pitch, volume, driver)

[sound]
Configure sound output and sound icons

[keyboard]
Configure input driver and keyboard layout

[screen]
Configure screen reading driver and ignored screens

[general]
General settings like punctuation, clipboard, and debug levels

Driver Configuration

Fenrir uses a modular driver system:

•
speechdDriver - Speech-dispatcher (recommended)
•
genericDriver - Command-line TTS (espeak, etc.)
•
dectalkDriver - DECtalk-compatible serial hardware speech
•
dectalkUsbDriver - Native Access Solutions DECtalk USB hardware speech
•
litetalkDriver - LiteTalk-compatible serial hardware speech
•
doubletalkDriver - DoubleTalk LT-compatible serial hardware speech
•
tripletalkDriver - TripleTalk-compatible serial hardware speech
•
debugDriver - Debug/testing

•
genericDriver - Sox-based (default)
•
gstreamerDriver - GStreamer-based
•
debugDriver - Debug/testing

•
evdevDriver - Linux evdev (recommended for Linux)
•
x11Driver - X11 terminal-scoped input for fenrir -x

•
vcsaDriver - Linux VCSA devices (TTY)
•
ptyDriver - Terminal emulation

•
unixDriver - Unix socket remote control (recommended)
•
tcpDriver - TCP socket remote control (localhost only)

EXAMPLES

Start Fenrir as a daemon with default settings.

fenrir -f -d
Run Fenrir in foreground with debug output.

fenrir -o speech#rate=0.8;sound#volume=0.5
Override speech rate and sound volume settings.

fenrir -F
Force Fenrir to work on all screens, ignoring ignore_screen settings.

fenrir -s /home/user/my-fenrir.conf
Use a custom configuration file.

REMOTE CONTROL

Fenrir includes a powerful remote control system for automation and integration with external applications.

Configuration

Enable remote control in /etc/fenrirscreenreader/settings/settings.conf or the user-local settings file:

[remote]
enable=True
driver=unixDriver
enable_settings_remote=True
enable_command_remote=True

Using socat with Unix Sockets

# 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.

# Interrupt current speech
echo "command interrupt" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock
# Speak custom text
echo "command say Hello, this is a test" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock
# Temporarily disable speech
echo "command tempdisablespeech" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock
    

# Enable highlight tracking
echo "setting set focus#highlight=True" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock
# Change speech rate
echo "setting set speech#rate=0.8" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock
# Change punctuation level (none/some/most/all)  
echo "setting set general#punctuation_level=all" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock
# Voice and TTS control
echo "setting set speech#voice=en-us+f3" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock
# Multiple settings at once
echo "setting set speech#rate=0.8;sound#volume=0.7;general#punctuation_level=most" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock
# Reset all settings
echo "setting reset" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-daemon.sock
    

# 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

Command Reference

•
command say <text> - Speak the specified text
•
command interrupt - Stop current speech
•
command tempdisablespeech - Disable speech until next key press
•
ls / list / command ls / command list - List registered Fenrir instances

•
setting set <section>#<key>=<value> - Set configuration value
•
setting reset - Reset all settings to defaults
•
setting save [path] - Save current settings

•
command clipboard <text> - Add text to clipboard
•
command window <x1> <y1> <x2> <y2> - Define window area
•
command resetwindow - Reset to full screen
•
command vmenu <menu_path> - Set virtual menu
•
command resetvmenu - Reset virtual menu
•
command quitapplication - Quit Fenrir

Important Controllable Settings

•
general#punctuation_level=none/some/most/all - Punctuation verbosity
•
speech#rate=0.1-1.0 - Speech rate
•
speech#pitch=0.1-1.0 - Speech pitch
•
speech#volume=0.1-1.0 - Speech volume
•
speech#voice=voice_name - Voice selection
•
speech#module=module_name - TTS module

•
screen#ignore_screen=1,2,3 - TTY screens to ignore
•
focus#highlight=True/False - Follow text highlighting

•
keyboard#char_echo_mode=0-2 - Character echo mode
•
keyboard#word_echo=True/False - Word echo

FILES

/etc/fenrirscreenreader/settings/settings.conf
Main configuration file

~/.local/share/stormux/fenrirscreenreader/settings/settings.conf
User-local configuration file

/etc/fenrirscreenreader/keyboard/
Keyboard layout definitions

/etc/fenrirscreenreader/punctuation/
Punctuation level definitions

/usr/share/sounds/fenrirscreenreader/
System sound themes

~/.local/stormux/fenrir/sounds/
User sound themes

~/.local/stormux/fenrir/
User scripts

/tmp/fenrir.log
Debug log file

/run/fenrir.pid
Process ID file when running as daemon

ENVIRONMENT

Fenrir respects standard Linux permissions and requires appropriate access to:

•
/dev/input/* (for evdev input driver)
•
/dev/uinput (for key injection)
•
/dev/vcsa* (for VCSA screen driver)
•
DBus system bus (for screen change detection)

DEPENDENCIES

Required

•
Python 3.6 or later
•
python3-evdev (for evdev input driver)
•
python3-pyudev (for device detection)

•
speech-dispatcher and python3-speechd (for speech)
•
sox with opus support (for sound)
•
espeak-ng (for speech synthesis)

Optional

•
python3-pyenchant and aspell-* (for spell checking)
•
python3-daemonize (for daemon mode)
•
pyalsaaudio (for ALSA volume control)

SIGNALS

Gracefully shut down Fenrir

EXIT STATUS

0
Success

1
General error (configuration, permission, etc.)

BUGS

Report bugs to the project maintainer or via the project repository.

AUTHORS

Current maintainer: Storm Dragon

Previous developer: Chrys

Contributors: Jeremiah and others

COPYRIGHT

This software is licensed under the LGPL v3.

SEE ALSO

speechd(1), espeak(1), espeak-ng(1), sox(1)

Full documentation: https://git.stormux.org/storm/fenrir/wiki

Support: stormux+subscribe@groups.io

2025 Fenrir Screen Reader