BRLTTY(1)

✨ BRLTTY(1) ✨

okay so this is the BRLTTY User's Manual page for brltty, bestie. It's giving braille display driver energy for Linux/Unix. 💅

---

🌸 NAME 🌸

brltty — refreshable braille display driver for Linux/Unix.

---

🦋 SYNOPSIS 🦋

brltty [option ...]

---

💖 DESCRIPTION 💖

So basically, brltty is a background process (daemon) which provides access to the console screen (when in text mode) for a blind person using a refreshable braille display. It drives the braille display, and provides complete screen review functionality. Some speech capability has also been incorporated. periodt. ✨

---

🔥 OPTIONS 🔥

Options can be passed to brltty in a number of ways. From most to least influential, these are:

1. Command Line Options
2. Boot Parameters
3. Environment Variables (if the -E (--environment-variables) option is in effect)
4. The Configuration File
5. Built-in Defaults

🎀 Command Line Options 🎀

The options are processed sequentially from left to right. If an option is specified more than once, or in case of a conflict, the rightmost specification takes precedence.

The following options are supported:

• -a table, --attributes-table= — The path to the attributes table. Relative paths are anchored at /etc/brltty/Attributes. The .atb extension is optional. The built-in default is left_right.atb.
• -b driver,...|auto, --braille-driver= — The driver for the braille display (see Driver Specification). The built-in default is auto.
• -c table, --contraction-table= — The path to the contraction table. Relative paths are anchored at /etc/brltty/Contraction. The .ctb extension is optional.
• -d device,..., --braille-device= — The device to which the braille display is connected. The built-in default is usb:,bluetooth:.

The general form of a braille device specification is qualifier:data. For backward compatibility with earlier releases, if the qualifier is omitted then serial: is assumed. The following device types are supported:

• Bluetooth — For a bluetooth device, specify bluetooth:address. The address must be six two-digit hexadecimal numbers separated by colons, e.g. 01:23:45:67:89:AB.
• Serial — For a serial device, specify serial:device. The serial: qualifier is optional (for backward compatibility). If a relative path is given then it's anchored at /dev/ (the usual location where devices are defined on a Unix-like system). The following device specifications all refer to the primary serial device on Linux: serial:ttyS0, serial:/dev/ttyS0, ttyS0, /dev/ttyS0.
• USB — For a USB device, specify usb:. brltty will search for the first USB device which matches the braille display driver being used. If this is inadequate, e.g. if you have more than one USB braille display which requires the same driver, then you can refine the device specification by appending the serial number of the display to it, e.g. usb:12345. N.B.: The "identification by serial number" feature doesn't work for some models because some manufacturers either don't set the USB serial number descriptor at all or do set it but not to a unique value.

A comma-delimited list of braille devices may be specified. If this is done then autodetection is performed on each listed device in sequence. This feature is particularly useful if you have a braille display with more than one interface, e.g. both a serial and a USB port.

• -e, --standard-error — Write logs to standard error rather than to the system log (useful for debugging).
• -f file, --configuration-file= — The path to the configuration file. Relative paths are anchored at the current working directory. The built-in default is /etc/brltty.conf.
• -h, --help — Print a command line usage summary (commonly used options only), and then exit.
• -i name, --speech-input= — The file system object (FIFO, named pipe, named socket, etc) which gives other applications access to brltty's speech driver for text-to-speech conversion. It's created at start-up and removed at termination. Relative paths are anchored at the current working directory. The built-in default is that the file system object is not created.
• -k table, --keyboard-table= — The path to the keyboard table. Relative paths are anchored at /etc/brltty/Keyboard. The .ktb extension is optional.
• -l level, --log-level= — The minimum severity level for messages written to the log. Any of the following numbers, or any abbreviation of their corresponding names, may be specified:
  • 0 — emergency
  • 1 — alert
  • 2 — critical
  • 3 — error
  • 4 — warning
  • 5 — notice
  • 6 — information
  • 7 — debug

