# Fenrir

A modern, modular, flexible and fast console screen reader for Linux.
This software is licensed under the LGPL v3.

**Current maintainer:** Storm Dragon  
**Previous developer:** Chrys

## Key Features

- **Linux Console Support**: Works as a Linux TTY screen reader, with optional X11 terminal mode
- **Flexible Driver System**: Modular architecture with multiple drivers for speech, sound, input, and screen
- **Review Mode**: Navigate and review screen content without moving the edit cursor
- **Table Navigation**: Advanced table mode with column headers, cell-by-cell navigation, and boundary feedback
- **Progress Bar Monitoring**: Automatic detection and audio feedback for progress indicators with ascending tones
- **Multiple Clipboard Support**: Manage multiple clipboard entries
- **Configurable Key Bindings**: Desktop and laptop keyboard layouts
- **Sound Icons**: Audio feedback for various events
- **Spell Checking**: Built-in spell checker with word management
- **Language Support**: Multiple speech synthesis languages and voices
- **Bookmark System**: Quick access to specific screen areas
- **Auto-announcement**: Automatic reading of incoming text and time announcements
- **Tutorial Mode**: Built-in help system for learning keyboard shortcuts


## Platform Support

Fenrir is a Linux screen reader. Linux is the only officially supported platform.

**Other platforms (macOS, BSD, Windows):** Pull requests adding support for other operating systems may be accepted provided they do not break Linux functionality. However, no special care will be taken to preserve functionality on secondary platforms. If changes to Fenrir break support on a non-Linux OS, it is the responsibility of third-party contributors to submit fixes.

- Linux TTY (`vcsaDriver`, `evdevDriver`) - Full support
- X11 terminal emulators (`-x`, `ptyDriver`, `x11Driver`) - Supported


## Core Requirements

- Python 3 >= 3.9 (recommended 3.13+)
- Screen, input, speech, sound driver dependencies (see "Features, Drivers, Extras" section)
- For full functionality on Linux: evdev, speech-dispatcher, sox


## 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. **x11Driver** - X11 terminal-scoped input driver for `fenrir -x`
   - python-xlib
### 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 screen driver for `fenrir -x`
   - 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.

- Archlinux: PKGBUILD in AUR
  - fenrir: stable release
  - fenrir-git: Bleeding edge release
- Manual:
  - install "espeak" and "sox" with your package manager
  - sudo pip install -r requirements.txt 
  - run install.sh or uninstall.sh as root
- You can also just run it from Git without installing:
Requires root privileges

    cd src/
    sudo ./fenrir

Settings are located in:
- **After installation**: `/etc/fenrir/settings/settings.conf`
- **Development**: `config/settings/settings.conf`

By default Fenrir uses:
- **Sound driver**: genericDriver (via sox)
- **Speech driver**: speechdDriver (via speech-dispatcher) 
- **Input driver**: evdevDriver for Linux TTY, x11Driver for `fenrir -x`
- **Screen driver**: vcsaDriver for Linux TTY, ptyDriver for `fenrir -x`

