Next Previous Contents

## 4. Using BRLTTY

Before starting BRLTTY, you need to set up your braille display. In most cases this is done simply by connecting it to an available serial port, and then turning it on. After your display has been set up, run BRLTTY simply by typing the command `brltty` at a shell prompt (this must be done as root). Check the -d command line option, the braille-device configuration file directive, and the --with-braille-device build option for alternatives regarding how to tell BRLTTY which device your display is connected to. Check the -b command line option, the braille-driver configuration file directive, and the --with-braille-driver build option for alternatives regarding how to tell BRLTTY which kind of braille display you have. Check the -B command line option, and the braille-parameters configuration file directive for alternatives regarding how to pass parameters to the driver for your braille display.

A message giving the program name (BRLTTY) and its version number will appear briefly (see the -M command line option) on the braille display. The display will then show a small area of the screen including the cursor. By default, the cursor is represented as dots 7 and 8 superimposed on the character it is on.

Any screen activity will be reflected on the braille display. The display will also follow the progress of the cursor on the screen. This feature is known as cursor tracking.

Just typing on the keyboard and reading the display, however, isn't enough. Try entering a command which will cause an error, and pressing enter. The error appears on the screen, but, unless you have a multi-line display, the chances are that it isn't visible on the braille display. All you see thereon is another shell prompt. What's needed, then, is some way to move the braille window around the screen. The keys on the braille display itself can be used to send commands to BRLTTY which, in addition to a lot of other things, can also do exactly that.

## 4.1 Commands

Unfortunately, the various braille displays don't offer a standard set of controls. Some have the six standard dot keys, some have eight, and others have none. Some have thumb keys, but there's no standard number of them. Some have a button above each braille cell. Some have rocker switches. Some have an easy-to-reach bar which works much like a joystick. Most have varying combinations of the above. Because the nature and layout of each display is so different, please refer to the documentation for your particular display in order to find out exactly what its keys do.

BRLTTY commands are referred to by name within this manual. If you forget which key(s) on your braille display to use for a particular command, then refer to its driver's help page. The main key you should immediately commit to memory, therefore, is the one for the HELP command. Use the regular motion keys (as described below) to navigate the help page, and press the `help` key again to quit.

### Vertical Motion

See also the PRINDENT/NXINDENT, and the PRDIFCHAR/NXDIFCHAR routing key commands.

LNUP/LNDN

  Go up/down one line. If identical line skipping has been activated (see the SKPIDLNS command), then these commands, rather than moving exactly one line, are aliases for the PRDIFLN/NXDIFLN commands.

WINUP/WINDN

  Go up/down one window. If the window is only 1 line high then move 5 lines.

PRDIFLN/NXDIFLN

  Go up/down to the nearest line with different content. If identical line skipping has been activated (see the SKPIDLNS command), then these commands, rather than skipping identical lines, are aliases for the LNUP/LNDN commands.

ATTRUP/ATTRDN

  Go up/down to the nearest line with different attributes (character highlighting).

TOP/BOT

  Go to the top/bottom line.

TOP_LEFT/BOT_LEFT

  Go to the top-left/bottom-left corner.

PRPGRPH/NXPGRPH

  Go to the nearest line of the previous/next paragraph (the first non-blank line beyond the nearest blank line). The current line is included when searching for the inter-paragraph space.

PRPROMPT/NXPROMPT

  Go to the previous/next command prompt.

PRSEARCH/NXSEARCH

  Search backward/forward for the nearest occurrence of the character string within the cut buffer (see Cut and Paste) which isn't within the braille window. The search proceeds to the left/right, starting at the character immediately to the left/right of the window, and wrapping at the edge of the screen. The search isn't case sensitive.

### Horizontal Motion

See also the SETLEFT routing key command.

CHRLT/CHRRT

  Go left/right one character.

HWINLT/HWINRT

  Go left/right half a window.

