diff --git a/README.md b/README.md index af4f2f42..c2b860a8 100644 --- a/README.md +++ b/README.md @@ -123,9 +123,19 @@ Requires root privileges sudo ./fenrir Settings are located in: -- **After installation**: `/etc/fenrir/settings/settings.conf` +- **System-wide installation**: `/etc/fenrirscreenreader/settings/settings.conf` +- **User-local settings**: `~/.local/share/stormux/fenrirscreenreader/settings/settings.conf` - **Development**: `config/settings/settings.conf` +When Fenrir runs as a regular user, including `fenrir -x`, it loads the +user-local settings file if it exists. If it does not exist, Fenrir falls back +to the system settings file, but saving settings writes to the user-local path. +When Fenrir runs as root, settings save to the system-wide path by default. + +User sound themes are loaded before system themes from +`~/.local/stormux/fenrir/sounds/`. User scripts are loaded before configured +system scripts from `~/.local/stormux/fenrir/`. + By default Fenrir uses: - **Sound driver**: genericDriver (via sox) - **Speech driver**: speechdDriver (via speech-dispatcher) @@ -217,7 +227,8 @@ 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`: +Configure in `/etc/fenrirscreenreader/settings/settings.conf` or your +user-local settings file: ```ini [keyboard] keyboard_layout=desktop # or 'laptop' @@ -246,7 +257,8 @@ Fenrir includes a powerful remote control system that allows external applicatio ### Configuration -Enable remote control in `/etc/fenrir/settings/settings.conf`: +Enable remote control in `/etc/fenrirscreenreader/settings/settings.conf` or +your user-local settings file: ```ini [remote] @@ -758,6 +770,12 @@ By default, Fenrir targets the X11 window from `WINDOWID`, falling back to the a 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`. +In this mode Fenrir runs as a regular user. Settings are loaded from +`~/.local/share/stormux/fenrirscreenreader/settings/settings.conf` when present, +otherwise from `/etc/fenrirscreenreader/settings/settings.conf`; saving settings +creates or updates the user-local file. User sound themes and scripts are read +first from `~/.local/stormux/fenrir/sounds/` and `~/.local/stormux/fenrir/`. + 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 diff --git a/config/keyboard/Readme.md b/config/keyboard/Readme.md index 67aab55d..7b66e8d9 100644 --- a/config/keyboard/Readme.md +++ b/config/keyboard/Readme.md @@ -28,11 +28,13 @@ This directory contains keyboard layout files for Fenrir screen reader. ## Configuration -To change keyboard layout, edit `/etc/fenrir/settings/settings.conf`: +To change keyboard layout, edit `/etc/fenrirscreenreader/settings/settings.conf` +or your user-local settings file at +`~/.local/share/stormux/fenrirscreenreader/settings/settings.conf`: ```ini [keyboard] -keyboardLayout=desktop # or laptop +keyboard_layout=desktop # or laptop ``` ## Available Key Constants diff --git a/docs/fenrir.1 b/docs/fenrir.1 index 6bed6ca2..bf15df00 100644 --- a/docs/fenrir.1 +++ b/docs/fenrir.1 @@ -17,6 +17,8 @@ fenrir \- A modern, modular console screen reader for Linux .RB [ \-\-x11-window-id .IR WINDOWID ] .RB [ \-F ] +.RB [ \-i +.IR SCREEN ] .SH DESCRIPTION Fenrir is a modern, modular, flexible and fast console screen reader written in Python 3. @@ -39,7 +41,7 @@ Run Fenrir in the foreground instead of as a daemon. Useful for debugging and te .TP .BR \-s ", " \-\-setting " " \fISETTING-FILE\fR -Path to a custom settings file. Default is /etc/fenrir/settings/settings.conf. +Path to a custom settings file. Default is /etc/fenrirscreenreader/settings/settings.conf for root and ~/.local/share/stormux/fenrirscreenreader/settings/settings.conf for regular-user saves. .TP .BR \-o ", " \-\-options " " \fISECTION#SETTING=VALUE;..\fR @@ -56,11 +58,19 @@ Print debug messages to screen in addition to logging them. .TP .BR \-F ", " \-\-force-all-screens -Force Fenrir to respond on all screens, ignoring the ignoreScreen setting. This temporarily overrides screen filtering for the current session. +Force Fenrir to respond on all screens, ignoring the ignore_screen setting. This temporarily overrides screen filtering for the current session. .TP .BR \-i ", " \-I ", " \-\-ignore-screen " \fISCREEN\fR" -Ignore specific screen(s). Can be used multiple times to ignore multiple screens. This is equivalent to setting ignoreScreen in the configuration file and will be combined with any existing ignore settings. +Ignore specific screen(s). Can be used multiple times to ignore multiple screens. This is equivalent to setting ignore_screen in the configuration file and will be combined with any existing ignore settings. + +.TP +.BR \-x ", " \-\-x11 +Run in X11 terminal mode using PTY screen monitoring and X11 keyboard input scoped to the terminal window. + +.TP +.BR \-\-x11-window-id " " \fIWINDOWID\fR +Use a specific X11 terminal window id for X11 terminal mode. .SH KEY CONCEPTS @@ -179,12 +189,24 @@ Announce marked text .SS Settings File The main configuration file is located at: .IP \[bu] 2 -.B /etc/fenrir/settings/settings.conf +.B /etc/fenrirscreenreader/settings/settings.conf (system-wide installation) .IP \[bu] 2 +.B ~/.local/share/stormux/fenrirscreenreader/settings/settings.conf +(user-local settings) +.IP \[bu] 2 .B config/settings/settings.conf (development/git version) +When Fenrir runs as a regular user, including fenrir -x, it loads the +user-local settings file if it exists. If it does not exist, Fenrir falls back +to the system settings file, but saving settings writes to the user-local path. +When Fenrir runs as root, settings save to the system-wide path by default. + +User sound themes are loaded before system themes from +~/.local/stormux/fenrir/sounds/. User scripts are loaded before configured +system scripts from ~/.local/stormux/fenrir/. + .SS Key Sections .TP .B [speech] @@ -264,7 +286,7 @@ Override speech rate and sound volume settings. .TP .B fenrir -F -Force Fenrir to work on all screens, ignoring ignoreScreen settings. +Force Fenrir to work on all screens, ignoring ignore_screen settings. .TP .B fenrir -s /home/user/my-fenrir.conf @@ -275,14 +297,14 @@ Use a custom configuration file. Fenrir includes a powerful remote control system for automation and integration with external applications. .SS Configuration -Enable remote control in /etc/fenrir/settings/settings.conf: +Enable remote control in /etc/fenrirscreenreader/settings/settings.conf or the user-local settings file: .EX [remote] enable=True driver=unixDriver -enableSettingsRemote=True -enableCommandRemote=True +enable_settings_remote=True +enable_command_remote=True .EE .SS Using socat with Unix Sockets @@ -323,13 +345,13 @@ echo "setting set focus#highlight=True" | socat - UNIX-CLIENT:/tmp/fenrirscreenr echo "setting set speech#rate=0.8" | 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#punctuation_level=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 # 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 +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 echo "setting reset" | socat - UNIX-CLIENT:/tmp/fenrirscreenreader-deamon.sock @@ -387,7 +409,7 @@ command quitapplication - Quit Fenrir .TP .B Speech Control: .IP \[bu] 2 -general#punctuationLevel=none/some/most/all - Punctuation verbosity +general#punctuation_level=none/some/most/all - Punctuation verbosity .IP \[bu] 2 speech#rate=0.1-1.0 - Speech rate .IP \[bu] 2 @@ -402,28 +424,32 @@ speech#module=module_name - TTS module .TP .B Screen Control: .IP \[bu] 2 -screen#ignoreScreen=1,2,3 - TTY screens to ignore +screen#ignore_screen=1,2,3 - TTY screens to ignore .IP \[bu] 2 focus#highlight=True/False - Follow text highlighting .TP .B Input Control: .IP \[bu] 2 -keyboard#charEchoMode=0-2 - Character echo mode +keyboard#char_echo_mode=0-2 - Character echo mode .IP \[bu] 2 -keyboard#wordEcho=True/False - Word echo +keyboard#word_echo=True/False - Word echo .SH FILES .TP -.B /etc/fenrir/settings/settings.conf +.B /etc/fenrirscreenreader/settings/settings.conf Main configuration file .TP -.B /etc/fenrir/keyboard/ +.B ~/.local/share/stormux/fenrirscreenreader/settings/settings.conf +User-local configuration file + +.TP +.B /etc/fenrirscreenreader/keyboard/ Keyboard layout definitions .TP -.B /etc/fenrir/punctuation/ +.B /etc/fenrirscreenreader/punctuation/ Punctuation level definitions .TP @@ -431,9 +457,13 @@ Punctuation level definitions System sound themes .TP -.B ~/.local/share/fenrirscreenreader/sounds/ +.B ~/.local/stormux/fenrir/sounds/ User sound themes +.TP +.B ~/.local/stormux/fenrir/ +User scripts + .TP .B /var/log/fenrir.log Debug log file diff --git a/docs/fenrir.adoc b/docs/fenrir.adoc index 44ba51ac..99d0de91 100644 --- a/docs/fenrir.adoc +++ b/docs/fenrir.adoc @@ -27,9 +27,12 @@ and voices provided by Speech Dispatcher. + Keyboard shortcuts are bound to commands to read the screen, review it and perform other actions like modify the settings on the fly, switch languages, copy and paste text, provide miscellaneous information. + -=== Configuration file === The permanent settings are recorded in the -configuration file /etc/fenrirscreenreader/settings.conf, that is -heavily commented. + +=== Configuration file === The system-wide settings are recorded in the +configuration file /etc/fenrirscreenreader/settings/settings.conf, that is +heavily commented. Regular-user sessions, including `+fenrir -x+`, load +`+~/.local/share/stormux/fenrirscreenreader/settings/settings.conf+` when it +exists, otherwise they fall back to the system settings file. Saving settings +as a regular user creates or updates the user-local file. + These settings are described in this user guide. To start Fenrir once type as root: @@ -1215,10 +1218,10 @@ Enable debug mode. Debug information will be logged. Print debug messages to screen in addition to logging them. `+-F, --force-all-screens+`:: -Force Fenrir to respond on all screens, ignoring the ignoreScreen setting. This temporarily overrides screen filtering for the current session. +Force Fenrir to respond on all screens, ignoring the ignore_screen setting. This temporarily overrides screen filtering for the current session. `+-i, -I, --ignore-screen +`:: -Ignore specific screen(s). Can be used multiple times to ignore multiple screens. This is equivalent to setting ignoreScreen in the configuration file and will be combined with any existing ignore settings. +Ignore specific screen(s). Can be used multiple times to ignore multiple screens. This is equivalent to setting ignore_screen in the configuration file and will be combined with any existing ignore settings. ==== Set settings options @@ -1483,6 +1486,8 @@ By default we ship two sound packs. . `+default-wav+` wav encoded, just for compatibility Sound packs are located at /usr/share/sounds/fenrirscreenreader/ +User sound packs in `+~/.local/stormux/fenrir/sounds/+` are loaded before +system sound packs. Sound volume controls how loud the sounds for your selected sound pack are. @@ -1789,7 +1794,7 @@ keyboard_layout=desktop .... Values: An absolute Path to a Keyboard definition file or a Filename -without extension located in `+/etc/fenrir/keyboard+` +without extension located in `+/etc/fenrirscreenreader/keyboard+` Announce characters while typing. @@ -1857,7 +1862,7 @@ the current punctuation and dict file in use: punctuation_profile=default .... -Values: Text, see available profiles in `+/etc/fenrir/punctuation+` or +Values: Text, see available profiles in `+/etc/fenrirscreenreader/punctuation+` or in `+sourceTree/config/punctuation+` The current punctuation level in use: @@ -1963,19 +1968,20 @@ Values: Text, see aspell dictionary's. Folder Path for your scripts "scriptKey" functionality: .... -scriptPath=/usr/share/fenrirscreenreader/scripts +script_path=/usr/share/fenrirscreenreader/scripts .... -Values: Text, Existing path on file system. +Values: Text, Existing path on file system. User scripts in +`+~/.local/stormux/fenrir/+` are loaded before this configured path. Override commands or create new ones without changing the Fenrir defaults: .... -commandPath=/usr/share/fenrirscreenreader/commands +command_path=/usr/share/fenrirscreenreader/commands .... -Values: Text, Existing path on file system. Subfolders in commandPath +Values: Text, Existing path on file system. Subfolders in command_path are: * `+commands+` = to create shortcut commands @@ -2111,14 +2117,15 @@ Values: on=`+True+`, off=`+False+` === Scripting Scripts can be in any language, bash, python, sh or others. Place your -scripts in the directory /usr/share/fenrirscreenreader/scripts/ (the -path is configurable in settings.conf). The script key is the +personal scripts in `+~/.local/stormux/fenrir/+`, or place system scripts in +the directory /usr/share/fenrirscreenreader/scripts/ (the path is configurable +in settings.conf). The script key is the applications key. Usually this key can be found on the keyboard located just left of the right most control key. When you name a script, the key name appears in the script seperated by the sequence [.underline]#-#. So, for example, if you have a python weather script you want assigned to the script key plus the letter w you would name the script -/usr/share/fenrirscreenreader/scripts/weather[.underline]##-##key_w.py +~/.local/stormux/fenrir/weather[.underline]##-##key_w.py Then, to access the script, simply press the script key and the letter w. Scripts must be executable. So, make sure to chmod 755 your script when you place it in the scripts directory. The script gets some diff --git a/docs/user.md b/docs/user.md index fc1723d4..f3144d74 100644 --- a/docs/user.md +++ b/docs/user.md @@ -77,7 +77,13 @@ Navigate the screen without moving the text cursor. Essential for examining cont ## Configuration ### Settings File -Main configuration: `/etc/fenrir/settings/settings.conf` +Main configuration: +- **System-wide**: `/etc/fenrirscreenreader/settings/settings.conf` +- **User-local**: `~/.local/share/stormux/fenrirscreenreader/settings/settings.conf` + +When Fenrir runs as a regular user, including `fenrir -x`, it loads the user-local settings file if it exists. If it does not exist, Fenrir falls back to the system settings file, but saving settings creates or updates the user-local file. When Fenrir runs as root, settings save to the system-wide file by default. + +User sound themes are loaded before system themes from `~/.local/stormux/fenrir/sounds/`. User scripts are loaded before configured system scripts from `~/.local/stormux/fenrir/`. ### Key Sections - `[speech]` - Speech synthesis settings @@ -356,7 +362,7 @@ fenrir [OPTIONS] - `-p, --print` - Print debug to screen - `-x, --x11` - PTY + 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` - Ignore ignoreScreen setting +- `-F, --force-all-screens` - Ignore ignore_screen setting - `-i, -I, --ignore-screen SCREEN` - Ignore specific screen(s), can be used multiple times ### X11 Terminal Mode @@ -377,6 +383,8 @@ fenrir -x --x11-window-id 0x123456 X11 terminal mode uses the same keyboard layout files as TTY Fenrir. Supported Fenrir keys include numpad Insert/`KEY_KP0`, CapsLock/`KEY_CAPSLOCK`, Insert/`KEY_INSERT`, and Super/Windows/`KEY_META`. Compose script keys are exposed as `KEY_COMPOSE`. +In this mode Fenrir runs as a regular user. Settings are loaded from `~/.local/share/stormux/fenrirscreenreader/settings/settings.conf` when present, otherwise from `/etc/fenrirscreenreader/settings/settings.conf`; saving settings creates or updates the user-local file. User sound themes and scripts are read first from `~/.local/stormux/fenrir/sounds/` and `~/.local/stormux/fenrir/`. + This mode requires `python-xlib`. For a dedicated PTY/terminal screen reader, see TDSR: https://github.com/tspivey/tdsr diff --git a/src/fenrirscreenreader/fenrirVersion.py b/src/fenrirscreenreader/fenrirVersion.py index c78f44fd..3d1a410e 100644 --- a/src/fenrirscreenreader/fenrirVersion.py +++ b/src/fenrirscreenreader/fenrirVersion.py @@ -5,4 +5,4 @@ # By Chrys, Storm Dragon, and contributors. version = "2026.05.12" -code_name = "master" +code_name = "testing"