storm/fenrir
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
fenrir/docs/user.md

335 lines
9.4 KiB
Markdown
Raw Blame History

# 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](../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
```ini
[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:
```ini
[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
```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" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
# Temporarily disable speech
echo "command tempdisablespeech" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
```
#### Settings Control
```bash
# 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
```bash
# 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
```bash
# 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
```bash
fenrir_say() {
echo "command say $1" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock
}
# Usage
fenrir_say "Build completed"
```
#### Python Integration
```python
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
```bash
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](../README.md) - Installation and basic setup
- [settings.conf](../config/settings/settings.conf) - Configuration reference
- `man fenrir` - Manual page
Reference in New Issue View Git Blame Copy Permalink