FWINLT/FWINRT

  Go left/right one window. These commands are particularly useful because they automatically wrap when they reach the edge of the screen. Other features, like their ability to skip blank windows (see the SKPBLNKWINS command), further enhance their usefulness.

FWINLTSKIP/FWINRTSKIP

  Go left/right to the nearest non-blank window.

LNBEG/LNEND

  Go to the beginning/end of the line.

### Implicit Motion

See also the GOTOMARK routing key command.

HOME

  Go to where the cursor is.

BACK

  Go back to where the most recent motion command put the braille window. This is an easy way to get right back to where you were reading after an unexpected event (like cursor tracking) moves the braille window at an inopportune moment.

RETURN

  - If the most recent motion of the braille window was automatic, e.g. as a result of cursor tracking, then go back to where the most recent motion command put it (see the BACK command).
  - If the cursor isn't within the braille window then go to where the cursor is (see the HOME command).

### Feature Activation

Each of these commands has three forms: activate (turn the feature on), deactivate (turn the feature off), and toggle (if it's off then turn it on, and if it's on then turn it off). Unless specifically noted, each of these features is initially off, and, when on, affects BRLTTY's operation as a whole. The initial setting of some of these features can be changed via the preferences menu.

FREEZE

  Freeze the screen image. BRLTTY makes a copy of the screen (content and attributes) as of the moment when the screen image is frozen, and then ignores all updating of the screen until it's unfrozen. This feature makes it easy, for example, to sample the output of an application which writes too much too quickly.

DISPMD

  Show the highlighting (the attributes) of each character within the braille window, rather than the characters themselves (the content). This feature is useful, for example, when you need to locate a highlighted item. When showing screen content, the text table is used (see the -t command line option, the text-table configuration file directive, and the --with-text-table build option). When showing screen attributes, the attributes table is used (see the -a command line option, the attributes-table configuration file directive, and the --with-attributes-table build option). This feature only affects the current virtual terminal.

SIXDOTS

  Show characters using 6-dot, rather than 8-dot, braille. Dots 7 and 8 are still used by other features like cursor representation and highlighted character underlining. If a contraction table has been selected (see the -c command line option and the contraction-table configuration file directive), then it is used. This setting can also be changed with the Text Style preference.

SLIDEWIN

  If cursor tracking (see the CSRTRK command) is on, then, whenever the cursor moves too close to (or beyond) either end of the braille window, horizontally reposition the window such that the cursor, while remaining on that side, is nearer the centre. If this feature is off, then the braille window is always positioned such that its left end is a multiple of its width from the left edge of the screen. This setting can also be changed with the Sliding Window preference.

SKPIDLNS

  Rather than explicitly moving exactly one line either up or down, skip past lines which have the same content as the current line. This feature affects the LNUP/LNDN commands, as well as the line wrapping feature of the FWINLT/FWINRT and FWINLTSKIP/FWINRTSKIP commands. This setting can also be changed with the Skip Identical Lines preference.

SKPBLNKWINS

  Skip past blank windows when reading either forward or backward. This feature affects the FWINLT/FWINRT commands. This setting can also be changed with the Skip Blank Windows preference.

CSRVIS

  Show the cursor by superimposing a dot pattern (see the CSRSIZE command) on top of the character where it is. This feature is initially on. This setting can also be changed with the Show Cursor preference.

CSRHIDE

  Hide the cursor (see the CSRVIS command) in order to accurately read the character beneath it. This feature only affects the current virtual terminal.

CSRTRK

  Track (follow) the cursor. If the cursor moves to a location which isn't within the braille window, then automatically move the braille window to the cursor's new location. You'll usually want this feature turned on since it minimizes the effects of screen scrolling, and since, during input, the region wherein you're currently typing is always visible. If this feature causes the braille window to jump at an inopportune moment, then use the BACK command to get back to where you were reading. You may need to turn this feature off when using an application which continually updates the screen while maintaining a fixed data layout. This feature is initially on. This feature only affects the current virtual terminal.

