Skip to main content

Setting up a terminal screen-reader on OpenBSD

Tim Chase

This post walks through installing the screen-reader yasr and configuring it to use speech-dispatcher with a TTS engine.

This assumes you have successfully installed a stock OpenBSD system and that your user has doas access to install software.

Install required packages

First, install the requisite packages from the repos: 

$ doas pkg_add speech-dispatcher espeak flite
The flite package is optional, but can provide you with an alternate set of voices.

Currently yasr isn't available as an OpenBSD package, but it's fairly easy to install. You should be able to obtain the yasr source tarball from the yasr home page where they also provide CVS access to the source-code . In case you want to check against the version 0.6.9 used here: 

$ cd
$ mkdir tmp
$ cd tmp
$ ftp http://prdownloads.sourceforge.net/yasr/yasr-0.6.9.tar.gz
$ sha256 http://prdownloads.sourceforge.net/yasr/yasr-0.6.9.tar.gz
SHA256 (yasr-0.6.9.tar.gz) = 41f17cfab8e88824a8dc1476602a0944b9030a8f8da2538a7a6549e3534e3bdf
and to build it 
$ tar xzf yasr-0.6.9.tar.gz
$ cd yasr-0.6.9
$ ./configure && make
At some point, hopefully yasr will be in the package repositories, making it as easy as pkg_add yasr.

Ensure that sound works

If you haven't already, make sure that your OpenBSD box can play audio. You can check this by using 

$ aucat -i somefile.wav
If you don't have any .wav files on your machine, speech-dispatcher provides /usr/local/share/sounds/speech-dispatcher/test.wav so 
aucat -i /usr/local/share/sounds/speech-dispatcher/test.wav
should play a short flourish. If it is too quiet, use mixerctl to set the volume or try additional OpenBSD audio troubleshooting techniques.

Set up speech-dispatcher

To create a user configuration file in ~/.config/speech-dispatcher/ use 

$ spd-conf
with the default output of "espeak" (you can later try changing this to "flite" but I leave that as an exercise for the reader) and output via libao. You can also set the default output speed. I prefer it a little faster than the default but it might be good to start with the default and then tune it later. As you configure, it should offer you the option to run some tests. If you choose "yes" for the first test, you should hear "Speech dispatcher works." I recommend skipping the other tests. With this in place, you should now have a ~/.config/speech-dispatcher/ directory with various configuration settings within.

The yasr screen-reader requires speech-dispatcher to listen on an inet socket rather than a Unix socket, so edit the config file with your favorite text editor and uncomment/change the CommunicationMethod from "unix_socket" to "inet_socket" 

$ ed ~/.config/speech-dispatcher/speechd.conf
/CommunicationMethod.*unix_socket
a
CommunicationMethod "inet_socket"
.

wq
This does open a local port (6560) allowing other processes on the same machine to connect to speech-dispatcher just so you're aware. If you choose to change the port, just make sure to also change it in the yasr configuration later.

Configure yasr

Copy the default yasr configuration file for modification: 

$ cp ~/tmp/yasr-0.6.9/yasr.conf ~/.yasr.conf
Make the following changes:

  • Comment out all the synthesizer=… lines except the synthesizer=speech dispatcher line, uncommenting that one
  • Uncomment the synthesizer port=127.0.0.1:6560 line
  • Set the shell=… to your preferred shell. OpenBSD doesn't install bash at /bin/bash so you'll either want to use /bin/ksh or, (if you have bash installed) /usr/local/bin/bash, or your preferred default shell.
You can change other aspects of yasr in here, but for now, leave the defaults.

Testing

It took me a bit to figure out that speech-dispatcher listens for a connection but times-out (by default, 5 seconds) and then quits. So you need to invoke it and then immediately launch yasr 

$ speech-dispatcher && ~/tmp/yasr-0.6.9/yasr/yasr
If all is working successfully it should start yasr and you should hear it read your prompt.

Getting started with yasr

The ~/.yasr.conf file lists all of the keyboard commands for both normal/interactive mode (the default) and for review mode. Keys are given by ASCII value written in hex.

Normal/interactive mode commands
Hex value(s) Keyboard command Action
0x01 Ctrl+A say cursor
0x0c Ctrl+L say line
0x0e Ctrl+N bypass
0x18 Ctrl+X flush
0x1b0b Ctrl+Alt+K keyboard wizard
0x1b0f Ctrl+Alt+O options menu
0x1b13 Ctrl+Alt+S write configuration
0x1b30 Alt+0 say line:256
0x1b62 Alt+b say character:-1
0x1b63 Alt+c say character
0x1b64 Alt+d say word
0x1b65 Alt+e read cursor to bottom
0x1b69 Alt+i reinitialize
0x1b6b Alt+k say line:-1
0x1b6c Alt+l say line
0x1b6d Alt+m say line:1
0x1b72 Alt+r toggle review mode
0x1b74 Alt+t read top to cursor
0x1b77 Alt+w read screen
0x1b78 Alt+x flush:1

When you enter review-mode, commands go to yasr directly instead of being passed to the application.

Review-mode commands
Hex value(s) Keyboard command Action
0x20 space say review cursor
0x24 $ end of line
0x28 ( previous paragraph
0x29 ) next paragraph
0x3c < search back
0x3e > search forward
0x5e ^ beginning of line
0x60 ` ascii
0x62 b say character:-1
0x63 c say character
0x65 e read cursor to bottom
0x66 f find
0x6a j say line:1:0
0x6b k say line:-1:0
0x6c l say line
0x6d m say line:1:0
0x6e n bypass
0x74 t read top to cursor
0x76 v set option:6
0x77 w read screen
0x78 x say word:1
0x7a z say word:-1
0x1b73 Alt+s set option:5
0x1b5b41 Up arrow say line:-1:1
0x1b5b42 Down arrow say line:1:1
0x1b5b44 Left arrow say character:-1
0x1b5b43 Right arrow say character:1

I'm not quite sure what several of those do, but feel free to experiment with them.

Next steps

From here, you can tweak your yasr keyboard commands in your ~/.yasr.conf or change your speech-dispatcher settings in your ~/.config/speech-dispatcher/speechd.conf and ~/.config/speech-dispatcher/modules/espeak.conf files.

You might copy/link the yasr binary into some place on your $PATH such as 

$ mkdir ~/bin
$ ln -s ~/tmp/yasr-0.6.9/yasr/yasr ~/bin

If you're feeling adventuous and prefer flite you might try configuring speech-dispatcher to use that instead.

Finally, it helps to have a suite of applications that play nicely with text-to-speech output. A few you might want to try:

  • Local mail: mail/mailx
  • Remote mail: s-nail (available as a package)
  • Calendar: remind (available as a package)
  • Web-browsing: lynx or edbrowse
  • RSS: rss2email or newsboat (both available as as packages)
  • IRC: ii (available as a package) or tinyirc (not currently available as a package)
  • Task management: taskwarrior or devtodo (both available as as packages)
  • Music: cmus or mpd/mpc (both available as as packages)
  • Terminal multiplexing: tmux or GNU screen (available as packages) It helps to either hide the status-bar or remove the clock so that it doesn't constantly spam you with time updates
  • Games:
    • bsdgames collection
    • frotz interpreter for Infocom-style text adventures