Tim's blog (Posts about accessibility)

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

Software for a command-line world

Tim Chase — Tue, 26 May 2015 21:04:51 GMT

Below are a list of programs that can all be used over an SSH connection with no need for an X connection.

Email:

mail (command-line; uses local mailboxes)
mutt (full-screen; uses local mailboxes, POP3, or IMAP)
elm (full-screen; uses local mailboxes, may support POP3/IMAP)
mh/nmh (mail-handler/new-mail-handler; command-line; uses "MH" format, supports POP3 via fetchmail)
pine/alpine (full-screen; uses local mailboxes, POP3, or IMAP)
offlineimap
and many others

RSS:

Raggle
newsbeuter
snownews
NRSS/Canto
rss2email/rss2imap
~~Google Reader~~ supports an on-line reader (the Mobile version should be usable in any console browser)

Web:

lynx (the classic full-screen text-browser)
links/links2 (a full-screen text-browser with more visual layout engine)
elinks (a full-screen text-browser with more visual layout engine)
w3m
edbrowse (it's an editor, it's a browser, it's command-line)

Text Editing:

vi/vim (the classic full-screen text-editor)
emacs (another popular and extensible choice in full-screen text-editors)
ed (the classic command-line text editor)
nano (a simple full-screen editor)
pico (a simple full-screen editor)
edbrowse (it's like ed on steroids)
and countless others

these can be used in concert with various markup syntax such as Markdown, HTML, DocBook, LaTeX, etc to produce publishable documents; you can use packages like antiword or wordview ("wv") to convert .DOC files to a usable format.

Spreadsheet/math/calculator:

Spreadsheet:
- sc (a simple full-screen spreadsheet with vi-like keybindings)
- sc-im (like sc above but with the ability to import/export xls/xlsx files)
- slsc (based on sc)
- oleo (a simple full-screen spreadsheet with a more Emacs-like feel)
- SheetsUI
Math:
- Octave
- R
- scilab
Graphing:
- gnuplot
- graphviz
Calculator
- bc (a simple command-line calculator)
- python (the full power of Python, at a command-line)

Calendar:

calendar (show events on given days)
remind (like the previous calendar program on steroids)
cal (display a calendar)
pcal (good for printing)
cron (for scheduling repeated tasks)
at (for scheduling a single job sometime in the future)
gcalcli (interact with Google Calendar from the command-line)
khal
mencal and mencal2 (menstruation calendars)

To-do/time management:

devtodo

TaskWarrior

TimeTracker (a simple command-line time-tracker in the spirit of many VCS tools, written by yours-truely in response to this post, and somewhat documented here)

Music/audio:

Playback
- cmus
- mpg321
- mpd/mpc
- mpg123
- ogg123
- pianobar (command-line Pandora client)
- nama (music recording and editing)
- and many others
Editing/recording
- sox
- ecasound
Volume control
- aumix
Podcatchers
- hpodder

Chat:

finch (a console version of Gaim/Pidgin)
centericq (support for ICQ, Yahoo!, AIM, IRC, MSN, Gadu-Gadu and Jabber protocols)
naim (support for AIM, ICQ, IRC, and the lily CMC protocols)
irssi (popular IRC client)
weechat
gtmess (MSN client)

Database:

psql interface to PostgreSQL
mysql interface to MySQL
sqlite interface to the sqlite database
all the major databases have command-line clients

Filesystem

Midnight Commander (mc)
ranger

Version control:

I currently use git, Mercurial, Bazaar, Subversion and RCS depending on the project context

Distributed VCS
- git (a fast, powerful patchwork of scripts and commands)
- mercurial (hg) (fast, powerful, predictable, and mostly written in Python)
- bazaar (fast, powerful, predictable, and purely written in Python)
- darcs (slower, and less popular)
Centralized VCS
- subversion (svn) (removes some of the annoyances of CVS and more extensible)
- cvs/OpenCVS (the classic, rapidly being replaced by Subversion)
- rcs (not bad for one developer and one text file, but doesn't scale nicely)

Addressbook:

Games:

the bsdgames package in Debian provides several (I'm a sucker for cribbage)
the frotz package gives access to most text-adventures
nethack
and oodles of other games

Torrents:

rtorrent

aria2c

Admin:

top, ps, kill, who, last
ping, traceroute, dig, ifconfig, ip, netstat, nslookup
openssl, ssh, sftp, scp, rsync
iotop an I/O monitor like "top"

Miscellaneous:

weather

I also find that using "tmux" or GNU "screen" vital to being productive, as I can do many, many things all at the same time, each in their own window. It also allows me to disconnect and then reconnect from another machine later, resuming where I left off.