CSRSIZE

  Represent the cursor with all eight dots (a solid block), rather than with just dots 7 and 8 (an underline). This setting can also be changed with the Cursor Style preference.

CSRBLINK

  Blink (turn on and off according to a predefined interval) the symbol representing the cursor (see the CSRVIS command). This setting can also be changed with the Blinking Cursor preference.

ATTRVIS

  Underline (with combinations of dots 7 and 8) highlighted characters.

  no underline

    White on black (normal), gray on black, white on blue, black on cyan.

  dots 7 and 8

    Black on white (reverse video).

  dot 8

    Everything else.

  This setting can also be changed with the Show Attributes preference.
ATTRBLINK

  Blink (turn on and off according to a predefined interval) the attribute underline (see the ATTRVIS command). This feature is initially on. This setting can also be changed with the Blinking Attributes preference.

CAPBLINK

  Blink (turn on and off according to a predefined interval) capital (uppercase) letters. This setting can also be changed with the Blinking Capitals preference.

TUNES

  Play a short predefined tune (see Alert Tunes) whenever a significant event occurs. This feature is initially on. This setting can also be changed with the Alert Tunes preference.

AUTOREPEAT

  Automatically repeat a command at a regular interval after an initial delay while its key (combination) remains pressed. Only some drivers support this functionality, the primary limitation being that many braille displays don't signal key presses and key releases as distinctly separate events. This feature is initially on. This setting can also be changed with the Autorepeat preference.

AUTOSPEAK

  Automatically speak:

  - the new line when the braille window is moved vertically.
  - characters which are entered or deleted.
  - the character to which the cursor is moved.
  This feature is initially off. This setting can also be changed with the Autospeak preference.

### Mode Selection

HELP

  Switch to the braille display driver's help page. This is where you can find an on-line summary of things like what your braille display's keys do, and how to interpret its status cells. Use the regular vertical and horizontal motion commands to navigate the help page. Invoke the `help` command again to return to the screen.

INFO

  Switch to the status display (see section The Status Display for full details). It presents a summary including the position of the cursor, the position of the braille window, and the states of a number of BRLTTY's features. Invoke this command again to return to the screen.

LEARN

  Switch to command learn mode (see section Command Learn Mode for full details). This is how you can interactively learn what your braille display's keys do. Invoke this command again to return to the screen. This command isn't available if the --disable-learn-mode build option was specified.

### Preference Maintenance

PREFMENU

  Switch to the preferences menu (see The Preferences Menu for full details). Invoke this command again to return to normal operation.

PREFSAVE

  Save the current preferences settings (see Preferences for full details).

PREFLOAD

  Restore the most recently saved preferences settings (see Preferences for full details).

### Menu Navigation

MENU_FIRST_ITEM/MENU_LAST_ITEM

  Go to the first/last item in the menu.

MENU_PREV_ITEMMENU_NEXT_ITEM/

  Go to the previous/next item in the menu.

MENU_PREV_SETTING/MENU_NEXT_SETTING

  Decrement/increment the current menu item's setting.

### Speech Controls

SAY_LINE

  Speak the current line. The Say-Line Mode preference determines if pending speech is discarded first.

SAY_ABOVE

  Speak the top portion of the screen (ending with the current line).

SAY_BELOW

  Speak the bottom portion of the screen (starting with the current line).

MUTE

  Stop speaking immediately.

SPKHOME

  Go to where the speech cursor is.

SAY_SLOWER/SAY_FASTER

  Decrease/increase the speech rate (see also the Speech Rate preference). This command is only available if a driver which supports it is being used.

SAY_SOFTER/SAY_LOUDER

  Decrease/increase the speech volume (see also the Speech Volume preference). This command is only available if a driver which supports it is being used.

### Speech Navigation

SPEAK_CURR_CHAR

  a

### Virtual Terminal Switching

See also the SWITCHVT routing key command.

SWITCHVT_PREV/SWITCHVT_NEXT

  Switch to the previous/next virtual terminal.

### Other Commands

