A modern, modular, flexible and fast console screen reader. It should run on any operating system. If you want to help, or write drivers to make it work on other systems, just let me know. This software is licensed under the LGPL v3.
Current maintainer: Storm Dragon
Previous developer: Chrys
If there is a package for your distrobution of choice, please let us know so we can add it here.
You can also just run it from Git without installing: Requires root privileges
cd src/ sudo ./fenrir
Settings are located in:
/etc/fenrir/settings/settings.confconfig/settings/settings.confBy default Fenrir uses:
Both PulseAudio and PipeWire require special configuration to allow console applications running as root (like Fenrir) to route audio to your regular user session. This is normal audio system behavior, not a Fenrir issue.
For non-Fenrir users or quick setup, download and run these scripts directly:
# Download the script
wget https://git.stormux.org/storm/fenrir/raw/branch/master/tools/configure_pulse.sh
chmod +x configure_pulse.sh
# Run twice: once as user, once as root
./configure_pulse.sh
sudo ./configure_pulse.sh
# Download the script
wget https://git.stormux.org/storm/fenrir/raw/branch/master/tools/configure_pipewire.sh
chmod +x configure_pipewire.sh
# Run twice: once as user, once as root
./configure_pipewire.sh
sudo ./configure_pipewire.sh
Direct links:
If you have Fenrir installed, the scripts are available at:
PulseAudio:
/usr/share/fenrirscreenreader/tools/configure_pulse.sh
sudo /usr/share/fenrirscreenreader/tools/configure_pulse.sh
PipeWire:
/usr/share/fenrirscreenreader/tools/configure_pipewire.sh
sudo /usr/share/fenrirscreenreader/tools/configure_pipewire.sh
Note: These scripts work for any console application that needs root audio access, not just Fenrir.
Start Fenrir:
sudo systemctl start fenrir # If installed as service
# OR
sudo fenrir # Run directly
Basic Navigation:
Insert, Keypad Insert, or Meta/Super keyFenrir + H to learn all commands interactivelyFenrir + QEssential Commands:
Ctrl - Stop speech (shut up)Fenrir + Keypad 5 - Read current screenKeypad 8 - Read current lineKeypad 5 - Read current wordKeypad 2 - Read current characterFenrir + T - Announce timeFenrir + S - Spell check current wordFenrir + Keypad * - Toggle table mode / highlight trackingFenrir supports two main keyboard layouts:
Configure in /etc/fenrir/settings/settings.conf:
[keyboard]
keyboardLayout=desktop # or 'laptop'
Enable Fenrir at boot:
sudo systemctl enable fenrir
Configure audio (if needed):
Test speech:
# Test speech-dispatcher directly
sudo spd-say "Hello World"
Fenrir includes a powerful remote control system that allows external applications and scripts to control Fenrir through Unix sockets or TCP connections. This is particularly useful for automation, integration with other applications, or providing alternative control methods.
Enable remote control in /etc/fenrir/settings/settings.conf:
[remote]
enable=True
driver=unixDriver # or tcpDriver
port=22447 # for TCP driver
socketFile= # custom socket path (optional)
enableSettingsRemote=True # allow settings changes
enableCommandRemote=True # allow command execution
unixDriver (recommended): Uses Unix domain sockets
/tmp/fenrirscreenreader-deamon.sock (TTY mode) or /tmp/fenrirscreenreader-<pid>.socksocattcpDriver: Uses TCP sockets on localhost
netcat, telnet, or any TCP clientThe socat command provides the easiest way to send commands to Fenrir:
# Interrupt current speech
echo "command interrupt" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Speak custom text
echo "command say Hello, this is a test message" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Temporarily disable speech (until next keystroke)
echo "command tempdisablespeech" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Enable highlight tracking mode
echo "setting set focus#highlight=True" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Change speech parameters
echo "setting set speech#rate=0.8" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
echo "setting set speech#pitch=0.6" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
echo "setting set speech#volume=0.9" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Change punctuation level (none/some/most/all)
echo "setting set general#punctuationLevel=all" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
echo "setting set general#punctuationLevel=none" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Voice and TTS engine control
echo "setting set speech#voice=en-us+f3" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
echo "setting set speech#module=espeak-ng" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Disable sound temporarily
echo "setting set sound#enabled=False" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
echo "setting set sound#volume=0.5" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Keyboard and input settings
echo "setting set keyboard#charEchoMode=1" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
echo "setting set keyboard#wordEcho=True" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Screen control (ignore specific TTYs)
echo "setting set screen#ignoreScreen=1,2,3" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Multiple settings at once
echo "setting set speech#rate=0.8;sound#volume=0.7;general#punctuationLevel=most" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Reset all settings to defaults
echo "setting reset" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Save current settings
echo "setting save" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
echo "setting saveas /tmp/my-fenrir-settings.conf" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Place text into clipboard
echo "command clipboard This text will be copied to clipboard" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Export clipboard to file
echo "command exportclipboard" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Define a window area (x1 y1 x2 y2)
echo "command window 0 0 80 24" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Reset window to full screen
echo "command resetwindow" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Set virtual menu context
echo "command vmenu nano/file" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Reset virtual menu
echo "command resetvmenu" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Quit Fenrir
echo "command quitapplication" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
If using the TCP driver, replace socat commands with netcat:
# Using netcat
echo "command say Hello from TCP" | nc localhost 22447
# Using telnet
echo "command interrupt" | telnet localhost 22447
command <action> [parameters]
setting <action> [parameters]
Speech Commands:
command say <text> - Speak the specified textcommand interrupt - Stop current speechcommand tempdisablespeech - Disable speech until next key pressClipboard Commands:
command clipboard <text> - Add text to clipboardcommand exportclipboard - Export clipboard to fileWindow Commands:
command window <x1> <y1> <x2> <y2> - Define window areacommand resetwindow - Reset to full screenVMenu Commands:
command vmenu <menu_path> - Set vmenu contextcommand resetvmenu - Reset vmenuApplication Commands:
command quitapplication - Quit FenrirSettings Commands:
setting set <section>#<key>=<value> - Set configuration valuesetting reset - Reset all settings to defaultssetting save [path] - Save current settingssetting saveas <path> - Save settings to specific fileCommon Settings:
Speech Settings:
speech#enabled=True/False - Enable/disable speechspeech#rate=0.1-1.0 - Speech rate (speed)speech#pitch=0.1-1.0 - Speech pitch (tone)speech#volume=0.1-1.0 - Speech volumespeech#voice=voice_name - Voice selection (e.g., "en-us+f3")speech#module=module_name - TTS module (e.g., "espeak-ng")speech#driver=driver_name - Speech driver (speechdDriver/genericDriver)speech#autoReadIncoming=True/False - Auto-read new textSound Settings:
sound#enabled=True/False - Enable/disable soundsound#volume=0.1-1.0 - Sound volumesound#driver=driver_name - Sound driver (genericDriver/gstreamerDriver)sound#theme=theme_name - Sound themeGeneral Settings:
general#punctuationLevel=none/some/most/all - Punctuation verbositygeneral#debugLevel=0-3 - Debug levelgeneral#emoticons=True/False - Enable emoticon replacementgeneral#autoSpellCheck=True/False - Automatic spell checkingFocus Settings:
focus#cursor=True/False - Follow text cursorfocus#highlight=True/False - Follow text highlightingKeyboard Settings:
keyboard#charEchoMode=0-2 - Character echo (0=none, 1=always, 2=capslock only)keyboard#wordEcho=True/False - Echo complete wordskeyboard#charDeleteEcho=True/False - Echo deleted characterskeyboard#interruptOnKeyPress=True/False - Interrupt speech on key pressScreen Settings:
screen#ignoreScreen=1,2,3 - TTY screens to ignorescreen#autodetectIgnoreScreen=True/False - Auto-detect screens to ignorescreen#screenUpdateDelay=float - Screen update delayTime Settings:
time#enabled=True/False - Enable time announcementstime#presentTime=True/False - Announce timetime#presentDate=True/False - Announce date changestime#delaySec=seconds - Announcement intervaltime#onMinutes=00,30 - Specific minutes to announceFenrir includes advanced table navigation capabilities for working with tabular data in terminal applications, CSV files, and formatted text output.
Table mode is activated through the toggle_highlight_tracking command, which cycles through three focus modes:
Key bindings:
Fenrir + Keypad * (asterisk)Fenrir + YPress the key combination repeatedly to cycle through modes until you hear "table mode enabled".
Keypad 6 - Move to next table columnKeypad 4 - Move to previous table columnFenrir + Keypad 4 - Jump to first column of current rowFenrir + Keypad 6 - Jump to last column of current rowFenrir + L - Move to next table columnFenrir + J - Move to previous table columnFenrir + Shift + J - Jump to first column of current rowFenrir + Shift + L - Jump to last column of current rowFenrir + Keypad 1 (desktop) or Fenrir + Ctrl + J (laptop)Fenrir + Keypad 3 (desktop) or Fenrir + Ctrl + L (laptop)For better navigation experience, you can set column headers:
Fenrir + X to mark the current line as the header rowFenrir automatically detects table structures using multiple strategies:
|), semicolon-separated (;), tab-separatedWhen navigating in table mode, Fenrir announces:
# Working with CSV data
cat data.csv
Name,Age,City
Alice,30,New York
Bob,25,Los Angeles
# 1. Press Fenrir + Keypad * until "table mode enabled"
# 2. Navigate to "Name,Age,City" line
# 3. Press Fenrir + X to set headers
# 4. Use Keypad 4/6 to navigate between columns
# 5. Each cell will be announced with its column header
Fenrir provides intelligent progress bar detection and audio feedback for various progress indicators commonly found in terminal applications.
Command: progress_bar_monitor (no default key binding - assign manually)
To enable progress monitoring:
echo "command progress_bar_monitor" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sockFenrir automatically detects various progress indicator formats:
Download: 45%
Processing: 67.5%
Installing: 100%
Files: 15/100
Progress: 3 of 10
Step 7/15
[#### ] 40%
[====> ] 50%
[**********] 100%
Loading...
Processing...
Working...
Installing...
Downloading...
Compiling...
Building...
# Enable progress monitoring
echo "command progress_bar_monitor" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Common scenarios where progress monitoring is useful:
wget https://example.com/large-file.zip # Download progress
tar -xvf archive.tar.gz # Extraction progress
make -j4 # Compilation progress
pacman -S package # Package installation
rsync -av source/ destination/ # File synchronization
Progress monitoring can be configured through settings:
progressMonitoring=True in sound section#!/bin/bash
# notify_fenrir.sh - Send notifications to Fenrir
SOCKET="/tmp/fenrirscreenreader-deamon.sock"
fenrir_say() {
echo "command say $1" | socat - UNIX-CLIENT:$SOCKET
}
fenrir_interrupt() {
echo "command interrupt" | socat - UNIX-CLIENT:$SOCKET
}
# Usage examples
fenrir_say "Build completed successfully"
fenrir_interrupt
#!/usr/bin/env python3
import socket
import os
def send_fenrir_command(command):
"""Send command to Fenrir via Unix socket"""
socket_path = "/tmp/fenrirscreenreader-deamon.sock"
if os.path.exists(socket_path):
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
try:
sock.connect(socket_path)
sock.send(command.encode('utf-8'))
finally:
sock.close()
# Examples
send_fenrir_command("command say Processing complete")
send_fenrir_command("setting set speech#rate=0.9")
enableSettingsRemote=FalseenableCommandRemote=FalseSocket not found:
ps aux | grep fenrir/tmp/fenrirscreenreader-*Commands not working:
enableCommandRemote=True in settings/var/log/fenrir.logecho "command interrupt" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sockFenrir supports several command-line options for different use cases:
fenrir [OPTIONS]
-h, --help - Show help message and exit-v, --version - Show version information and exit-f, --foreground - Run in foreground (don't daemonize)-s, --setting SETTING-FILE - Path to custom settings file-o, --options SECTION#SETTING=VALUE;.. - Override settings file options-d, --debug - Enable debug mode-p, --print - Print debug messages to screen-e, --emulated-pty - Use PTY emulation with escape sequences for input (enables desktop/X/Wayland usage)-E, --emulated-evdev - Use PTY emulation with evdev for input (single instance)-F, --force-all-screens - Force Fenrir to respond on all screens, ignoring ignoreScreen setting-i, -I, --ignore-screen SCREEN - Ignore specific screen(s). Can be used multiple times. Combines with existing ignore settings.# Run in foreground with debug output
sudo fenrir -f -d
# Use PTY emulation for desktop use
sudo fenrir -e
# Override settings via command line
sudo fenrir -o "speech#rate=0.8;sound#volume=0.5"
# Force Fenrir to work on all screens (ignore ignoreScreen setting)
sudo fenrir -F
# Ignore specific screens
sudo fenrir --ignore-screen 1
sudo fenrir -i 1 -i 2 # Ignore screens 1 and 2
Translation files are located in the locale/ directory. To install translations:
# Copy translation file to system location
sudo cp locale/your_language/LC_MESSAGES/fenrir.mo /usr/share/locale/your_language/LC_MESSAGES/fenrir.mo
Available languages:
Name Last modified Size Description
Parent Directory -
.git/ 2025-12-10 20:34 -
autostart/ 2025-12-10 20:34 -
build/ 2025-12-10 20:34 -
config/ 2025-12-10 20:34 -
docs/ 2025-12-10 20:34 -
locale/ 2025-12-10 20:34 -
src/ 2025-12-10 20:34 -
tests/ 2025-12-10 20:34 -
tools/ 2025-12-10 20:34 -
.gitignore 2025-12-10 20:34 112
CREDITS 2025-12-10 20:34 620
LICENCE 2025-12-10 20:34 7.5K
README.md 2025-12-10 20:34 25K
RELEASE_CHECKLIST.md 2025-12-10 20:34 5.4K
bugs 2025-12-10 20:34 438
check-dependencies.py 2025-12-10 20:34 4.5K
install.sh 2025-12-10 20:34 2.3K
pytest.ini 2025-12-10 20:34 1.8K
requirements.txt 2025-12-10 20:34 87
setup.py 2025-12-10 20:34 4.5K
uninstall.sh 2025-12-10 20:34 596
10 Gbit/s