[FEAT] Screenreader support

[travis-jeans]

Is your feature request related to a problem? Please describe.
If I try use Orca Screenreader the window does not read anything or give feedback on key presses. Besides, shortcuts for use with Orca like jump to heading "h", conflict with existing keybindings.

Describe the solution you'd like
The ability for a screenreader to read the contents of the app would be useful. For instance, when pressing the down arrow key to go down the list, I would expect the title of the radio station the user has chosen would be read out - additionally, an option for the current song playing to be voiced out or the ability to access it through the app somehow. Same goes for when accessing options menus or other parts of the app, whatever text changes like prompts to change the volume and volume percent should be read out as well.

Describe alternatives you've considered
The main thing is I really love this app, so far it's my favorite for radio stations. I haven't tried other radio stations app that might have screenreader support mixed in, so I could do that. But I also think it would be worthwhile making improvements to this app so it can appeal to a larger audience.

Additional context
To start I would recommend reviewing:

• Keyboard (WCAG criteria) functionality requiring access by text-to-speech software.
• Character Keys (WCAG) has information about remapping letter or punctuation key shortcuts to those utilising Ctrl or Alt (that wouldn't interfere with screenreader bindings).

I realize something like adding accessibility support is maybe not on the top of the priority list, so I've added it as a feature request. I think for simplicity, starting with the key bindings would be a good first step since other users have requested it as well.

[s-n-g]

This is very interesting!

I have looked into it a bit and it seems orca will not work with PyRadio.
orca works with a gui program, PyRadio is a tui program, and that's why it does not work as you have already experienced it.

The only way to have some kind of sound message from PyRadio is to use a tts engine directly.
This way, selecting a station will speak "Station: whatever", when a station starts playing it will speak "Playing (station) whatever), or even "Title: whatever"

This would be ideal

Can you please try the file attached here?
It will try to speak the text you type

On linux it will try spd-say, espeak, festival in that order
On wildows, it works using either pyttsx3 or a powershell workaround (if that's not there)
On macOS, it will use say

tts_tool.py

[s-n-g]

BTW, Pyradio already has a way to customize its key bindings, youcan have a look and tell me if that would be adequate?

You can get to it by typing "c" and then go to "Keyboard Shortcuts" / "Shortcuts" at the end of the list

[travis-jeans]

This is very interesting!

I have looked into it a bit and it seems orca will not work with PyRadio. orca works with a gui program, PyRadio is a tui program, and that's why it does not work as you have already experienced it.

The only way to have some kind of sound message from PyRadio is to use a tts engine directly. This way, selecting a station will speak "Station: whatever", when a station starts playing it will speak "Playing (station) whatever), or even "Title: whatever"

This would be ideal

Can you please try the file attached here? It will try to speak the text you type

On linux it will try spd-say, espeak, festival in that order On wildows, it works using either pyttsx3 or a powershell workaround (if that's not there) On macOS, it will use say

tts_tool.py

The tts_tool.py works for me (on a separate command line).

Output:

Initializing TTS for Linux...
Platform: Linux 6.12.27-amd64
Linux: Using spd-say

Cross-Platform Text-to-Speech Tool - Real TTS Engines

Type text to speak it, or 'help' for commands
Press Ctrl+C to exit

Ready! Platform: Linux, Method: spd-say

Enter text to speak: pyradio test
Speaking: 'pyradio test'
Method: spd-say

Enter text to speak: Speech completed
testing
Speaking: 'testing'
Method: spd-say

Enter text to speak: Speech completed

BTW, Pyradio already has a way to customize its key bindings, youcan have a look and tell me if that would be adequate?

You can get to it by typing "c" and then go to "Keyboard Shortcuts" / "Shortcuts" at the end of the list

I tried changing the keybindings in the app but encountered some problems when trying to add Ctrl to the shortcut keys. First thing is that it holding the Ctrl key seems to correspond to making the character a capital, so Ctrl+h and capital H are considered the same. Shift+Ctrl+h is interpreted as Ctrl+h or Ctrl+H. The modifier key (windows key between Ctrl and Alt on my keyboard) doesn't seem to work, neither does the Alt key.

Output:

Shortcut Conflict
The following entries have a shortcut conflict.
Conflicting shortcut: "^G"

Group: Movement Keys
Go to end of list
Group: Main Window keys
Opens groups window

Please insert a different shortcut!

Tip: Press "0" to switch between the conflicting items. When not in editing mode, you can press "f" to see the free keys you can use.

Press any key...

[OK] [Cancel]

An example with "Ctrl+h" interpreted as "^H".

The free list of keys:

When trying to change the volume from + to Ctrl++, it interprets it to be =:

Free Keys
The following Keys are free to be used as Shortcut Keys:

Digits: 1 2 3 4 5 6 7 8 9
Leters: D F K Q U f j k
F-Keys: F1 F2 F3 F4 F5 F6
Punct: ! " $ % & ( ) : ; @ ^  ` }

Press any key...

Another issue I had is when trying to change the keyboard shortcut for Go to top of list, pressing the Ctrl+g key while in the input menu (when the shortcut is already g) will leave the shortcut edit input and go to the top of the list, consequently not changing the keybinding.

Some of the shortcuts I changed to use the Ctrl key.

Output:

PyRadio 0.9.3.11.19 (github pyradio link)
Keyboard Shortcuts
Actions, Default, User, New
Movement Keys
Go down Default j New ^J
Go up Default k New ^K
Go left Default h New ^H
Go right Default l New ^L

Other ideas

What might be convenient for users wanting to have Ctrl and Alt as modifier keys would be to have a preset available to swap all bindings at once. Ideally, either replacing a configuration file in a config folder or loading a file via the app could be ways of doing it considering there are a lot of keybindings.

[s-n-g]

Hi @travis-jeans

It took me a while to get back to you, been busy and then started reading about tts and such.
Sorry about that

I have managed to install piper tts on my manjaro box and I have been testing it with pyradio.
I have a first and very simple implementation
Can you please test it?

Download: https://github.com/s-n-g/pyradio/archive/refs/heads/tts.zip and unpack it
In its top directory execute

./devel/build_install_pyradio

And execute

~/.local/bin/pyradio

This will use spd-say to say the name of the selected station as you navigate through them
Let's make sure this works for you and it is acceptable before we start dealing with the keyboard issues.

Can you please provide more info on your tts setup?
module, voice, etc
This has nothing to do with our test, I just wan to get a sense of a real world tts engine setup.
Also, what system are you on?

[travis-jeans]

This will use spd-say to say the name of the selected station as you navigate through them

It works. If I can give some feedback:

• hearing "selected station" before every station name while browsing the list is redundant, maybe it would be better for it only to say selected station once the station is selected to play
• the numbers in the list aren't read out and I think they should be (as they appear to be in a list)
• if moving quickly between selections (to go down the list), the selection highlight will lag for several seconds after maybe 3-4 down arrow movements

I'm using Linux (Debian 13 XFCE). I use Orca, using the default voice (default setting when installed except for changes to speed). Years ago I had set another voice installed from RHVoice since the voice sounded more natural, but I couldn't figure out how to install it again. In general, people usually use the default voice for a lot of screenreaders.

For Windows, NVDA and Jaws are the most popular. According the WebAIM Screen Reader Survey 2024, only 2.4% of users use Orca. Hope this helps.

[s-n-g]

Hi @travis-jeans,

I have just released v0.9.3.11.21 with the latest TTS changes.

You can read about it here:
https://github.com/coderholic/pyradio/blob/master/docs/tts.md

Any feedback is welcome!

Regarding the keyboard customization issue:
This is somewhat tricky due to how terminals handle input:

• Ctrl combinations are relatively easy to capture, though note that Ctrl-h and Ctrl-H (Shift + Ctrl-h) are often interpreted as the same.

• Alt combinations are more challenging to detect reliably.

• Other combinations (like Ctrl-Shift, Alt-Shift, Alt-Ctrl-Shift, Super/Win, etc.) are much harder — and in some cases impossible — to capture consistently across different terminals.

I'll look into what can be improved regarding Alt key support, but there are inherent limitations with terminal-based applications.

[travis-jeans]

Sounds fantastic, thank you. I greatly appreciate the documentation as well. I'm looking forward to testing it.

I haven't gotten the update notification on my pyradio version yet (might have changed how it works since I installed the tts on it?), but hopefully I'll get an update prompt soon. Is it possible the version you sent me to try with the tts is affecting how often it checks for updates?

[s-n-g]

There is no change to the update notification functionality; the program checks every 10 days.

In order to manually update, execute:

pyradio -U 

[travis-jeans]

Thanks, that updated it.

I really like the update! The performance issue with the lag moving down the list is completely gone and the TTS says the numbers and the stations. The metadata update also works well for the stations I've tried which do that, it helps me remember the songs I listen to.

Other than having the TTS read out the help menu and other menus and give feedback for settings / etc, here are a few ideas for extra settings for the TTS config options:

• verbosity toggle for "read all" or "only read metadata updates" - I can imagine a scenario where someone would want TTS for everything versus someone who might only want an "announcer" metadata feature.
• speech speed setting: those who use screen readers usually have it set to a certain speed due to auditory processing - some with a lot of experience have it very fast, others might have it very slow if they're not used to. I think a slider (a bit like the volume adjuster) to set a percent value could be very helpful.

If you want any more feedback on WIPs let me know, I'm happy to help.

Thanks again for providing this feature, I'm enjoying using it. If I think of any more feedback to give once I have more time to use the app with TTS on I'll post in here again or make a new thread.

[s-n-g]

I am really glad you like the update!

Your feedback is valuable and your ideas are excellent!

Sure, i will add the rate setting and maybe the pitch? Would that be useful?

Regarding the verbosity toggle:

I am currently trying to enable the various messages one gets when performing several actions, like the confirmation window one gets when one tries to delete a station, for example. Do you think this should be on when verbosity is on only?

Or just leave the help screens and field names to it?

[travis-jeans]

Sure, i will add the rate setting and maybe the pitch? Would that be useful?

Rate, Pitch, and Volume have slider adjustments in NVDA and Orca so I'd say they would be useful additions to the settings. Refs: NVDA Voice Settings (User Guide), Orca Voice Preferences

I am currently trying to enable the various messages one gets when performing several actions, like the confirmation window one gets when one tries to delete a station, for example. Do you think this should be on when verbosity is on only?

In the context of screenreaders, verbosity is usually to report additional things relating to punctuation. My initial thought was having the options for "All" versus "Some" in the radio context is to try make a sort of "Announcer" for metadata updates as a separate (but related) thing to screenreader support. After using this TTS more I have some feedback about how this could possibly work.

Verbosity for different levels of Punctuation

To avoid confusion for screenreader users Verbosity could be more similar to how screenreaders use the term - to read out more "punctuation" or not. Here is a practical example of how this could apply to pyradio's TTS system:

When metadata is updated, usually the format is something like "Artist - Song", but the TTS setting as it is at the moment does not read out the hyphen, it will have a short pause instead. At first I found it a bit difficult to split the Artist / Song in my head, over time I got better at hearing the pause to separate Artist from Song. However, to make it easier for people, maybe a setting to read punctuation could avoid some of this confusion. Same thing for when "brackets" are used in part of a song title - sometimes it is obvious when something is an addition in brackets and other times it isn't but a punctuation verbosity setting could solve this.

So a Verbosity setting for punctuation could be something like: default, more punctuation, all punctuation. Or default and all.

There could be a separate toggle for "TTS announcer (to read metadata updates)", since referring to this as verbosity could get confusing if verbosity only relates to level of punctuation read out.

However if making separate settings for metadata updates versus other verbosity settings is a bit complicated I would focus on adding screenreader support for menus and dialogs first. Anything else is extras. ☺️

Additional Feedback on Metadata Updates

I've noticed some radio stations will update the metadata more than once for the same song. One radio station updated the metadata 3 times within a short space of time (like 1-2 minutes). This might have been a fluke, maybe the radio updated the metadata wrong the first time since I haven't heard this happen since, but to prevent the TTS reading out the same thing more than once, maybe there could be a check if the artist and song name is the same not to update the metadata again?

Maybe using a regular expression if there's a "includes" match on both sides of the hyphen, the TTS won't repeat itself (or rather, the metadata won't update more than once). I say both because there could be a legitimate situation where there are remixes or remake of the same song by a different artist playing back-to-back so the check should be on both sides.

On the other hand, it could just be a fluke I noticed and not worth implementing this kind of check at all. It's only happened once for one station (and I listen to pyradio for hours every day). I think a punctuation verbosity setting would be more useful to help interpret the Song / Artist when it's read out than blocking potential duplicate metadata updates.

[s-n-g]

I have a new unofficial release for you to test.
Download: https://github.com/s-n-g/pyradio/archive/refs/heads/tts.zip and unpack it
In its top directory execute

./devel/build_install_pyradio

This one adds:

1. the rate and pitch config options
2. a test function
   when you change any of the TTS options you can hear the result by pressing t.
3. some more messages
   example: press x to delete a station, a confirmation window will appear and you should hear the TTS speak its text.
4. titles will not be repeated

Regarding the punctuation setting

I would propose a on/off function (to keep things simple).

So the text: this is a sample text (to check your settings)

No punctuation: this is a sample text to check your settings
With punctuation: this is a sample text open parenthesis to check your settings close parenthesis

The text: this option is read-only

No punctuation: this option is read only
With punctuation: this option is read dash only

Did i get this right?

Regarding the verbosity setting

I like this setup.

I like the "announcer" (+ errors) category
Then we could have the medium verbosity: speak help screens and message boxes
And finally full verbosity: speak keys, values and such (although I do not know how i will implement this one - at first glance it looks hard)

What do you think?

[travis-jeans]

Testing Unofficial Release

Not sure if I did something wrong, but I followed your instructions to install then ran pyradio to load the program and got this error message.

Traceback (most recent last call):
File "/home/travis/.local/bin/pyradio", line 3, in <module>
from pyradio.main import shell
File "/home/travis/.local/pipx/venvs/pyradio/lib/python3.13/site-packages/pyradio/main.py", line 22, in <module>
from .radio import PyRadio
File "/home/travis/.local/pipx/venvs/pyradio/lib/python3.13/site-packages/pyradio/radio.py", line 62 in <module>
from .tts_text import tts_transform_to_string
ModuleNotFoundError: No module named 'pyradio.tts_text'

Punctuation Settings

Without testing the program, the way you've outlined it looks correct.

Verbosity Menu

Speak keys - by this do you mean when you press the down arrow key it might say "down" before reading list items? Personally I tend to have this screenreader setting off the vast majority of the time. However, if there's an in program "help" screen which gives an overview of major shortcuts, then it could just read the text on that pop up to remind people what keys do. I can probably give more feedback once the test app is working. But if by "speak keys" you mean "speak key presses" I don't think it's necessary unless you are doing keyboard input for typing a shortcut like "\T" to toggle the screenreader.

I guess as an example of what I meant is that in the settings menu if you were changing the keybindings it would make sense to say the key presses once they're entered as a new keybinding especially if the key presses don't actually correspond to the exact same keybinding because of the terminal interface. It should be clear to the person listening that the keys they've pressed don't correspond to the same keybinding: if I press Ctrl+Shift+Alt+K and it comes up as "Ctrl+Shift+K the TTS should read "Ctrl+Shift+K" not "Ctrl+Shift+Alt+K".

An example of reading menus would be the TTS would read out the "values" of the currently bound shortcuts in the menu as they appear visually.

Hopefully that wasn't too much. 😅

Example Menus

So instead of bundling everything under verbosity they could be separated something like this (first option is default).

Verbosity

• default
• with punctuation

Speech Context

• all (metadata and menus)
• metadata only

[s-n-g]

You did nothing wrong., i did: I forgot to upload a file...

So, here it is again:
Download: https://github.com/s-n-g/pyradio/archive/refs/heads/tts.zip and unpack it
In its top directory execute

./devel/build_install_pyradio

Punctuation Settings

Without testing the program, the way you've outlined it looks correct.

Please keep in mind it is not implemented yet, it's just brainstorming...

Verbosity Menu

ok, I see what you mean; let's just test the program, as it is right now (especially the "press x part") and see how we can go on