CSRJMP_VERT

  Route (bring) the cursor to anywhere on the top line of the braille window (see Cursor Routing for full details). The cursor is moved by simulating vertical arrow-key presses. This command doesn't always work because some applications either move the cursor somewhat unpredictably or use the arrow keys for purposes other than cursor motion. It's somewhat safer than the other cursor routing commands, though, because it makes no attempt to simulate the left- and right-arrows.

PASTE

  Insert the characters within the cut buffer at the current cursor location (see Cut and Paste for full details).

RESTARTBRL

  Stop, and then restart the braille display driver.

RESTARTSPEECH

  Stop, and then restart the speech synthesizer driver.

### Character Commands

ROUTE

  Route (bring) the cursor to the character associated with the routing key (see Cursor Routing for full details). The cursor is moved by simulating arrow-key presses. This command doesn't always work because some applications either move the cursor somewhat unpredictably or use the arrow keys for purposes other than cursor motion.

CUTBEGIN

  Anchor the start of the cut block at the character associated with the routing key (see Cut and Paste for full details). This command clears the cut buffer.

CUTAPPEND

  Anchor the start of the cut block at the character associated with the routing key (see Cut and Paste for full details). This command doesn't clear the cut buffer.

CUTRECT

  Anchor the end of the cut block at the character associated with the routing key, and append the rectangular region to the cut buffer (see Cut and Paste for full details).

CUTLINE

  Anchor the end of the cut block at the character associated with the routing key, and append the linear region to the cut buffer (see Cut and Paste for full details).

COPYCHARS

  Copy the character block anchored by the two routing keys to the cut buffer (see Cut and Paste for full details).

APNDCHARS

  Append the character block anchored by the two routing keys to the cut buffer (see Cut and Paste for full details).

PRINDENT/NXINDENT

  Go up/down to the nearest line which isn't indented more than the column associated with the routing key.

DESCCHAR

  Momentarily (see the -M command line option) display a message describing the character associated with the routing key. It reveals the decimal and hexadecimal values of the character, the foreground and background colours, and, when present, special attributes (`bright` and `blink`). The message looks like this:

  > `char 65 (0x41): white on black bright blink`

SETLEFT

  Horizontally reposition the braille window so that its left edge is at the column associated with the routing key. This feature makes it very easy to put the window exactly where it's needed, and, therefore, for displays which have routing keys, almost eliminates the need for a lot of elementary window motion (like the CHRLT/CHRRT and HWINLT/HWINRT commands).

PRDIFCHAR/NXDIFCHAR

  Go up/down to the nearest line which has a different character in the column associated with the routing key.

### Base Commands

SWITCHVT

  Switch to the virtual terminal whose number (counting from 1) matches that of the routing key. See also the SWITCHVT_PREV/SWITCHVT_NEXT virtual terminal switching commands.

SETMARK

  Mark (remember) the current position of the braille window in a register associated with the routing key. See the GOTOMARK command. This feature only affects the current virtual terminal.

GOTOMARK

  Move the braille window to the position formerly marked (see the SETMARK command) with the same routing key. This feature only affects the current virtual terminal.

## 4.2 The Configuration File

System defaults for many settings may be established within a configuration file. The default name for this file is `/etc/brltty.conf`, although it may be overridden with the -f command line option. It doesn't need to exist. A template for it can be found within the `Documents` subdirectory.

Blank lines are ignored. A comment begin with a number sign (`#`), and continues to the end of the line. The following directives are recognized:

`api-parameters` name`=`value`,`...

  Specify parameters for the Application Programming Interface. If the same parameter is specified more than once, then its rightmost assignment is used. For a description of the parameters accepted by the interface, please see the BrlAPI reference manual. See the --with-api-parameters build option for the defaults established during the build procedure. This directive can be overridden with the -A command line option.