## 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
```bash
# 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  
```bash
# 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:**
- [configure_pulse.sh](https://git.stormux.org/storm/fenrir/raw/branch/master/tools/configure_pulse.sh)
- [configure_pipewire.sh](https://git.stormux.org/storm/fenrir/raw/branch/master/tools/configure_pipewire.sh)

### Using Installed Scripts

If you have Fenrir installed, the scripts are available at:

**PulseAudio:**
```bash
/usr/share/fenrirscreenreader/tools/configure_pulse.sh
sudo /usr/share/fenrirscreenreader/tools/configure_pulse.sh
```

**PipeWire:**
```bash
/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**:
   ```bash
   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:

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

Configure in `/etc/fenrir/settings/settings.conf`:
```ini
[keyboard]
keyboard_layout=desktop  # or 'laptop'
```

### First Time Setup

1. **Enable Fenrir at boot**:
   ```bash
   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**:
   ```bash
   # 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`:

```ini
[remote]
enable=True
driver=unixDriver              # or tcpDriver
port=22447                     # for TCP driver
socket_file=                   # custom socket path (optional)
enable_settings_remote=True    # allow settings changes
enable_command_remote=True     # allow command execution
```

### Remote Drivers

1. **unixDriver** (recommended): Uses Unix domain sockets
   - Socket location: `/tmp/fenrirscreenreader-deamon.sock` for the standard control socket
   - `fenrir -x` instances also create private sockets: `/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:

#### Instance Discovery
```bash
# List registered Fenrir instances and their socket paths
echo "ls" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
```

In X terminal mode (`fenrir -x`), multiple Fenrir instances can run at the same
time. Each instance has a private socket, 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. Untargeted commands sent through a
shared or broadcast path are claimed by one instance so duplicate instances do
not all perform the same action.

#### Basic Speech Control
```bash
# 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
```bash
# 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#punctuation_level=all" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
echo "setting set general#punctuation_level=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#char_echo_mode=1" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
echo "setting set keyboard#word_echo=True" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock

# Screen control (ignore specific TTYs)
echo "setting set screen#ignore_screen=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#punctuation_level=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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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:

```bash
# 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:**
- `command say <text>` - Speak the specified text
- `command interrupt` - Stop current speech
- `command tempdisablespeech` - Disable speech until next key press

**Clipboard Commands:**
- `command clipboard <text>` - Add text to clipboard
- `command exportclipboard` - Export clipboard to file

**Window Commands:**
- `command window <x1> <y1> <x2> <y2>` - Define window area
- `command resetwindow` - Reset to full screen

**VMenu Commands:**
- `command vmenu <menu_path>` - Set vmenu context
- `command resetvmenu` - Reset vmenu

**Application Commands:**
- `command quitapplication` - Quit Fenrir

**Instance Commands:**
- `ls` / `list` / `command ls` / `command list` - List registered Fenrir instances and their socket paths

#### Available Settings

**Settings Commands:**
- `setting set <section>#<key>=<value>` - Set configuration value
- `setting reset` - Reset all settings to defaults
- `setting save [path]` - Save current settings
- `setting saveas <path>` - Save settings to specific file

**Common Settings:**

*Speech Settings:*
- `speech#enabled=True/False` - Enable/disable speech
- `speech#rate=0.1-1.0` - Speech rate (speed)
- `speech#pitch=0.1-1.0` - Speech pitch (tone)
- `speech#volume=0.1-1.0` - Speech volume
- `speech#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#auto_read_incoming=True/False` - Auto-read new text

*Sound Settings:*
- `sound#enabled=True/False` - Enable/disable sound
- `sound#volume=0.1-1.0` - Sound volume
- `sound#driver=driver_name` - Sound driver (genericDriver/gstreamerDriver)
- `sound#theme=theme_name` - Sound theme

*General Settings:*
- `general#punctuation_level=none/some/most/all` - Punctuation verbosity
- `general#debug_level=0-3` - Debug level
- `general#emoticons=True/False` - Enable emoticon replacement
- `general#auto_spell_check=True/False` - Automatic spell checking

*Focus Settings:*
- `focus#cursor=True/False` - Follow text cursor
- `focus#highlight=True/False` - Follow text highlighting

*Keyboard Settings:*
- `keyboard#char_echo_mode=0-2` - Character echo (0=none, 1=always, 2=capslock only)
- `keyboard#word_echo=True/False` - Echo complete words
- `keyboard#char_delete_echo=True/False` - Echo deleted characters
- `keyboard#interrupt_on_key_press=True/False` - Interrupt speech on key press

*Screen Settings:*
- `screen#ignore_screen=1,2,3` - TTY screens to ignore
- `screen#autodetect_ignore_screen=True/False` - Auto-detect screens to ignore
- `screen#screen_update_delay=float` - Screen update delay

*Time Settings:*
- `time#enabled=True/False` - Enable time announcements
- `time#present_time=True/False` - Announce time
- `time#present_date=True/False` - Announce date changes
- `time#delay_sec=seconds` - Announcement interval
- `time#on_minutes=00,30` - Specific minutes to announce

## 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:**
- **Desktop layout**: `Fenrir + Keypad *` (asterisk)
- **Laptop layout**: `Fenrir + Y`

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

### Table Navigation Commands

#### Column Navigation (Desktop Layout)
- **Next column**: `Keypad 6` - Move to next table column
- **Previous column**: `Keypad 4` - Move to previous table column
- **First column**: `Fenrir + Keypad 4` - Jump to first column of current row
- **Last column**: `Fenrir + Keypad 6` - Jump to last column of current row

#### Column Navigation (Laptop Layout)
- **Next column**: `Fenrir + L` - Move to next table column
- **Previous column**: `Fenrir + J` - Move to previous table column
- **First column**: `Fenrir + Shift + J` - Jump to first column of current row
- **Last column**: `Fenrir + Shift + L` - Jump to last column of current row

#### Cell Character Navigation
- **First character in cell**: `Fenrir + Keypad 1` (desktop) or `Fenrir + Ctrl + J` (laptop)
- **Last character in cell**: `Fenrir + Keypad 3` (desktop) or `Fenrir + Ctrl + L` (laptop)

### 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:
- **Delimited text**: CSV, pipe-separated (`|`), semicolon-separated (`;`), tab-separated
- **Aligned columns**: Space-aligned columns (2+ spaces between columns)
- **Flexible parsing**: Handles various table formats commonly found in terminal applications

### Table Mode Features

- **Cell-by-cell navigation**: Navigate through table cells with precise positioning
- **Column header support**: Set and announce column headers for better context
- **Boundary feedback**: Audio cues when reaching start/end of rows
- **Empty cell handling**: Blank cells are announced as "blank"
- **Independent tracking**: Table position is maintained independently of cursor movement

### Speech Output in Table Mode

When navigating in table mode, Fenrir announces:
- **Cell content** followed by **column header/name**
- **Boundary notifications**: "end of line", "start of line"
- **Position indicators**: "first character in cell [column name]"

### Example Usage

```bash
# 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
- **Ascending tones**: 400Hz to 1200Hz frequency range
- **Percentage mapping**: 0% = 400Hz, 100% = 1200Hz
- **Smooth progression**: Frequency increases proportionally with progress

#### Activity Indicators
- **Steady beep**: 800Hz tone every 2 seconds for ongoing activity
- **Non-intrusive**: Beeps don't interrupt speech or other audio

### Progress Monitoring Features

- **Automatic detection**: No manual configuration required
- **Multiple format support**: Handles various progress indicator styles
- **Prompt awareness**: Automatically pauses when command prompts are detected
- **Non-blocking**: Progress tones don't interrupt speech or other functionality
- **Configurable**: Can be enabled/disabled as needed

### Usage Examples

```bash
# 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:
- **Default enabled**: Set `progress_monitoring=True` in sound section
- **Sound integration**: Works with all sound drivers (sox, gstreamer)
- **Remote control**: Enable/disable through remote commands

### Scripting Examples

#### Bash Script for Speech Notifications
```bash
#!/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
```python
#!/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

- Unix sockets are accessible only to the user running Fenrir
- TCP driver binds only to localhost (127.0.0.1)
- Socket file permissions are set to write-only (0o222)
- Commands are processed with Fenrir's privileges
- Settings changes can be disabled via `enable_settings_remote=False`
- Command execution can be disabled via `enable_command_remote=False`

### Troubleshooting

**Socket not found:**
- Verify Fenrir is running: `ps aux | grep fenrir`
- Check socket location: `/tmp/fenrirscreenreader-*`
- Ensure remote driver is enabled in settings

**Commands not working:**
- Verify `enable_command_remote=True` in settings
- Check Fenrir debug logs: `/var/log/fenrir.log`
- Test with simple command: `echo "command interrupt" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock`

## Command Line Options

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

```
fenrir [OPTIONS]
```

### 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
- `-x, --x11` - Use PTY emulation with X11 keyboard input scoped to the terminal window
- `--x11-window-id WINDOWID` - X11 window id to use for `--x11` terminal mode
- `-F, --force-all-screens` - Force Fenrir to respond on all screens, ignoring ignore_screen setting
- `-i, -I, --ignore-screen SCREEN` - Ignore specific screen(s). Can be used multiple times. Combines with existing ignore settings.

### Examples:
```bash
# Run in foreground with debug output
sudo fenrir -f -d

# Use PTY emulation with X11 terminal-scoped keybindings
fenrir -x

# Use X11 mode with an explicit terminal window id
fenrir -x --x11-window-id 0x123456

# Override settings via command line
sudo fenrir -o "speech#rate=0.8;sound#volume=0.5"

# Force Fenrir to work on all screens (ignore ignore_screen setting)
sudo fenrir -F

# Ignore specific screens
sudo fenrir --ignore-screen 1
sudo fenrir -i 1 -i 2    # Ignore screens 1 and 2
```

### X11 Terminal Mode

`fenrir -x` runs Fenrir inside a GUI terminal without root. It uses the PTY screen driver for terminal contents and the X11 input driver for Fenrir keybindings. Unlike evdev mode, it does not listen to the whole desktop; key grabs are scoped to the target terminal window so desktop screen readers can keep their own global bindings outside that terminal.

By default, Fenrir targets the X11 window from `WINDOWID`, falling back to the active X11 window. If a terminal does not set `WINDOWID`, pass the window explicitly with `--x11-window-id`.

X11 terminal mode uses the normal keyboard layout files, including desktop and laptop bindings. It supports Fenrir keys such as numpad Insert/`KEY_KP0`, CapsLock/`KEY_CAPSLOCK`, Insert/`KEY_INSERT`, and Super/Windows/`KEY_META`. Script keys such as Compose use `KEY_COMPOSE`.

This mode requires `python-xlib`.

For users who want a dedicated PTY/terminal screen reader instead of Fenrir's Linux console focus, see TDSR: https://github.com/tspivey/tdsr

## Localization
Translation files are located in the `locale/` directory. To install translations:

```bash
# 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:
- German (de)
- Spanish (es) 
- Polish (pl)
- Portuguese (pt)
- Russian (ru)

## Documentation and Support

- **Email list**: [stormux+subscribe@groups.io](mailto:stormux+subscribe@groups.io?subject=subscribe) with the subject subscribe
- **Fenrir Wiki**: [https://git.stormux.org/storm/fenrir/wiki](https://git.stormux.org/storm/fenrir/wiki)
- **IRC**: irc.stormux.org #stormux
- **Issues**: Report bugs and feature requests on the project repository
