Patronage & Donations
If you use the Slackware UK services on a regular basis, and would like to contribute to running costs, make a continuing patronage (and receive special benefits), or make a one off PayPal payment, please use one of the following buttons:
Patreon Logo
For regular monthly donations
PayPal Logo
For one time donations
All donations will be gratefully received - thank you!
Toggle theme:Toggle Theme Button
Content of directory's README.md

Fenrir

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

Key Features

OS Requirements

Core Requirements

Features, Drivers, Extras, Dependencies

Input Drivers:

  1. evdevDriver - Linux evdev input driver (recommended for Linux)
    • python-evdev >=0.6.3 (This is commonly referred to as python3-evdev by your distribution)
    • python-pyudev
    • loaded uinput kernel module
    • ReadWrite permission:
      • /dev/input
      • /dev/uinput
  2. ptyDriver - Terminal emulation input driver (cross-platform)
    • python-pyte
  3. atspiDriver - AT-SPI input driver for desktop environments
    • python-pyatspi2

Remote Drivers:

  1. unixDriver - Unix socket remote control (default)
    • socat (for command-line interaction)
  2. tcpDriver - TCP socket remote control (localhost only)
    • netcat or telnet (for command-line interaction)

Screen Drivers:

  1. vcsaDriver - Linux VCSA devices driver (recommended for Linux TTY)
    • python-dbus
    • Read permission to the following files and services:
      • /sys/devices/virtual/tty/tty0/active
      • /dev/tty[1-64]
      • /dev/vcsa[1-64]
      • read logind DBUS
  2. ptyDriver - Terminal emulation driver (cross-platform)
    • python-pyte

Speech Drivers:

  1. speechdDriver - Speech-dispatcher driver (recommended)
    • Speech-dispatcher
    • python-speechd
  2. genericDriver - Generic subprocess speech driver
    • espeak or espeak-ng (or any TTS command)
  3. debugDriver - Debug speech driver for testing
    • No dependencies

Sound Drivers:

  1. genericDriver (default) - Generic subprocess sound driver
    • Sox with opus support (recommended)
  2. gstreamerDriver - GStreamer sound driver
    • gstreamer >=1.0
    • GLib
  3. debugDriver - Debug sound driver for testing
    • No dependencies

