Send a Test XKB Bell with xkbbell Without Surprises

You will send one XKB bell request to a chosen X display, with a named bell and optional device, feedback, volume or window settings. You will also test the request without making a sound, which is the sensible first pass on a shared desk or remote session.

Allow about ten minutes. You need the x11-xkb-utils package, an X display that accepts your connection, and permission to use that display. The installed package here is x11-xkb-utils 7.7+8build2; the program reports xkbbell (xkbutils) 1.0.5. This guide sends a transient X request only. It does not change keyboard configuration or a system service.

1. Check the installed command

Start with read-only checks. No elevated privileges are needed:

$ command -v xkbbell
/usr/bin/xkbbell
$ xkbbell -version
xkbbell (xkbutils) 1.0.5

The option syntax uses one hyphen, including -display, -nobeep and -version. The command also requires a final name argument. Keep that argument last. For these examples, use the literal name test-bell; it is the label sent with the request, not a path or a file to create.

Checkpoint: if xkbbell -version does not print a version, stop and inspect the package installation before troubleshooting the X display.

2. Select a display explicitly

If you are working in the current graphical session, DISPLAY may already identify it:

$ printf 'display: %s\n' "${DISPLAY:-unset}"
display: :0

For a different local or authorised remote display, set a shell variable to the display name you were given. Replace the placeholder; do not guess a remote display or copy an untrusted value into a privileged script:

$ DISPLAY_NAME=':0'
$ xkbbell -display "$DISPLAY_NAME" -nobeep test-bell

There is no normal output on success. The -nobeep option suppresses the server bell while still requesting an event. Capture the status immediately:

$ printf 'exit status: %s\n' "$?"
exit status: 0

If the command says it could not open the display, check the display name and the X authorisation context. sudo is not a general fix: running as another user can remove the authorisation that your graphical session provides.

3. Send an audible bell only after the quiet test

$ xkbbell -display "$DISPLAY_NAME" test-bell
$ printf 'exit status: %s\n' "$?"
exit status: 0

With no device or feedback option, xkbbell uses the default values for the core keyboard device. A successful status means the request was accepted by the XKB extension. It does not prove that a particular physical speaker is connected or that the desktop sound policy will make the bell audible.

To undo this example, do nothing: the request has no persistent setting to revert. If the sound is unwelcome, stop using the audible form and return to -nobeep.

4. Add one option at a time

Once the basic request works, add only the value you need. The options below describe the target of the request:

• -dev ID selects an input device ID.
• -bf ID selects a bell feedback ID.
• -kf ID selects a keyboard feedback ID.
• -v VOLUME selects a volume from -100 through 100.
• -w ID selects a window ID.

These IDs are numeric where the program says so. Do not substitute a window title, device name or arbitrary label. Obtain the value from the X tooling that manages your session, then test it quietly:

$ DEVICE_ID='REPLACE_WITH_NUMERIC_DEVICE_ID'
$ xkbbell -display "$DISPLAY_NAME" -dev "$DEVICE_ID" -nobeep test-bell
$ printf 'exit status: %s\n' "$?"
exit status: 0

The same pattern applies to -bf, -kf and -w. A volume-only example is:

$ xkbbell -display "$DISPLAY_NAME" -v 25 -nobeep test-bell
$ printf 'exit status: %s\n' "$?"
exit status: 0

Do not assume that -v 25 changes a desktop mixer or a saved preference. It is a value for this request. The installed program rejects values outside the documented range.

5. Use forced bells carefully

-force asks for an audible bell even when the ordinary bell request would not be audible. It is useful for testing the server's forced-bell path, but it is easy to mistake for a normal volume or feedback setting. The program warns that the name is ignored for forced bell requests.

Keep the first forced test quiet with -nobeep, then remove that option only when an audible test is acceptable:

$ xkbbell -display "$DISPLAY_NAME" -force -nobeep test-bell
$ printf 'exit status: %s\n' "$?"
exit status: 0

If you need to test a named bell, do not combine that test with -force, because the name is deliberately ignored on that path.

6. Diagnose failures without guessing

Run the command again with the smallest failing set of options. The messages identify several common mistakes:

• Must specify a display with -display option means no usable display was supplied.
• Must specify a volume for -v means the option's value is missing.
• Volume must be in the range -100..100 means the value is outside the installed program's range.
• Keyboard feedback ID must be an integer, Bell feedback ID must be an integer or Must specify a numeric window ID means the relevant argument is not numeric.
• Bell name must be the last argument means an option or value was placed after test-bell.

For a clean syntax check, ask for help without a display. The command prints its usage and exits with status 1, because help is handled as a command-line error path in this release:

$ xkbbell -help
Usage: xkbbell [ <options> ] <name>
$ printf 'exit status: %s\n' "$?"
exit status: 1

Do not interpret that help status as an X display failure. For a real request, check the display error and the request status separately.