budctl

Control your wireless earbuds from Linux, without the vendor app: noise control, EQ, game mode, touch controls, battery and more. There is a command-line tool, budctl, and a desktop app, budctl-gui, both built on the same library.

• No telemetry and no account. budctl talks to your buds over Bluetooth, through BlueZ.
• The settings live on the buds, so budctl works alongside the phone app.

Supported buds: realme Buds T310. More are added as the author gets them.

Install

You need Rust 1.88 or newer, BlueZ, and for the desktop app a Wayland desktop.

cargo install --path crates/budctl-cli    # budctl
cargo install --path crates/budctl-gui    # budctl-gui
cp contrib/budctl.desktop ~/.local/share/applications/

Pair the buds and connect them in your Bluetooth settings first.

Command line

budctl list                                # paired buds, and whether budctl knows them
budctl status                              # battery, noise control, EQ, switches
budctl anc off|on|transparency             # noise control
budctl anc light|medium|deep               # noise cancelling, at this strength
budctl eq                                  # the EQ presets, and the one in use
budctl eq deep-bass                        # select a preset
budctl eq custom-4 50=+3 16000=-2          # change bands of a custom preset (dB)
budctl game on|off                         # game mode (low latency)
budctl set bass-boost|spatial|wind|dual on|off
budctl dual                                # the phones and computers dual connection keeps
budctl bass 2                              # bass level, -5 to +5
budctl touch                               # what each tap and hold does
budctl touch left triple-tap previous      # give a gesture an action (--dry-run first, if you like)
budctl touch cycle off anc                 # the modes a hold steps through
budctl find start --yes                    # ring the buds (loud: take them out of your ears)
budctl find stop

• --json prints machine-readable output for scripts and status bars ("schema": 1).
• --debug hex-dumps every frame sent and received, on stderr.
• --device <MAC> picks the buds when more than one supported pair is connected.

Exit codes:

Desktop app

budctl-gui has five pages:

• Overview: battery, noise control, the switches.
• Equalizer: presets, the bands of your custom presets, the bass level.
• Gestures: what each tap and hold does on each bud, and what a hold steps through.
• Earbud settings: dual connection and the devices it keeps, find my earbuds, firmware, audio codec.
• App settings.

The app connects when it needs to, and frees the buds' control channel 10 s after your last change, so other apps can use it. A change shows "Saving…" until the buds confirm it.

The mouse works everywhere. Vim-like keys work on top of it (press ? in the window):

The cursor shows only after you press a key, and the first key only shows it.

Colors: a built-in dark palette with a red accent, or a matugen palette: --theme <file>, else ~/.config/budctl/theme.json. The file is JSON with these keys, all optional: bg, fg, primary, primaryFg, primaryContainer, secondary, surfaceLow, surface, surfaceHigh, surfaceHighest, outlineVariant, surfaceVariantFg, err. It is read again whenever the window gets focus, so a new wallpaper's colors show up there too.

Other options: --demo shows made-up buds without Bluetooth; --debug and --device work as in the command-line tool.

How it works

budctl speaks the buds' own control protocol over an RFCOMM socket. What is known about it, and how sure, is written down in docs/protocol/: the transport and the realme Buds T310.

License

GPL-3.0-or-later. See LICENSE.