fenrir/docs/user.md

Fenrir User Manual

Fenrir is a modern command line screen reader written in Python 3.

It has a modular structure, a flexible driver-based architecture, is highly configurable and easy to customize and extend.

Current maintainer: Storm Dragon
Previous developer: Chrys

Quick Start

1. Installation: See the README.md for installation instructions
2. First run: sudo fenrir (or sudo systemctl start fenrir if installed)
3. Tutorial mode: Press Fenrir + H to learn all commands interactively
4. Basic navigation: Use numeric keypad for review (desktop layout)
5. Stop speech: Press Ctrl at any time
6. Quit: Press Fenrir + Q

Key Concepts

Fenrir Key

The Fenrir Key is used to invoke screen reader commands. By default:

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

You can configure multiple Fenrir keys to suit your preference.

Keyboard Layouts

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

Review Mode

Navigate the screen without moving the text cursor. Essential for examining content without disrupting your workflow.

Essential Commands

Navigation (Desktop Layout)

• Ctrl - Stop speech (shut up)
• Fenrir + H - Tutorial mode
• 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

Review Commands

• Keypad 7/9 - Previous/next line
• Keypad 4/6 - Previous/next word
• Keypad 1/3 - Previous/next character
• Fenrir + Keypad dot - Exit review mode

Information

• Fenrir + T - Announce time
• Fenrir + T T - Announce date
• Keypad dot - Cursor position

Clipboard

• Fenrir + X - Set mark
• Fenrir + C - Copy marked text
• Fenrir + V - Paste clipboard
• Fenrir + Shift + C - Read current clipboard

Settings (Runtime Changes)

• Fenrir + F3 - Toggle sound
• Fenrir + F4 - Toggle speech
• Fenrir + Up/Down - Speech volume
• Fenrir + Right/Left - Speech rate
• Fenrir + Ctrl + P - Punctuation level

Configuration

Settings File

Main configuration: /etc/fenrir/settings/settings.conf

Key Sections

• [speech] - Speech synthesis settings
• [sound] - Sound output and icons
• [keyboard] - Input and key bindings
• [screen] - Screen reading configuration
• [general] - General settings

Common Settings

[speech]
enabled=True
driver=speechdDriver
rate=0.5
pitch=0.5
volume=1.0

[sound] 
enabled=True
driver=genericDriver
volume=0.7

[keyboard]
driver=evdevDriver
keyboardLayout=desktop

[screen]
driver=vcsaDriver
ignoreScreen=

[remote]
enable=True
driver=unixDriver
enableSettingsRemote=True
enableCommandRemote=True

Remote Control

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

Configuration

Enable remote control in settings:

[remote]
enable=True
driver=unixDriver              # or tcpDriver  
port=22447                     # for TCP driver
enableSettingsRemote=True      # allow settings changes
enableCommandRemote=True       # allow command execution

Basic Usage with socat

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" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock

# Temporarily disable speech
echo "command tempdisablespeech" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock

Settings Control

# Enable highlight tracking
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

# Voice and TTS 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

# 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
echo "setting reset" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock

# Save settings
echo "setting save" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
echo "setting saveas /tmp/my-settings.conf" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock

Clipboard Operations

# Add text to clipboard
echo "command clipboard Text to copy" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock

# Export clipboard to file
echo "command exportclipboard" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock

Application Control

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

Command Reference

Speech Commands:

• command say <text> - Speak text
• command interrupt - Stop speech
• command tempdisablespeech - Disable until next key

Settings Commands:

• setting set <section>#<key>=<value> - Change setting
• setting reset - Reset to defaults
• setting save - Save current settings

Other Commands:

• command clipboard <text> - Add to clipboard
• command exportclipboard - Export clipboard to file
• command window <x1> <y1> <x2> <y2> - Define window
• command resetwindow - Reset window
• command vmenu <menu_path> - Set virtual menu
• command resetvmenu - Reset virtual menu

Key Settings You Can Change:

• Punctuation level: setting set general#punctuationLevel=all
• Speech parameters: setting set speech#rate=0.8;speech#pitch=0.6
• Voice selection: setting set speech#voice=en-us+f3
• Character echo: setting set keyboard#charEchoMode=1
• Screen ignore: setting set screen#ignoreScreen=1,2,3

Scripting Integration

Bash Helper Function

fenrir_say() {
    echo "command say $1" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
}

# Usage
fenrir_say "Build completed"

Python Integration

import socket
import os

def send_fenrir_command(command):
    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()

send_fenrir_command("command say Process complete")

Advanced Features

Spell Checking

• Fenrir + S - Spell check current word
• Fenrir + S S - Add word to dictionary
• Fenrir + Shift + S - Remove word from dictionary

Bookmarks (1-10)

• Fenrir + Shift + [1-0] - Set bookmark
• Fenrir + [1-0] - Go to bookmark
• Fenrir + Ctrl + [1-0] - Clear bookmark

Multiple Clipboards

• Fenrir + Home/End - First/last clipboard
• Fenrir + PageUp/PageDown - Previous/next clipboard

Window Mode

1. Set marks to define window area
2. Fenrir + Keypad / - Set window
3. Fenrir + Keypad / / - Clear window

Drivers

Speech Drivers

• speechdDriver - Speech-dispatcher (recommended)
• genericDriver - Command-line TTS (espeak, etc.)

Sound Drivers

• genericDriver - Sox-based (default)
• gstreamerDriver - GStreamer-based

Input Drivers

• evdevDriver - Linux evdev (recommended for Linux)
• ptyDriver - Terminal emulation (cross-platform)

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)

Command Line Options

fenrir [OPTIONS]

• -h, --help - Show help
• -v, --version - Show version
• -f, --foreground - Run in foreground
• -s, --setting FILE - Custom settings file
• -o, --options SECTION#SETTING=VALUE;.. - Override settings
• -d, --debug - Enable debug mode
• -p, --print - Print debug to screen
• -e, --emulated-pty - PTY emulation for desktop use
• -E, --emulated-evdev - PTY + evdev emulation
• -F, --force-all-screens - Ignore ignoreScreen setting

Troubleshooting

No Speech

1. Test speech-dispatcher: sudo spd-say "hello"
2. Check driver setting in configuration
3. Verify speech-dispatcher is running

No Sound

1. Run audio configuration script: configure_pulse.sh or configure_pipewire.sh
2. Check sound driver setting
3. Verify sox installation

No Input Response

1. Check permissions: /dev/input/* and /dev/uinput
2. Verify evdev driver setting
3. Run as root for testing

Debug Mode

sudo fenrir -f -d
# Debug output goes to /var/log/fenrir.log

Getting Help

• Tutorial Mode: Fenrir + H (interactive help)
• Wiki: https://git.stormux.org/storm/fenrir/wiki
• Email: stormux+subscribe@groups.io
• IRC: irc.stormux.org #stormux

See Also

• README.md - Installation and basic setup
• settings.conf - Configuration reference
• man fenrir - Manual page