Setting up a terminal screen-reader on OpenBSD

Tim Chase — Sun, 19 May 2019 23:52:20 GMT

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 source code from the yasr source repository.

$  git clone https://github.com/mgorse/yasr

and to build it

$ cd yasr/yasr
$ 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

Tim's blog (Posts about BSD)