The built-in default is notice.

• -m device, --midi-device= — The device to use for the Musical Instrument Digital Interface. For ALSA it's client:port, where each may be either a number or a case-sensitive substring of its name. For other interfaces it's the full path to an appropriate system device. The built-in default is:
  • Linux/ALSA — the first available MIDI output port
  • Linux/OSS — /dev/sequencer
• -n, --no-daemon — Remain in the foreground (useful for debugging).
• -o name=value,..., --override-preference= — Override a preference setting. For the location of the preferences file, see the -F (--preferences-file) option.
• -p device, --pcm-device= — The device to use for digital audio. For ALSA it's name[:argument,...]. For other interfaces it's the full path to an appropriate system device. The built-in default is:
  • FreeBSD — /dev/dsp
  • Linux/ALSA — hw:0,0
  • Linux/OSS — /dev/dsp
  • NetBSD — /dev/audio
  • OpenBSD — /dev/audio
  • Qnx — the preferred PCM output device
  • Solaris — /dev/audio
• -q, --quiet — Suppress the start-up messages. This is done by reducing the default log level (see the -l (--log-level=) option) to warning (information if either -v (--verify) or -V (--version) is also specified).
• -r, --release-device — Release the device to which the braille display is connected when the current screen or window can't be read.
• -s driver,...|auto, --speech-driver= — The driver for the speech synthesizer (see Driver Specification). The built-in default is auto.
• -t table, --text-table= — The path to the text table. Relative paths are anchored at /etc/brltty/Text. The .ttb extension is optional. The built-in default is en-nabcc.ttb (the North American Braille Computer Code).
• -v, --verify — Print the start-up messages and then exit. This always includes the versions of brltty itself, the server side of its application programming interface, and each of the selected braille and speech drivers. If the -q (--quiet) option isn't also specified then it also includes the values of the options after all sources have been considered. If more than one braille driver and/or more than one braille device has been specified then braille display autodetection is performed. If more than one speech driver has been specified then speech synthesizer autodetection is performed.
• -x driver, --screen-driver= — The screen driver. The built-in default is operating system appropriate.
• -A name=value,..., --api-parameters= — Parameters for the application programming interface. If the same parameter is specified more than once then the rightmost specification is used. Parameter names may be abbreviated.
• -B [driver:]name=value,..., --braille-parameters= — Parameters for the braille display driver. If the same parameter is specified more than once then the rightmost specification is used. Parameter names may be abbreviated. If a parameter assignment is qualified with a driver identification code then it's only processed if that braille display driver is being used.
• -D directory, --drivers-directory= — The path to the directory which contains the dynamically loadable driver objects. The built-in default is /usr/lib64/brltty.
• -E, --environment-variables — Recognize environment variables.
• -F file, --preferences-file= — The path to the preferences file. Relative paths are anchored at /var/lib/brltty. The built-in default is brltty.prefs.
• -H, --full-help — Print a command line usage summary (all options), and then exit.
• -I, --install-service — (Windows only) Install brltty as the BrlAPI service so that it will be automatically started when the system is booted, and so that applications can know that a BrlAPI server is running.
• -K arg, --keyboard-properties= — Properties of the keyboard.
• -L file, --log-file= — The file to which log messages are written. Relative paths are anchored at the current working directory. The default is to send log messages to the system log.
• -M csecs, --message-delay= — The message hold time in hundredths of a second. The built-in default is 400 (4 seconds).
• -N, --no-api — Don't start the application programming interface.
• -P file, --pid-file= — The full path to the process identifier file. If this option is supplied, brltty writes its process identifier (pid) into the specified file at start-up. The file is removed when brltty terminates.
• -R, --remove-service — (Windows only) Remove the BrlAPI service so that brltty will not be automatically started when the system is booted, and so that applications can know that no BrlAPI server is running.
• -S [driver:]name=value,..., --speech-parameters= — Parameters for the speech synthesizer driver. If the same parameter is specified more than once then the rightmost specification is used. Parameter names may be abbreviated. If a parameter assignment is qualified with a driver identification code then it's only processed if that speech synthesizer driver is being used.
• -T directory, --tables-directory=directory — where the tables live, bestie: text, contraction, attributes, keyboard, and input tables all chill in this directory. Built-in default is /etc/brltty.
• -U directory, --updatable-directory=directory — the directory holding files that can be updated. Built-in default is /var/lib/brltty.
• -V, --version — prints the versions of brltty itself, the server side of its application programming interface, and every driver that got configured in at build-time, then dips out. And if you didn't also pass -q (--quiet), it prints copyright info too. 💅
• -W directory, --writable-directory=directory — the directory that can be written to. Built-in default is /run/brltty.
• -X name=value,..., --screen-parameters= — parameters for the screen driver. If you specify the same parameter more than once, the rightmost one wins (last one standing, periodt). Parameter names may be abbreviated. ✨
• -Y text, --start-message= — the text shown when the braille driver starts, and spoken when the speech driver starts. Built-in default is BRLTTY 6.8.
• -Z text, --stop-message= — the text shown when the braille driver stops. Built-in default is BRLTTY stopped.

