The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


Speech::Speakup - a module to interface with the Speakup screen-reader


 use Speech::Speakup;
 my @speakup_parameters = Speech::Speakup::speakup_get();
 my @synth_parameters   = Speech::Speakup::synth_get();
 print "speakup_parameters are @speakup_parameters\n";
 print "synth_parameters   are @synth_parameters\n";
 Speech::Speakup::speakup_set('silent', 7);  # impose silence
 Speech::Speakup::speakup_set('silent', 4);  # restore speech
 Speech::Speakup::synth_set('punct', 2);  # change the punctuation-level


Speakup is a screen-reader that runs on Linux as a module within the kernel. A screen-reader allows blind or visually-impaired people to hear text as it appears on the screen, and to review text already displayed anywhere on the screen. Speakup will only run on the linux consoles, but is powerful and ergonomic, and can run during the boot process. The other important screen-reader is yasr, which runs in user-space and is very portable, but has less features.

There are parameters you can get and set at the screen-reader level by using the routines speakup_get and speakup_set.

One of those parameters is the particular voice synthesiser engine that speakup will use; this synthesiser has its own parameters, parameters that speakup will use when invoking it, and which you can get and set by using the routines synth_get and synth_set.

The synthesiser can be a hardware device, on a serial line or USB, or it can be software. The most common software synth for Linux is espeak, and flite is also important.

There are also some files in /proc or /sys determining things such as how the various punctuation parameters are to be pronounced. These can not be edited in situ. You should use the speakupconf utility (in debian it's in the speakup-tools package) to save an aside-copy, then edit that, then reload:

 speakupconf save
 vi ~/.speakup/i18n/characters
 speakupconf load

This is Speech::Speakup version 1.05


All these routines set the variable $Speech::Speakup::Message to an appropriate error message if they fail.

speakup_get() or speakup_get($param);

When called without arguments, speakup_get returns a list of the readable speakup parameters.

When called with one of those parameters as an argument, speakup_get returns the current value of that parameter, or undef if the get fails.

Most parameters are only one line long, and are returned without any terminating new-line. The (read-only) keymap and version parameters are longer; they are returned as a scalar text string containing embedded new-lines.

speakup_set() or speakup_set($param, $value);

When called without arguments, speakup_set returns a list of the writeable speakup parameters.

When called with $parameter,$value as arguments, speakup_set sets the value of that parameter. It returns success or failure.

synth_get() or synth_get($param);

When called without arguments, synth_get returns a list of the readable synthesiser parameters.

When called with one of those parameters as an argument, synth_get returns the current value of that parameter, or undef if the get fails.

synth_set() or synth_set($param, $value);

When called without arguments, synth_set returns a list of the writeable synthesiser parameters.

When called with $parameter,$value as arguments, synth_set sets the value of that parameter. It returns success or failure.


The parameters key_echo and no_interrupt are boolean: 0 or 1.

The important silent parameter is a bitmap. 7 means immediate silence flushing all pending text; 5 speaks the pending text and then goes silent; then 4 restores speech.

The punc_some, punc_most and punc_all parameters are strings containing lists of punctuation characters. The reading_punc parameter can then be set to 0, 1, 2 or 3 in order to select which punctuation characters are pronounced when reading (for example with Keypad-8), and the punc_level parameter can be set likewise to select which punctuation characters are pronounced when the computer writes them to the screen. 1 selects punc_some, 2 selects punc_most, 3 selects punc_all, and 0 supresses pronounciation of any punctuation. For reading prose, you'll probably prefer 1, and for a programming languange probably 3.

The speakup parameter synth is a string, which must exist as a subdirectory of the speakup parameter directory.

The parameter synth_direct is not a parameter, it is a direct input to the synthesiser; use this if your application needs to say something. It imposes a length-limit of 250 bytes. The synth_direct input bypasses speakup, and works even if the silent parameter is set to 7. Its punctuation-level ignores the settings of punc_level or reading_punc, and is controled by the synth punct parameter, see below.

The authoritative documentation of these parameters is the source code, in the file drivers/staging/speakup/kobjects.c


The punct and tone parameters may be set to 0, 1 or 2.

The punct parameter controls the punctuation-level applied to the synth_direct input. When punct is 0 or 2, then # $ % & * + / = @ are pronounced, and when punct is 1 all punctuation seems to be pronounced.

The important vol, pitch, freq and rate parameters are 0 to 9, default 5.

freq controls the expressiveness of the voice (the amount by which its frequency varies during speech), whereas pitch adjusts between a low voice and a high voice.


No routines are exported by default, but they are exported under the ALL tag, so if you want to import them all you should:

 import Speech::Speakup qw(:ALL);



Whenever a subroutine call fails, the $Message variable is set with an appropriate error message. If the call succeeds it is set to undef.


The $SpDir variable is set to the the speakup-directory, which can be in /proc but is usually in /sys/accesibility.


A simple example in the examples/ subdirectory is already a useful application:


speakup_params lists, and then allows you to modify, all the speakup and synth parameters. It uses the Term::Clui module to provide the user-interface.


It requires only Exporter, which is core Perl.

The example speakup_params requires also the CPAN module Term::Clui


Peter J Billam

 aptitude install espeakup speakup-tools
 aptitude install flite eflite
 /sys/accessibility/speakup/ or /proc/speakup/
 aptitude install espeak
 perldoc Speech::eSpeak

There should soon be an equivalent Python3 module with the same calling interface, at