`attributes-table` file

  Specify the attributes table (see section Attributes Tables for details). If a relative path is supplied, then it's anchored at `/etc/brltty` (see the --with-data-directory and the --with-execute-root build options for more details). The `.atb` extension is optional. The default is to use the built-in table (see the --with-attributes-table build option). This directive can be overridden with the -a command line option.

`braille-device` device`,`...

  Specify the device to which the braille display is connected (see section Braille Device Specification). See the --with-braille-device build option for the default established during the build procedure. This directive can be overridden with the -d command line option.

`braille-driver` driver`,`...|`auto`

  Specify the braille display driver (see section Driver Specification). The default is to perform autodetection. This directive can be overridden with the -b command line option.

`braille-parameters` [driver`:`]name`=`value`,`...

  Specify parameters for the braille display drivers. If the same parameter is specified more than once, then its rightmost assignment is used. If a parameter name is qualified by a driver (see section Driver Identification Codes) then that setting only applies to that driver; if it isn't then it applies to all drivers. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. See the --with-braille-parameters build option for the defaults established during the build procedure. This directive can be overridden with the -B command line option.

`contraction-table` file

  Specify the contraction table (see section Contraction Tables for details). If a relative path is supplied, then it's anchored at `/etc/brltty` (see the --with-data-directory and the --with-execute-root build options for more details). The `.ctb` extension is optional. The contraction table is used when the 6-dot braille feature is activated (see the SIXDOTS command and the Text Style preference). The default is to display uncontracted 6-dot braille. This directive can be overridden with the -c command line option. It isn't available if the --disable-contracted-braille build option was specified.

`keyboard-table` file|`auto`

  Specify the keyboard table (see section Key Tables for details). If a relative path is supplied, then it's anchored at `/etc/brltty` (see the --with-data-directory and the --with-execute-root build options for more details). The `.ktb` extension is optional. The default is not to use a keyboard table. This directive can be overridden with the -k command line option.

`keyboard-properties` name`=`value`,`...

  Specify the properties of the keyboard(s) to be monitored. If the same property is specified more than once, then its rightmost assignment is used. See section Keyboard Properties for a list of the properties which may be specified. The default is to monitor all keyboards. This directive can be overridden with the -K command line option.

`midi-device` device

  Specify the device to use for the Musical Instrument Digital Interface (see section MIDI Device Specification). This directive can be overridden with the -m command line option. It isn't available if the --disable-midi-support build option was specified.

`pcm-device` device

  Specify the device to use for digital audio (see section PCM Device Specification). This directive can be overridden with the -p command line option. It isn't available if the --disable-pcm-support build option was specified.

`preferences-file` file

  Specify the location of the file which is to be used for the saving and loading of user preferences. If a relative path is supplied, then it's anchored at `/var/lib/brltty`. The default is to use `brltty.prefs`. This directive can be overridden with the -F command line option.

`release-device` boolean

  Whether or not to release the device to which the braille display is connected when the current screen or window can't be read.

  on

    Release the device.

  off

    Don't release the device.

  The default setting is `on` on Windows platforms and `off` on all other platforms. This directive can be overridden with the -r command line option.
`screen-driver` driver

  Specify the screen driver (see section Supported Screen Drivers). See the --with-screen-driver build option for the default established during the build procedure. This directive can be overridden with the -x command line option.

`screen-parameters` [driver`:`]name`=`value`,`...

  Specify parameters for the screen drivers. If the same parameter is specified more than once, then its rightmost assignment is used. If a parameter name is qualified by a driver (see section Supported Screen Drivers) then that setting only applies to that driver; if it isn't then it applies to all drivers. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. See the --with-screen-parameters build option for the defaults established during the build procedure. This directive can be overridden with the -X command line option.

`speech-driver` driver`,`...|`auto`

  Specify the speech synthesizer driver (see section Driver Specification). The default is to perform autodetection. This directive can be overridden with the -s command line option. It isn't available if the --disable-speech-support build option was specified.