---

🌈 Environment Variables 🌈

Okay so these environment variables are recognized if you specify the -E (--environment-variables) option. No -E, no vibes:

• BRLTTY_API_PARAMETERS=name=value,... — parameters for the application programming interface. Peep the -A (--api-parameters=) option for details.
• BRLTTY_ATTRIBUTES_TABLE=table — the attributes table. See the -a (--attributes-table=) option for details.
• BRLTTY_BRAILLE_DEVICE=device,... — the device the braille display is connected to. See the -d (--braille-device=) option for details.
• BRLTTY_BRAILLE_DRIVER=driver,...|auto — the driver for the braille display. See the -b (--braille-driver=) option for details.
• BRLTTY_BRAILLE_PARAMETERS=[driver:]name=value,... — parameters for the braille display driver. See the -B (--braille-parameters=) option for details.
• BRLTTY_CONFIGURATION_FILE=file — the configuration file. See the -f (--configuration-file=) option for details.
• BRLTTY_CONTRACTION_TABLE=table — the contraction table. See the -c (--contraction-table=) option for details.
• BRLTTY_MIDI_DEVICE=device — the device to use for the Musical Instrument Digital Interface. See the -m (--midi-device=) option for details.
• BRLTTY_PCM_DEVICE=device — the device to use for digital audio. See the -p (--pcm-device=) option for details.
• BRLTTY_PREFERENCES_FILE=file — the preferences file. See the -F (--preferences-file=) option for details.
• BRLTTY_RELEASE_DEVICE=on|off — release the device the braille display is connected to when the current screen or window can't be read. See the -r (--release-device) option for details.
• BRLTTY_SCREEN_DRIVER=driver — the screen driver. See the -x (--screen-driver=) option for details.
• BRLTTY_SCREEN_PARAMETERS=name=value,... — parameters for the screen driver. See the -X (--screen-parameters=) option for details.
• BRLTTY_SPEECH_DRIVER=driver,...|auto — the driver for the speech synthesizer. See the -s (--speech-driver=) option for details.
• BRLTTY_SPEECH_INPUT=name — the file system object that gives other applications access to brltty's speech driver for text-to-speech conversion. See the -i (--speech-input=) option for details.
• BRLTTY_SPEECH_PARAMETERS=[driver:]name=value,... — parameters for the speech synthesizer driver. See the -S (--speech-parameters=) option for details.
• BRLTTY_TEXT_TABLE=table — the text table. See the -t (--text-table=) option for details.

---

📝 The Configuration File 📝

Blank lines? Ignored, we don't see them. And if the character # shows up anywhere on a line, everything from that # to the end of the line is treated as a comment. Sashay away, comment text. 🎀

These are the configuration directives that are supported, and yes, all of them:

