1BRLTTY(1)                    BRLTTY User's Manual                    BRLTTY(1)
2
3
4

NAME

6       brltty - refreshable braille display driver for Linux/Unix
7

SYNOPSIS

9       brltty [option ...]
10

DESCRIPTION

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

OPTIONS

19       Options  can  be  passed  to  brltty in a number of ways.  From most to
20       least influential, these are:
21
22       1.  Command Line Options
23
24       2.  Boot Parameters
25
26       3.  Environment Variables (if the -E  (--environment-variables)  option
27           is in effect)
28
29       4.  The Configuration File
30
31       5.  Built-in Defaults
32
33   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
38       The following options are supported:
39
40       -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
45       -b driver,...|auto (--braille-driver=)
46              The  driver  for the braille display (see Driver Specification).
47              The built-in default is auto.
48
49       -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
53       -d device,... (--braille-device=)
54              The  device  to  which  the  braille  display is connected.  The
55              built-in default is usb:,bluetooth:.
56
57              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
62              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
67              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
75              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
86              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
92       -e (--standard-error)
93              Write logs to standard error rather than to the system log (use‐
94              ful for debugging).
95
96       -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
101       -h (--help)
102              Print a command line usage summary (commonly used options only),
103              and then exit.
104
105       -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
113       -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
117       -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
122              0   emergency
123
124              1   alert
125
126              2   critical
127
128              3   error
129
130              4   warning
131
132              5   notice
133
134              6   information
135
136              7   debug
137
138       The built-in default is notice.
139
140       -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
147              Linux/ALSA  the first available MIDI output port
148
149              Linux/OSS   /dev/sequencer
150
151       -n (--no-daemon)
152              Remain in the foreground (useful for debugging).
153
154       -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
158       -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
163              FreeBSD     /dev/dsp
164
165              Linux/ALSA  hw:0,0
166
167              Linux/OSS   /dev/dsp
168
169              NetBSD      /dev/audio
170
171              OpenBSD     /dev/audio
172
173              Qnx         the preferred PCM output device
174
175              Solaris     /dev/audio
176
177       -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
183       -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
187       -s driver,...|auto (--speech-driver=)
188              The  driver  for  the  speech synthesizer (see Driver Specifica‐
189              tion).  The built-in default is auto.
190
191       -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
197       -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
209       -x driver (--screen-driver=)
210              The screen driver.  The built-in default is operating system ap‐
211              propriate.
212
213       -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
218       -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
226       -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
230       -E (--environment-variables)
231              Recognize environment variables.
232
233       -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
237       -H (--full-help)
238              Print a command line usage summary (all options), and then exit.
239
240       -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
245       -K arg (--keyboard-properties=)
246              Properties of the keyboard.
247
248       -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
253       -M csecs (--message-delay=)
254              The message hold time in hundredths of a second.   The  built-in
255              default is 400 (4 seconds).
256
257       -N (--no-api)
258              Don't start the application programming interface.
259
260       -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
266       -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
271       -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
279       -T directory (--tables-directory=)
280              The  path  to the directory which contains the text, attributes,
281              contraction, keyboard, and input tables.  The  built-in  default
282              is /etc/brltty.
283
284       -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
288       -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
295       -W directory (--writable-directory=)
296              The path to a directory which can be written to.   The  built-in
297              default is /run/brltty.
298
299       -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
304       -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.3.
308
309       -Z text (--stop-message=)
310              The  text to be shown when the braille driver stops.  The built-
311              in default is BRLTTY stopped.
312
313   Environment Variables
314       The following environment variables are recognized if the  -E  (--envi‐
315       ronment-variables) option is specified:
316
317       BRLTTY_API_PARAMETERS=name=value,...
318              Parameters  for  the application programming interface.  See the
319              -A (--api-parameters=) option for details.
320
321       BRLTTY_ATTRIBUTES_TABLE=table
322              The attributes table.  See the -a  (--attributes-table=)  option
323              for details.
324
325       BRLTTY_BRAILLE_DEVICE=device,...
326              The  device  to which the braille display is connected.  See the
327              -d (--braille-device=) option for details.
328
329       BRLTTY_BRAILLE_DRIVER=driver,...|auto
330              The   driver   for   the   braille   display.    See   the    -b
331              (--braille-driver=) option for details.
332
333       BRLTTY_BRAILLE_PARAMETERS=[driver:]name=value,...
334              Parameters   for   the  braille  display  driver.   See  the  -B
335              (--braille-parameters=) option for details.
336
337       BRLTTY_CONFIGURATION_FILE=file
338              The configuration file.  See the -f (--configuration-file=)  op‐
339              tion for details.
340
341       BRLTTY_CONTRACTION_TABLE=table
342              The contraction table.  See the -c (--contraction-table=) option
343              for details.
344
345       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
349       BRLTTY_PCM_DEVICE=device
350              The device to use for digital audio.  See the -p (--pcm-device=)
351              option for details.
352
353       BRLTTY_PREFERENCES_FILE=file
354              The preferences file.  See the -F  (--preferences-file=)  option
355              for details.
356
357       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
362       BRLTTY_SCREEN_DRIVER=driver
363              The screen driver.  See the -x (--screen-driver=) option for de‐
364              tails.
365
366       BRLTTY_SCREEN_PARAMETERS=name=value,...
367              Parameters for the screen driver.  See the -X  (--screen-parame‐
368              ters=) option for details.
369
370       BRLTTY_SPEECH_DRIVER=driver,...|auto
371              The   driver   for   the   speech   synthesizer.    See  the  -s
372              (--speech-driver=) option for details.
373
374       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
379       BRLTTY_SPEECH_PARAMETERS=[driver:]name=value,...
380              Parameters for  the  speech  synthesizer  driver.   See  the  -S
381              (--speech-parameters=) option for details.
382
383       BRLTTY_TEXT_TABLE=table
384              The text table.  See the -t (--text-table=) option for details.
385
386   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
391       The following configuration directives are supported:
392
393       api-parameters name=value,...
394              Parameters  for  the application programming interface.  See the
395              -A (--api-parameters=) option for details.
396
397       attributes-table table
398              The attributes table.  See the -a  (--attributes-table=)  option
399              for details.
400
401       braille-device device,...
402              The  device  to which the braille display is connected.  See the
403              -d (--braille-device=) option for details.
404
405       braille-driver driver,...|auto
406              The   driver   for   the   braille   display.    See   the    -b
407              (--braille-driver=) option for details.
408
409       braille-parameters [driver:]name=value,...
410              Parameters   for   the  braille  display  driver.   See  the  -B
411              (--braille-parameters=) option for details.
412
413       contraction-table table
414              The contraction table.  See the -c (--contraction-table=) option
415              for details.
416
417       midi-device device
418              The  device to use for the Musical Instrument Digital Interface.
419              See the -m (--midi-device=) option for details.
420
421       pcm-device device
422              The device to use for digital audio.  See the -p (--pcm-device=)
423              option for details.
424
425       preferences-file file
426              The  preferences  file.  See the -F (--preferences-file=) option
427              for details.
428
429       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
434       screen-driver driver
435              The screen driver.  See the -x (--screen-driver=) option for de‐
436              tails.
437
438       screen-parameters name=value,...
439              Parameters  for the screen driver.  See the -X (--screen-parame‐
440              ters=) option for details.
441
442       speech-driver driver,...|auto
443              The  driver  for   the   speech   synthesizer.    See   the   -s
444              (--speech-driver=) option for details.
445
446       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
451       speech-parameters [driver:]name=value,...
452              Parameters  for  the  speech  synthesizer  driver.   See  the -S
453              (--speech-parameters=) option for details.
454
455       text-table table
456              The text table.  See the -t (--text-table=) option for details.
457
458   Driver Specification
459       A braille display or speech synthesizer driver must  be  specified  via
460       its identification code:
461
462              al  Alva
463
464              an  Android
465
466              at  Albatross
467
468              ba  BrlAPI
469
470              bc  BrailComm
471
472              bd  Braudi
473
474              bg  B2G
475
476              bl  BrailleLite
477
478              bm  Baum
479
480              bn  BrailleNote
481
482              cb  CombiBraille
483
484              ce  Cebra
485
486              cn  Canute
487
488              ec  EcoBraille
489
490              en  eSpeak-NG
491
492              es  eSpeak
493
494              eu  EuroBraille
495
496              fa  FrankAudiodata
497
498              fl  FestivalLite
499
500              fs  FreedomScientific
501
502              fv  Festival
503
504              gs  GenericSay
505
506              hd  Hedo
507
508              hm  HIMS
509
510              ht  HandyTech
511
512              hw  HumanWare
513
514              ir  Iris
515
516              ic  Inceptor
517
518              lb  Libbraille
519
520              lt  LogText
521
522              mb  MultiBraille
523
524              md  MDV
525
526              mm  BrailleMemo
527
528              mn  MiniBraille
529
530              mp  Mikropuhe
531
532              mt  Metec
533
534              no  no driver
535
536              np  NinePoint
537
538              pg  Pegasus
539
540              pm  Papenmeier
541
542              sd  SpeechDispatcher
543
544              sk  Seika
545
546              sw  Swift
547
548              th  Theta
549
550              tn  TechniBraille Systems Inc.
551
552              ts  Telesensory Systems Inc.
553
554              tt  TTY
555
556              vd  VideoBraille
557
558              vo  Voyager, Part232 (serial adapter), BraillePen/EasyLink
559
560              vr  Virtual
561
562              vs  VisioBraille
563
564              vv  ViaVoice
565
566              xs  ExternalSpeech
567
568              xw  XWindow
569
570              A  comma-delimited list of drivers may be specified.  If this is
571              done then autodetection is performed using each listed driver in
572              sequence.   You may need to experiment in order to determine the
573              most reliable order since some drivers  autodetect  better  than
574              others.
575
576              If  the single word auto is specified then autodetection is per‐
577              formed using only those drivers which are known to  be  reliable
578              for this purpose.
579

SEE ALSO

581       For    full    documentation,    see   brltty's   on-line   manual   at
582       [http://brltty.app/documentation.html].
583
584
585
586brltty 6.3                       January 2021                        BRLTTY(1)
Impressum