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

-h, --help
    Show help message and exit.

-v, --version
    Show version information and exit.

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

-s, --setting SETTING-FILE
    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.

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

-d, --debug
    Enable debug mode. Debug information will be logged to /var/log/fenrir.log.

-p, --print
    Print debug messages to screen in addition to logging them.

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

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

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

--x11-window-id WINDOWID
    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

Ctrl
    Stop speech (shut up)

Fenrir + H
    Toggle tutorial mode (interactive help system)

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

Fenrir + T
    Announce current time

Fenrir + S
    Spell check current word

  Review Commands (Desktop Layout)

Keypad 7
    Review previous line

Keypad 9
    Review next line

Keypad 4
    Review previous word

Keypad 6
    Review next word

Keypad 1
    Review previous character

Keypad 3
    Review next character

Fenrir + Keypad dot
    Exit review mode

  Clipboard Operations

Fenrir + C
    Copy marked text to clipboard

Fenrir + V
    Paste clipboard contents

Fenrir + Shift + C
    Read current clipboard

Fenrir + X
    Set mark (for text selection)

Fenrir + Shift + X
    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:

Speech Drivers:

•   speechdDriver - Speech-dispatcher (recommended)

•   genericDriver - Command-line TTS (espeak, etc.)

•   dectalkDriver - DECtalk-compatible serial hardware speech

•   litetalkDriver - LiteTalk-compatible serial hardware speech

•   doubletalkDriver - DoubleTalk LT-compatible serial hardware speech

•   tripletalkDriver - TripleTalk-compatible serial hardware speech

•   debugDriver - Debug/testing

Sound Drivers:

•   genericDriver - Sox-based (default)

•   gstreamerDriver - GStreamer-based

•   debugDriver - Debug/testing

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)

EXAMPLES

fenrir
    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

Instance Discovery:
        # 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.

Basic Speech Control:
        # 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

Settings Control:
        # 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

Clipboard Operations:
        # 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

Speech Commands:

•   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

Settings Commands:

•   setting set <section>#<key>=<value> - Set configuration value

•   setting reset - Reset all settings to defaults

•   setting save [path] - Save current settings

Other Commands:

•   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

Speech Control:

•   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 Control:

•   screen#ignore_screen=1,2,3 - TTY screens to ignore

•   focus#highlight=True/False - Follow text highlighting

Input Control:

•   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

/var/log/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)

  Recommended

•   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

SIGTERM, SIGINT
    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