• api-parameters name=value,... — parameters for the application programming interface. See the -A (--api-parameters=) option for details.
• attributes-table table — the attributes table. See the -a (--attributes-table=) option for details.
• braille-device device,... — the device the braille display is connected to. See the -d (--braille-device=) option for details.
• braille-driver driver,...|auto — the driver for the braille display. See the -b (--braille-driver=) option for details.
• braille-parameters [driver:]name=value,... — parameters for the braille display driver. See the -B (--braille-parameters=) option for details.
• contraction-table table — the contraction table. See the -c (--contraction-table=) option for details.
• midi-device device — the device to use for the Musical Instrument Digital Interface. See the -m (--midi-device=) option for details.
• pcm-device device — the device to use for digital audio. See the -p (--pcm-device=) option for details.
• preferences-file file — the preferences file. See the -F (--preferences-file=) option for details.
• release-device on|off — release the device the braille display is connected to when the current screen or window can't be read. See the -r (--release-device) option for details.
• screen-driver driver — the screen driver. See the -x (--screen-driver=) option for details.
• screen-parameters name=value,... — parameters for the screen driver. See the -X (--screen-parameters=) option for details.
• speech-driver driver,...|auto — the driver for the speech synthesizer. See the -s (--speech-driver=) option for details.
• speech-input 0me — the file system object that gives other applications access to brltty's speech driver for text-to-speech conversion. See the -i (--speech-input=) option for details.

Not me pointing out that this one is written as 0me in the manual and not name — I'm just the messenger, bestie, the typo is not mine. 🙈

• speech-parameters [driver:]name=value,... — parameters for the speech synthesizer driver. See the -S (--speech-parameters=) option for details.
• text-table table — the text table. See the -t (--text-table=) option for details.

---

🔥 Driver Specification 🔥

A braille display driver or a speech synthesizer driver has to be specified by its identification code. Here's the whole roster, alphabetically iconic:

• al — Alva
• an — Android
• at — Albatross
• ba — BrlAPI
• bc — BrailComm
• bd — Braudi
• bl — BrailleLite
• bm — Baum
• bn — BrailleNote
• cb — CombiBraille
• ce — Cebra
• cn — Canute
• dp — DotPad
• ec — EcoBraille
• en — eSpeak-NG
• es — eSpeak
• eu — EuroBraille
• fa — FrankAudiodata
• fl — FestivalLite
• fs — FreedomScientific
• fv — Festival
• gs — GenericSay
• hd — Hedo
• hm — HIMS
• ht — HandyTech
• hw — HumanWare
• ir — Iris
• ic — Inceptor
• lb — Libbraille
• lt — LogText
• mb — MultiBraille
• md — MDV
• mm — BrailleMemo
• mn — MiniBraille
• mp — Mikropuhe
• mt — Metec
• no — no driver
• np — NinePoint
• pg — Pegasus
• pm — Papenmeier
• sd — SpeechDispatcher
• sk — Seika
• sw — Swift
• th — Theta
• tn — TechniBraille Systems Inc.
• ts — Telesensory Systems Inc.
• vd — VideoBraille
• vo — Voyager, Part232 (serial adapter), BraillePen/EasyLink
• vs — VisioBraille
• vv — ViaVoice
• xs — ExternalSpeech

You can hand it a comma-delimited list of drivers. If you do that, autodetection happens using each listed driver in sequence. And heads up — you might genuinely need to experiment to figure out the most reliable order, because some drivers autodetect better than others. It's giving trial and error, and that's okay. 💖

If you specify the single word auto, then autodetection is performed using only those drivers that are known to be reliable for this purpose. Lowkey the safe pick.

---

👀 SEE ALSO 👀

For the full documentation, go look at brltty's on-line manual at [http://brltty.app/documentation.html].

---

That's the whole page, bestie, you made it to the end and you ate. 💅✨

This manual page is for brltty version 6.8, and it's dated July 2025. Slay, go forth, and may your display autodetect on the first try. 🦋