1BRLTTY(1) BRLTTY User's Manual BRLTTY(1)
2
6 brltty - refreshable braille display driver for Linux/Unix
7
9 brltty [option ...]
10
12 brltty is a background process (daemon) which provides access to the
13 console screen (when in text mode) for a blind person using a refresh‐
14 able braille display. It drives the braille display, and provides com‐
15 plete screen review functionality. Some speech capability has also
16 been incorporated.
17
19 Options can be passed to brltty in a number of ways. From most to
20 least influential, these are:
21 1. Command Line Options
23 2. Boot Parameters
25 3. Environment Variables (if the -E (--environment-variables) option
27 is in effect)
28 4. The Configuration File
30 5. Built-in Defaults
32 Command Line Options
34 The options are processed sequentially from left to right. If an op‐
35 tion is specified more than once, or in case of a conflict, the right‐
36 most specification takes precedence.
37 The following options are supported:
39 -a table (--attributes-table=)
41 The path to the attributes table. Relative paths are anchored
42 at /etc/brltty/Attributes. The .atb extension is optional. The
43 built-in default is left_right.atb.
44 -b driver,...|auto (--braille-driver=)
46 The driver for the braille display (see Driver Specification).
47 The built-in default is auto.
48 -c table (--contraction-table=)
50 The path to the contraction table. Relative paths are anchored
51 at /etc/brltty/Contraction. The .ctb extension is optional.
52 -d device,... (--braille-device=)
54 The device to which the braille display is connected. The
55 built-in default is usb:,bluetooth:.
56 The general form of a braille device specification is quali‐
58 fier:data. For backward compatibility with earlier releases, if
59 the qualifier is omitted then serial: is assumed. The following
60 device types are supported:
61 Bluetooth
63 For a bluetooth device, specify bluetooth:address. The
64 address must be six two-digit hexadecimal numbers sepa‐
65 rated by colons, e.g. 01:23:45:67:89:AB.
66 Serial For a serial device, specify serial:device. The serial:
68 qualifier is optional (for backward compatibility). If a
69 relative path is given then it's anchored at /dev/ (the
70 usual location where devices are defined on a Unix-like
71 system). The following device specifications all refer
72 to the primary serial device on Linux: serial:ttyS0, se‐
73 rial:/dev/ttyS0, ttyS0, /dev/ttyS0.
74 USB For a USB device, specify usb:. brltty will search for
76 the first USB device which matches the braille display
77 driver being used. If this is inadequate, e.g. if you
78 have more than one USB braille display which requires the
79 same driver, then you can refine the device specification
80 by appending the serial number of the display to it, e.g.
81 usb:12345. N.B.: The "identification by serial number"
82 feature doesn't work for some models because some manu‐
83 facturers either don't set the USB serial number descrip‐
84 tor at all or do set it but not to a unique value.
85 A comma-delimited list of braille devices may be specified. If
87 this is done then autodetection is performed on each listed de‐
88 vice in sequence. This feature is particularly useful if you
89 have a braille display with more than one interface, e.g. both a
90 serial and a USB port.
91 -e (--standard-error)
93 Write logs to standard error rather than to the system log (use‐
94 ful for debugging).
95 -f file (--configuration-file=)
97 The path to the configuration file. Relative paths are anchored
98 at the current working directory. The built-in default is
99 /etc/brltty.conf.
100 -h (--help)
102 Print a command line usage summary (commonly used options only),
103 and then exit.
104 -i name (--speech-input=)
106 The file system object (FIFO, named pipe, named socket, etc)
107 which gives other applications access to brltty's speech driver
108 for text-to-speech conversion. It's created at start-up and re‐
109 moved at termination. Relative paths are anchored at the cur‐
110 rent working directory. The built-in default is that the file
111 system object is not created.
112 -k table (--keyboard-table=)
114 The path to the keyboard table. Relative paths are anchored at
115 /etc/brltty/Keyboard. The .ktb extension is optional.
116 -l level (--log-level=)
118 The minimum severity level for messages written to the log. Any
119 of the following numbers, or any abbreviation of their corre‐
120 sponding names, may be specified:
121 0 emergency
123 1 alert
125 2 critical
127 3 error
129 4 warning
131 5 notice
133 6 information
135 7 debug
137 The built-in default is notice.
139 -m device (--midi-device=)
141 The device to use for the Musical Instrument Digital Interface.
142 For ALSA it's client:port, where each may be either a number or
143 a case-sensitive substring of its name. For other interfaces
144 it's the full path to an appropriate system device. The built-
145 in default is:
146 Linux/ALSA the first available MIDI output port
148 Linux/OSS /dev/sequencer
150 -n (--no-daemon)
152 Remain in the foreground (useful for debugging).
153 -o name=value,... (--override-preference=)
155 Override a preference setting. For the location of the prefer‐
156 ences file, see the -F (--preferences-file) option.
157 -p device (--pcm-device=)
159 The device to use for digital audio. For ALSA it's name[:argu‐
160 ment,...]. For other interfaces it's the full path to an appro‐
161 priate system device. The built-in default is:
162 FreeBSD /dev/dsp
164 Linux/ALSA hw:0,0
166 Linux/OSS /dev/dsp
168 NetBSD /dev/audio
170 OpenBSD /dev/audio
172 Qnx the preferred PCM output device
174 Solaris /dev/audio
176 -q (--quiet)
178 Suppress the start-up messages. This is done by reducing the
179 default log level (see the -l (--log-level=) option) to warning
180 (information if either -v (--verify) or -V (--version) is also
181 specified).
182 -r (--release-device)
184 Release the device to which the braille display is connected
185 when the current screen or window can't be read.
186 -s driver,...|auto (--speech-driver=)
188 The driver for the speech synthesizer (see Driver Specifica‐
189 tion). The built-in default is auto.
190 -t table (--text-table=)
192 The path to the text table. Relative paths are anchored at
193 /etc/brltty/Text. The .ttb extension is optional. The built-in
194 default is en-nabcc.ttb (the North American Braille Computer
195 Code).
196 -v (--verify)
198 Print the start-up messages and then exit. This always includes
199 the versions of brltty itself, the server side of its applica‐
200 tion programming interface, and each of the selected braille and
201 speech drivers. If the -q (--quiet) option isn't also specified
202 then it also includes the values of the options after all
203 sources have been considered. If more than one braille driver
204 and/or more than one braille device has been specified then
205 braille display autodetection is performed. If more than one
206 speech driver has been specified then speech synthesizer autode‐
207 tection is performed.
208 -x driver (--screen-driver=)
210 The screen driver. The built-in default is operating system ap‐
211 propriate.
212 -A name=value,... (--api-parameters=)
214 Parameters for the application programming interface. If the
215 same parameter is specified more than once then the rightmost
216 specification is used. Parameter names may be abbreviated.
217 -B [driver:]name=value,... (--braille-parameters=)
219 Parameters for the braille display driver. If the same parame‐
220 ter is specified more than once then the rightmost specification
221 is used. Parameter names may be abbreviated. If a parameter
222 assignment is qualified with a driver identification code then
223 it's only processed if that braille display driver is being
224 used.
225 -D directory (--drivers-directory=)
227 The path to the directory which contains the dynamically load‐
228 able driver objects. The built-in default is /usr/lib64/brltty.
229 -E (--environment-variables)
231 Recognize environment variables.
232 -F file (--preferences-file=)
234 The path to the preferences file. Relative paths are anchored
235 at /var/lib/brltty. The built-in default is brltty.prefs.
236 -H (--full-help)
238 Print a command line usage summary (all options), and then exit.
239 -I (--install-service)
241 (Windows only) Install brltty as the BrlAPI service so that it
242 will be automatically started when the system is booted, and so
243 that applications can know that a BrlAPI server is running.
244 -K arg (--keyboard-properties=)
246 Properties of the keyboard.
247 -L file (--log-file=)
249 The file to which log messages are written. Relative paths are
250 anchored at the current working directory. The default is to
251 send log messages to the system log.
252 -M csecs (--message-delay=)
254 The message hold time in hundredths of a second. The built-in
255 default is 400 (4 seconds).
256 -N (--no-api)
258 Don't start the application programming interface.
259 -P file (--pid-file=)
261 The full path to the process identifier file. If this option is
262 supplied, brltty writes its process identifier (pid) into the
263 specified file at start-up. The file is removed when brltty
264 terminates.
265 -R (--remove-service)
267 (Windows only) Remove the BrlAPI service so that brltty will not
268 be automatically started when the system is booted, and so that
269 applications can know that no BrlAPI server is running.
270 -S [driver:]name=value,... (--speech-parameters=)
272 Parameters for the speech synthesizer driver. If the same pa‐
273 rameter is specified more than once then the rightmost specifi‐
274 cation is used. Parameter names may be abbreviated. If a pa‐
275 rameter assignment is qualified with a driver identification
276 code then it's only processed if that speech synthesizer driver
277 is being used.
278 -T directory (--tables-directory=)
280 The path to the directory which contains the text, contraction,
281 attributes, keyboard, and input tables. The built-in default is
282 /etc/brltty.
283 -U directory (--updatable-directory=)
285 The path to a directory which contains files that can be up‐
286 dated. The built-in default is /var/lib/brltty.
287 -V (--version)
289 Print the versions of brltty itself, the server side of its ap‐
290 plication programming interface, and those drivers which were
291 configured in at build-time, and then exit. If the -q (--quiet)
292 option isn't also specified then also print copyright informa‐
293 tion.
294 -W directory (--writable-directory=)
296 The path to a directory which can be written to. The built-in
297 default is /run/brltty.
298 -X name=value,... (--screen-parameters=)
300 Parameters for the screen driver. If the same parameter is
301 specified more than once then the rightmost specification is
302 used. Parameter names may be abbreviated.
303 -Y text (--start-message=)
305 The text to be shown when the braille driver starts and to be
306 spoken when the speech driver starts. The built-in default is
307 BRLTTY 6.6.
308 -Z text (--stop-message=)
310 The text to be shown when the braille driver stops. The built-
311 in default is BRLTTY stopped.
312 Environment Variables
314 The following environment variables are recognized if the -E (--envi‐
315 ronment-variables) option is specified:
316 BRLTTY_API_PARAMETERS=name=value,...
318 Parameters for the application programming interface. See the
319 -A (--api-parameters=) option for details.
320 BRLTTY_ATTRIBUTES_TABLE=table
322 The attributes table. See the -a (--attributes-table=) option
323 for details.
324 BRLTTY_BRAILLE_DEVICE=device,...
326 The device to which the braille display is connected. See the
327 -d (--braille-device=) option for details.
328 BRLTTY_BRAILLE_DRIVER=driver,...|auto
330 The driver for the braille display. See the -b
331 (--braille-driver=) option for details.
332 BRLTTY_BRAILLE_PARAMETERS=[driver:]name=value,...
334 Parameters for the braille display driver. See the -B
335 (--braille-parameters=) option for details.
336 BRLTTY_CONFIGURATION_FILE=file
338 The configuration file. See the -f (--configuration-file=) op‐
339 tion for details.
340 BRLTTY_CONTRACTION_TABLE=table
342 The contraction table. See the -c (--contraction-table=) option
343 for details.
344 BRLTTY_MIDI_DEVICE=device
346 The device to use for the Musical Instrument Digital Interface.
347 See the -m (--midi-device=) option for details.
348 BRLTTY_PCM_DEVICE=device
350 The device to use for digital audio. See the -p (--pcm-device=)
351 option for details.
352 BRLTTY_PREFERENCES_FILE=file
354 The preferences file. See the -F (--preferences-file=) option
355 for details.
356 BRLTTY_RELEASE_DEVICE=on|off
358 Release the device to which the braille display is connected
359 when the current screen or window can't be read. See the -r
360 (--release-device) option for details.
361 BRLTTY_SCREEN_DRIVER=driver
363 The screen driver. See the -x (--screen-driver=) option for de‐
364 tails.
365 BRLTTY_SCREEN_PARAMETERS=name=value,...
367 Parameters for the screen driver. See the -X (--screen-parame‐
368 ters=) option for details.
369 BRLTTY_SPEECH_DRIVER=driver,...|auto
371 The driver for the speech synthesizer. See the -s
372 (--speech-driver=) option for details.
373 BRLTTY_SPEECH_INPUT=name
375 The file system object which gives other applications access to
376 brltty's speech driver for text-to-speech conversion. See the
377 -i (--speech-input=) option for details.
378 BRLTTY_SPEECH_PARAMETERS=[driver:]name=value,...
380 Parameters for the speech synthesizer driver. See the -S
381 (--speech-parameters=) option for details.
382 BRLTTY_TEXT_TABLE=table
384 The text table. See the -t (--text-table=) option for details.
385 The Configuration File
387 Blank lines are ignored. If the character # occurs on any line then
388 all characters from it to the end of that line are treated as a com‐
389 ment.
390 The following configuration directives are supported:
392 api-parameters name=value,...
394 Parameters for the application programming interface. See the
395 -A (--api-parameters=) option for details.
396 attributes-table table
398 The attributes table. See the -a (--attributes-table=) option
399 for details.
400 braille-device device,...
402 The device to which the braille display is connected. See the
403 -d (--braille-device=) option for details.
404 braille-driver driver,...|auto
406 The driver for the braille display. See the -b
407 (--braille-driver=) option for details.
408 braille-parameters [driver:]name=value,...
410 Parameters for the braille display driver. See the -B
411 (--braille-parameters=) option for details.
412 contraction-table table
414 The contraction table. See the -c (--contraction-table=) option
415 for details.
416 midi-device device
418 The device to use for the Musical Instrument Digital Interface.
419 See the -m (--midi-device=) option for details.
420 pcm-device device
422 The device to use for digital audio. See the -p (--pcm-device=)
423 option for details.
424 preferences-file file
426 The preferences file. See the -F (--preferences-file=) option
427 for details.
428 release-device on|off
430 Release the device to which the braille display is connected
431 when the current screen or window can't be read. See the -r
432 (--release-device) option for details.
433 screen-driver driver
435 The screen driver. See the -x (--screen-driver=) option for de‐
436 tails.
437 screen-parameters name=value,...
439 Parameters for the screen driver. See the -X (--screen-parame‐
440 ters=) option for details.
441 speech-driver driver,...|auto
443 The driver for the speech synthesizer. See the -s
444 (--speech-driver=) option for details.
445 speech-input 0me
447 The file system object which gives other applications access to
448 brltty's speech driver for text-to-speech conversion. See the
449 -i (--speech-input=) option for details.
450 speech-parameters [driver:]name=value,...
452 Parameters for the speech synthesizer driver. See the -S
453 (--speech-parameters=) option for details.
454 text-table table
456 The text table. See the -t (--text-table=) option for details.
457 Driver Specification
459 A braille display or speech synthesizer driver must be specified via
460 its identification code:
461 al Alva
463 an Android
465 at Albatross
467 ba BrlAPI
469 bc BrailComm
471 bd Braudi
473 bl BrailleLite
475 bm Baum
477 bn BrailleNote
479 cb CombiBraille
481 ce Cebra
483 cn Canute
485 dp DotPad
487 ec EcoBraille
489 en eSpeak-NG
491 es eSpeak
493 eu EuroBraille
495 fa FrankAudiodata
497 fl FestivalLite
499 fs FreedomScientific
501 fv Festival
503 gs GenericSay
505 hd Hedo
507 hm HIMS
509 ht HandyTech
511 hw HumanWare
513 ir Iris
515 ic Inceptor
517 lb Libbraille
519 lt LogText
521 mb MultiBraille
523 md MDV
525 mm BrailleMemo
527 mn MiniBraille
529 mp Mikropuhe
531 mt Metec
533 no no driver
535 np NinePoint
537 pg Pegasus
539 pm Papenmeier
541 sd SpeechDispatcher
543 sk Seika
545 sw Swift
547 th Theta
549 tn TechniBraille Systems Inc.
551 ts Telesensory Systems Inc.
553 vd VideoBraille
555 vo Voyager, Part232 (serial adapter), BraillePen/EasyLink
557 vs VisioBraille
559 vv ViaVoice
561 xs ExternalSpeech
563 A comma-delimited list of drivers may be specified. If this is
565 done then autodetection is performed using each listed driver in
566 sequence. You may need to experiment in order to determine the
567 most reliable order since some drivers autodetect better than
568 others.
569 If the single word auto is specified then autodetection is per‐
571 formed using only those drivers which are known to be reliable
572 for this purpose.
573
575 For full documentation, see brltty's on-line manual at
576 [http://brltty.app/documentation.html].
577brltty 6.6 July 2023 BRLTTY(1)