`speech-input` name

  Specify the name of the file system object (FIFO, named pipe, named socket, etc) which can be used by other applications for text-to-speech conversion via BRLTTY's speech driver. This directive can be overridden with the -i command line option. It isn't available if the --disable-speech-support build option was specified.

`speech-parameters` [driver`:`]name`=`value`,`...

  Specify parameters for the speech synthesizer drivers. If the same parameter is specified more than once, then its rightmost assignment is used. If a parameter name is qualified by a driver (see section Driver Identification Codes) then that setting only applies to that driver; if it isn't then it applies to all drivers. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. See the --with-speech-parameters build option for the defaults established during the build procedure. This directive can be overridden with the -S command line option.

`text-table` file|`auto`

  Specify the text table (see section Text Tables for details). If a relative path is supplied, then it's anchored at `/etc/brltty` (see the --with-data-directory and the --with-execute-root build options for more details). The `.ttb` extension is optional. The default is to perform locale-based autoselection, with fallback to the built-in table (see the --with-text-table build option). This directive can be overridden with the -t command line option.

## 4.3 Command Line Options

Many settings can be explicitly specified when invoking BRLTTY. The `brltty` command accepts the following options:

`-a` file `--attributes-table=`file

  Specify the attributes table (see section Attributes Tables for details). If a relative path is supplied, then it's anchored at `/etc/brltty` (see the --with-data-directory and the --with-execute-root build options for more details). The `.atb` extension is optional. See the attributes-table configuration file directive for the default run-time setting. This setting can be changed with the Attributes Table preference.

`-b` driver`,`...|`auto` `--braille-driver=`driver`,`...|`auto`

  Specify the braille display driver (see section Driver Specification). See the braille-driver configuration file directive for the default run-time setting.

`-c` file `--contraction-table=`file

  Specify the contraction table (see section Contraction Tables for details). If a relative path is supplied, then it's anchored at `/etc/brltty` (see the --with-data-directory and the --with-execute-root build options for more details). The `.ctb` extension is optional. The contraction table is used when the 6-dot braille feature is activated (see the SIXDOTS command and the Text Style preference). See the contraction-table configureation file directive for the default run-time setting. This setting can be changed with the Contraction Table preference. This option isn't available if the --disable-contracted-braille build option was specified.

`-d` device`,`... `--braille-device=`device`,`...

  Specify the device to which the braille display is connected (see section Braille Device Specification). See the braille-device configuration file directive for the default run-time setting.

`-e` `--standard-error`

  Write diagnostic messages to standard error. The default is to record them via `syslog`.

`-f` file `--configuration-file=`file

  Specify the location of the configuration file which is to be used for the establishing of default run-time settings.

`-h` `--help`

  Display a summary of the command line options accepted by BRLTTY, and then exit.

`-i` name `--speech-input=`name

  Specify the name of the file system object (FIFO, named pipe, named socket, etc) which can be used by other applications for text-to-speech conversion via BRLTTY's speech driver. If not specified, the file system object is not created. See the speech-input configuration file directive for the default run-time setting. This option isn't available if the --disable-speech-support build option was specified.

`-k` file `--keyboard-table=`file

  Specify the keyboard table (see section Key Tables for details). If a relative path is supplied, then it's anchored at `/etc/brltty` (see the --with-data-directory and the --with-execute-root build options for more details). The `.ktb` extension is optional. See the keyboard-table configureation file directive for the default run-time setting. This setting can be changed with the Keyboard Table preference.

`-l` level `--log-level=`level

  Specify the severity threshold for diagnostic message generation. The following levels are recognized.

  0

    emergency

  1

    alert

  2

    critical

  3

    error

  4

    warning

  5

    notice

  6

    information

  7

    debug

  Either the number or the name may be supplied, and the name may be abbreviated. If not specified, then `information` is assumed (see the -q option for more details).
`-m` device `--midi-device=`device

  Specify the device to use for the Musical Instrument Digital Interface (see section MIDI Device Specification). See the midi-device configuration file directive for the default run-time setting. This option isn't available if the --disable-midi-support build option was specified.