Extras:

  1. spellchecker
    • python-pyenchant
    • aspell-YourLanguageCode (example aspell-en for us English)
  2. Unix daemon (also needed for Systemd):
    • python-daemonize
  3. Modify system volume:
    • pyalsaaudio (needs libasound2's headers).

installation

If there is a package for your distrobution of choice, please let us know so we can add it here.

Settings are located in:

By default Fenrir uses:

Audio Configuration

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.

Quick Setup - Direct Script Download

For non-Fenrir users or quick setup, download and run these scripts directly:

PulseAudio Configuration

# 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

PipeWire Configuration

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

Using Installed Scripts

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.

Getting Started

Basic Usage

  1. Start Fenrir:

    sudo systemctl start fenrir  # If installed as service
    # OR
    sudo fenrir                  # Run directly
  2. Basic Navigation:

    • Fenrir Key: By default Insert, Keypad Insert, or Meta/Super key
    • Tutorial Mode: Fenrir + H to learn all commands interactively
    • Quit Fenrir: Fenrir + Q
  3. Essential Commands:

    • Ctrl - Stop speech (shut up)
    • Fenrir + Keypad 5 - Read current screen
    • Keypad 8 - Read current line
    • Keypad 5 - Read current word
    • Keypad 2 - Read current character
    • Fenrir + T - Announce time
    • Fenrir + S - Spell check current word
    • Fenrir + Keypad * - Toggle table mode / highlight tracking

Keyboard Layouts

Fenrir supports two main keyboard layouts:

Configure in /etc/fenrir/settings/settings.conf:

[keyboard]
keyboardLayout=desktop  # or 'laptop'

First Time Setup

  1. Enable Fenrir at boot:

    sudo systemctl enable fenrir
  2. Configure audio (if needed):

    • For PulseAudio: Run configure_pulse.sh script (see below)
    • For PipeWire: Run configure_pipewire.sh script (see below)
  3. Test speech:

    # Test speech-dispatcher directly
    sudo spd-say "Hello World"

Remote Control

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.

Configuration

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

Remote Drivers

  1. unixDriver (recommended): Uses Unix domain sockets

    • Socket location: /tmp/fenrirscreenreader-deamon.sock (TTY mode) or /tmp/fenrirscreenreader-<pid>.sock
    • More secure, local-only access
    • Works with socat
  2. tcpDriver: Uses TCP sockets on localhost

    • Default port: 22447
    • Works with netcat, telnet, or any TCP client
    • Local connections only (127.0.0.1)

Using socat with Unix Sockets

The socat command provides the easiest way to send commands to Fenrir:

Basic Speech Control

# 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

Settings Control

# 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

Clipboard Operations

# 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

Window Management

# 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

VMenu Control

# 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

Application Control

# Quit Fenrir
echo "command quitapplication" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock

Using TCP Driver

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

Remote Command Reference

Command Format

command <action> [parameters]
setting <action> [parameters]

Available Commands

Speech Commands:

Clipboard Commands:

Window Commands:

VMenu Commands:

Application Commands:

Available Settings

Settings Commands:

Common Settings:

Speech Settings:

Sound Settings:

General Settings:

Focus Settings:

Keyboard Settings:

Screen Settings:

Time Settings:

Table Navigation

Fenrir includes advanced table navigation capabilities for working with tabular data in terminal applications, CSV files, and formatted text output.

Entering Table Mode

Table mode is activated through the toggle_highlight_tracking command, which cycles through three focus modes:

  1. Highlight tracking mode (default) - Follows text highlighting
  2. Cursor tracking mode - Follows text cursor movement
  3. Table mode - Enables table navigation

Key bindings:

Press the key combination repeatedly to cycle through modes until you hear "table mode enabled".

Table Navigation Commands

Column Navigation (Desktop Layout)

Column Navigation (Laptop Layout)

Cell Character Navigation

Setting Column Headers

For better navigation experience, you can set column headers:

  1. Navigate to header row: Use normal navigation to reach the row containing column headers
  2. Set headers: Press Fenrir + X to mark the current line as the header row
  3. Navigation feedback: Column headers will be announced along with cell content

Table Detection

Fenrir automatically detects table structures using multiple strategies:

Table Mode Features

Speech Output in Table Mode

When navigating in table mode, Fenrir announces:

Example Usage

# 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

Progress Bar Monitoring

Fenrir provides intelligent progress bar detection and audio feedback for various progress indicators commonly found in terminal applications.

Enabling Progress Monitoring

Command: progress_bar_monitor (no default key binding - assign manually)

To enable progress monitoring:

  1. Add a key binding in your keyboard layout file
  2. Or use the remote control system: echo "command progress_bar_monitor" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock

Progress Detection Patterns

Fenrir automatically detects various progress indicator formats:

1. Percentage Progress

Download: 45%
Processing: 67.5%
Installing: 100%

2. Fraction Progress

Files: 15/100
Progress: 3 of 10
Step 7/15

3. Progress Bars

[####      ] 40%
[====>     ] 50%
[**********] 100%

4. Activity Indicators

Loading...
Processing...
Working...
Installing...
Downloading...
Compiling...
Building...

Audio Feedback

Progress Tones

Activity Indicators

Progress Monitoring Features

Usage Examples

# 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

Customization

Progress monitoring can be configured through settings:

Scripting Examples

Bash Script for Speech Notifications

#!/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

Python Integration

#!/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")

Security Considerations

Troubleshooting

Socket not found:

Commands not working:

Command Line Options

Fenrir supports several command-line options for different use cases:

fenrir [OPTIONS]

Options:

Examples:

# 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

Localization

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:

Documentation and Support


Icon  Name                                        Last modified      Size  Description
[<--] Parent Directory - [DIR] .git/ 2025-12-10 20:34 - [DIR] autostart/ 2025-12-10 20:34 - [DIR] build/ 2025-12-10 20:34 - [DIR] config/ 2025-12-10 20:34 - [DIR] docs/ 2025-12-10 20:34 - [DIR] locale/ 2025-12-10 20:34 - [DIR] src/ 2025-12-10 20:34 - [DIR] tests/ 2025-12-10 20:34 - [DIR] tools/ 2025-12-10 20:34 - [   ] .gitignore 2025-12-10 20:34 112 [TXT] CREDITS 2025-12-10 20:34 620 [TXT] LICENCE 2025-12-10 20:34 7.5K [TXT] README.md 2025-12-10 20:34 25K [TXT] RELEASE_CHECKLIST.md 2025-12-10 20:34 5.4K [TXT] bugs 2025-12-10 20:34 438 [SPT] check-dependencies.py 2025-12-10 20:34 4.5K [SPT] install.sh 2025-12-10 20:34 2.3K [   ] pytest.ini 2025-12-10 20:34 1.8K [TXT] requirements.txt 2025-12-10 20:34 87 [SPT] setup.py 2025-12-10 20:34 4.5K [SPT] uninstall.sh 2025-12-10 20:34 596
Server (facade0) bandwidth utilisation
0  Bandwidth graph measuring   0.03 Gbit/s  10 Gbit/s