`-n` `--no-daemon`

  Specify that BRLTTY is to remain in the foreground. If not specified, then BRLTTY becomes a background process (daemon) after initializing itself but before starting any of the selected drivers.

`-p` device `--pcm-device=`device

  Specify the device to use for digital audio (see section PCM Device Specification). See the pcm-device configuration file directive for the default run-time setting. This option isn't available if the --disable-pcm-support build option was specified.

`-q` `--quiet`

  Log less information. This option changes the default log level (see the -l option) to `notice` if either the -v or the -V option is specified, and to `warning` otherwise.

`-r` `--release-device`

  Release the device to which the braille display is connected when the current screen or window can't be read. See the release-device configuration file directive for the default run-time setting.

`-s` driver`,`...|`auto` `--speech-driver=`driver`,`...|`auto`

  Specify the speech synthesizer driver (see section Driver Specification). See the speech-driver configuration file directive for the default run-time setting. This option isn't available if the --disable-speech-support build option was specified.

`-t` file `--text-table=`file

  Specify the text table (see section Text Tables for details). If a relative path is supplied, then it's anchored at `/etc/brltty` (see the --with-data-directory and the --with-execute-root build options for more details). The `.ttb` extension is optional. See the text-table configureation file directive for the default run-time setting. This setting can be changed with the Text Table preference.

`-v` `--verify`

  Display the current versions of BRLTTY itself, of the server side of its application programming interface, and of the selected braille and speech drivers, and then exit. If the -q option isn't specified, then also display the values of the options after all sources have been considered. If more than one braille driver (see the -b command line option) and/or more than one braille device (see the -d command line option) has been specified then braille display autodetection is performed. If more than one speech driver (see the -s command line option) has been specified then speech synthesizer autodetection is performed.

`-x` driver `--screen-driver=`driver

  Specify the screen driver (see section Supported Screen Drivers). See the screen-driver configuration file directive for the default run-time setting.

`-A` name`=`value`,`... `--api-parameters=`name`=`value`,`...

  Specify parameters for the Application Programming Interface. If the same parameter is specified more than once, then its rightmost assignment is used. For a description of the parameters accepted by the interface, please see the BrlAPI reference manual. See the api-parameters configuration file directive for the default run-time settings.

`-B`[driver`:`]name`=`value`,`... `--braille-parameters=`[driver`:`]name`=`value`,`...

  Specify parameters for the braille display drivers. If the same parameter is specified more than once, then its rightmost assignment is used. If a parameter name is qualified by a driver (see section Driver Identification Codes) then that setting only applies to that driver; if it isn't then it applies to all drivers. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. See the braille-parameters configuration file directive for the default run-time settings.

`-E` `--environment-variables`

  Recognize environment variables when determining the default settings for unspecified command line options (see section Command Line Options). If this option is specified, and if the environment variable associated with an unspecified option is defined, then the value of that environment variable is used. The names of these environment variables are based on the long names of the options they correspond to:

  - All letters are in upper case.
  - Underscores (`_`) are used instead of minus signs (`-`).
  - The prefix `BRLTTY_` is added.
  This option is particularly useful on the Linux operating system as it allows default settings to be passed to BRLTTY via boot parameters. The following environment variables are supported:
  `BRLTTY_API_PARAMETERS`

    Parameters for the Application Programming Interface (see the -A command line option).

  `BRLTTY_ATTRIBUTES_TABLE`

    The attributes table (see the -a command line option).

  `BRLTTY_BRAILLE_DEVICE`

    The braille display device (see the -d command line option).

  `BRLTTY_BRAILLE_DRIVER`

    The braille display driver (see the -b command line option).

  `BRLTTY_BRAILLE_PARAMETERS`

    Parameters for the braille display driver (see the -B command line option).

  `BRLTTY_CONFIGURATION_FILE`

    The configuration file (see the -f command line option).

  `BRLTTY_CONTRACTION_TABLE`

    The contraction table (see the -c command line option).

  `BRLTTY_KEYBOARD_TABLE`

    The keyboard table (see the -k command line option).

  `BRLTTY_KEYBOARD_PROPERTIES`

    The keyboard properties (see the -K command line option).

  `BRLTTY_MIDI_DEVICE`

    The Musical Instrument Digital Interface device (see the -m command line option).

  `BRLTTY_PCM_DEVICE`

    The digital audio device (see the -p command line option).

  `BRLTTY_PREFERENCES_FILE`

    The location of the file which is to be used for the saving and loading of user preferences (see the -F command line option).

  `BRLTTY_RELEASE_DEVICE`

    Whether or not to release the device to which the braille display is connected when the current screen or window can't be read (see the -r command line option).

  `BRLTTY_SCREEN_PARAMETERS`

    Parameters for the screen driver (see the -X command line option).

  `BRLTTY_SPEECH_DRIVER`

    The speech synthesizer driver (see the -s command line option).

  `BRLTTY_SPEECH_INPUT`

    The name of the file system object which can be used by other applications for text-to-speech conversion via BRLTTY's speech driver (see the -i command line option).

  `BRLTTY_SPEECH_PARAMETERS`

    Parameters for the speech synthesizer driver (see the -S command line option).

  `BRLTTY_TEXT_TABLE`

    The text table (see the -t command line option).

`-F` file `--preferences-file=`file

  Specify the location of the file which is to be used for the saving and loading of user preferences. If a relative path is supplied, then it's anchored at `/var/lib/brltty`. See the preferences-file configuration file directive for the default run-time setting.

`-I` `--install-service`

  Install BRLTTY as the BrlAPI service. This means that:

  - BRLTTY will be automatically started when the system is booted.
  - Applications can know that a BrlAPI server is running.
  This option is only supported on the Windows platform.
`-K` name`=`value`,`... `--keyboard-properties=`name`=`value`,`...

  Specify the properties of the keyboard(s) to be monitored. If the same property is specified more than once, then its rightmost assignment is used. See section Keyboard Properties for a list of the properties which may be specified. See the keyboard-properties configuration file directive for the default run-time settings.

`-M` csecs `--message-timeout=`csecs

  Specify the amount of time (in hundredths of a second) that BRLTTY keeps its own internally generated messages on the braille display. If not specified, then `400` (4 seconds) is assumed.

`-N` `--no-api`

  Disable the application programming interface.

`-P` file `--pid-file=`file

  Specify the file wherein BRLTTY is to write its process identifier (pid). If not specified, BRLTTY doesn't write its process identifier anywhere.

`-R` `--remove-service`

  Remove the BrlAPI service. This means that:

  - BRLTTY will not be automatically started when the system is booted.
  - Applications can know that no BrlAPI server is running.
  This option is only supported on the Windows platform.
`-S`[driver`:`]name`=`value`,`... `--speech-parameters=`[driver`:`]name`=`value`,`...

  Specify parameters for the speech synthesizer drivers. If the same parameter is specified more than once, then its rightmost assignment is used. If a parameter name is qualified by a driver (see section Driver Identification Codes) then that setting only applies to that driver; if it isn't then it applies to all drivers. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. See the speech-parameters configuration file directive for the default run-time settings.

`-V` `--version`

  Display the current versions of BRLTTY itself, of the server side of its application programming interface, and of those drivers which have been linked into its binary, and then exit. If the -q option isn't specified, then also display copyright information.

`-X`[driver`:`]name`=`value`,`... `--screen-parameters=`[driver`:`]name`=`value`,`...

  Specify parameters for the screen drivers. If the same parameter is specified more than once, then its rightmost assignment is used. If a parameter name is qualified by a driver (see section Supported Screen Drivers) then that setting only applies to that driver; if it isn't then it applies to all drivers. For a description of the parameters accepted by a specific driver, please see the documentation for that driver. See the screen-parameters configuration file directive for the default run-time settings.

Next Previous Contents