KEYBARS PRO

Using keybars Pro

keybars Pro is a desktop app that lights your keyboard with the music, your builds, your coding agents, a focus timer and calm scenes. It hears what your computer plays and talks to the keyboard itself, so there’s no cava, loopback driver or Keymapp to set up. This guide covers the window; the command line has every command for scripts and terminals.

Install

SystemDownloadThen
Fedora and other RPM systems.rpmsudo dnf install ./keybars-pro-*.rpm
Ubuntu, Debian.debsudo apt install ./keybars-pro_*.deb
Other Linux.tar.gzsee the tarball
macOS 14.2 or later.dmgdrag keybars Pro to Applications
Windows 10 or 11.zipunzip it to a folder of its own and run keybars-pro.exe

The macOS app runs on Apple silicon and Intel Macs; the Linux and Windows downloads are for 64-bit Intel and AMD (x86_64) only. The Linux packages need glibc 2.39 or later (Fedora 40, Ubuntu 24.04 and newer), with GTK 4 and WebKitGTK 6, which the package manager brings. They put the app in /usr/lib/keybars-pro, the keybars-pro command on your PATH, an entry in your applications, and a udev rule that lets whoever is at the computer drive ZSA keyboards over USB.

First open on macOS and Windows

The app isn’t notarised by Apple or signed for Windows yet, so the first open asks you to confirm:

  • macOS says it can’t check keybars Pro for malicious software. Open it once, then go to System Settings > Privacy & Security and choose Open Anyway beside keybars Pro.
  • Windows SmartScreen says it protected your PC. Choose More info, then Run anyway.

You only do this once.

The Linux tarball

The .tar.gz has the app, keybars-pro-cli, and the desktop entry and udev rule in build/linux/. Keep keybars-pro and keybars-pro-cli in the same folder, since each finds the other beside itself. For ZSA keyboards, install the rule and reload udev:

sudo cp build/linux/70-keybars-pro.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger --subsystem-match=hidraw

First run

The window opens on the startup checks: the keyboard, its map, the sound and the mode. Each ticks green as it connects. A failed one says why and how to fix it, with Retry and a way to report it.

Then a short guide checks your keyboard and the sound and shows where things are. App settings > Setup > Run again brings it back.

The header is the same on every page:

  • What plays: the picker that says what has the keyboard, and switches it.
  • The status pill: what’s connected. Green is fine, amber is working on it, red needs you. It opens Devices.
  • On: the switch that hands the keyboard back to its own layout, and lights it again.

Closing the window leaves keybars Pro in the tray. On GNOME, tray icons need the AppIndicator extension; without a tray, closing the window quits.

Keyboards

ZSA keyboards

The Moonlander, Voyager and Planck EZ connect over USB with no other software. The built-in maps cover every key, thumbs included. The Planck EZ’s map comes from QMK and hasn’t been checked on a real board yet.

On Linux the package’s udev rule gives you the keyboard; if it isn’t found, unplug it and plug it back in once after installing. Quit Keymapp while keybars Pro runs, or both will set the keys: Devices warns when Keymapp, OpenRGB or the free keybars command line could change them too.

Other keyboards, through OpenRGB

For any other per-key RGB keyboard, run OpenRGB with its SDK server on (openrgb --server, or Start Server on its SDK Server tab). keybars Pro tries a ZSA board first, then OpenRGB at 127.0.0.1:6742; the Equaliser’s Keys settings pick one or set another address.

A keyboard’s map says which LED sits under which key. keybars Pro uses, in order: a map you saved for that keyboard, a map generated from QMK for a keyboard of that name and LED count (Keychron’s Q and V series, the GMMK Pro, Drop’s CTRL and ALT, the Corne, Sofle, Kyria and more), OpenRGB’s key matrix, then OpenRGB’s key names on a full-size layout. OpenRGB’s matrix for a QMK board follows its wiring or rows of LEDs, which can lean the bars or stack a split board’s halves, so QMK’s map comes first. Keyboards draws every board with a map.

QMK keyboards reach OpenRGB only when their firmware speaks VialRGB (Vial) or the QMK-OpenRGB protocol, which stock firmware usually doesn’t.

Find keys

When the map’s wrong, or there isn’t one, Find keys (in the Equaliser’s Keys settings, or on Devices) lights one LED at a time while you click that key on the on-screen keyboard. It saves the map for that keyboard, and Forget my map goes back to the built-in one. Share on Devices makes the map a .keybars file for the marketplace.

Sound

keybars Pro records what your computer plays, not the microphone:

  • Linux: the PipeWire or PulseAudio monitor of your output.
  • macOS: a Core Audio tap. macOS asks once to let keybars Pro record system audio; if you said no, allow it in System Settings > Privacy & Security.
  • Windows: WASAPI loopback of the default output.

Nothing it hears is recorded or sent anywhere. To listen to another source, change it in the Equaliser’s settings. Run test plays a 30-second piece made in the app, so you can check the keyboard with no music or speakers.

What plays

One thing has the keyboard at a time: the Equaliser, System’s CPU bars, an Ambient scene, or Typing. Pick it from the header on any page, from the tray, or with keybars-pro play. The alert rules, Focus and the timer play on top of whichever it is, and a dot in the sidebar marks the page that’s playing.

When what plays changes, the keyboard fades from one to the next. App settings > Transitions sets how long: Off, Quick, Smooth (1 second, to start), Slow, or anything up to 5 seconds.

Equaliser

The music as bars across the keys, with every setting beside a preview that plays each change as you make it: the bars’ colours as a preset or your own gradient, brightness, peak dots that hold and fall, smoothing, gain (higher reaches the top more often), the frequency range and frame rate. Under Keys are the keyboard and its map, how many rows the bars use, keys to leave alone, and split boards mirrored with the bass in the middle or at the edges.

Now playing shows the track from your music app: MPRIS on Linux, Music and Spotify on macOS, the media controls on Windows. Import… loads a keybars config file, a link from the config builder, or a settings file keybars Pro saved; you can also drop a file on the window or paste a link. Share look… saves your look as a .keybars file, and Reset to defaults starts again.

Alerts

Alerts light keys when something happens. A rule names an event, paints keys and picks a colour and an effect; when the event arrives, the keys play over whatever’s on the keyboard. The higher rule wins a key two of them light.

EffectPlays for, unless the rule says otherwise
Flash0.9 s, on and off
Wave, Ripple1.5 s, a sweep or rings from each key
Pulse, Sparkle, Fade3 s
Hold, Breathe, Chaseuntil it clears

Give a rule a time and its effect plays that long: a flash keeps flashing, a wave or ripple starts again, a fade slows to fill it, and a held effect clears after it. A held rule also clears on the events you name, such as ci.passed, or by hand. Any of the others can play until cleared too, repeating until then.

Events come from keybars-pro alert and run on this computer, from GitHub, Codeberg or any Forgejo server, from any webhook, and from System’s limits. Connect on the Alerts page sets each one up. GitHub and Forgejo give a webhook address and secret to paste into a repository’s settings; Any webhook gives an address for deploy hooks, monitors, Home Assistant or a script on another machine. They reach keybars Pro through a relay while the app is open.

Coding agents lights one key you pick while Claude Code, Codex, Gemini CLI, Cursor, OpenCode or Aider works, waits for you, or finishes. Set up for me adds hooks to the agent’s own settings, beside the hooks already there, after backing the file up to <file>.keybars-backup.

The History tab lists the last 100 events and the rules they played. One that matched a rule but never lit the keys, because the lights were off or Focus kept it quiet, is marked missed. An event no rule matched offers Make a rule. Find packs opens rule packs in the marketplace, and Share makes your rules into one.

System

System reads the computer each second: each CPU core’s load, memory in use and the hottest temperature. Play it to show the cores as bars in place of the music, in their own colours. Its limits send cpu.high, memory.high and temperature.high to Alerts, and the .normal event when they fall back, so a held rule clears itself. macOS doesn’t give apps a temperature.

Focus and timers

Focus is a pomodoro timer along the top row, which the bars leave free. The time left drains across it, then the break breathes there in its own colour. While you work it can dim every key but the home row, and let only held alert rules play, so a failed build still shows but nothing flashes. Start it from its page, the tray, or keybars-pro focus start.

The timer, on the same page, is a countdown across the top two rows, green to amber to red, that flashes when it’s done. It plays over whatever has the keyboard.

Typing

Typing lights your key presses in place of the music, on ZSA boards: a ripple from each key, an afterglow that fades, or a heatmap of today’s presses. A gauge fills the number row toward a target speed. The keyboard reports only where a key is, never what it types.

Ambient

Ambient loops a calm scene or a clock on the keyboard, with no music or events needed:

  • Scenes: rain, zen, autumn wind, aurora, ocean, fireflies, snowfall, embers, box breathing, lava lamp, starfield, falling code and sunrise, and Snake, Pong and falling blocks playing themselves.
  • Clocks: rows, ring, spelled and binary, which you read off the keys.

Scenes shows each one playing, with the marketplace scenes made from it.

It starts dim (40%) to stay calm; brightness, speed and each scene’s colours change on its page. When the music stops plays the scene whenever the bars go quiet, in place of the keyboard’s own layout. Share makes the scene and your colours for it a .keybars file.

New scene… opens the scene maker: paint the keys frame by frame, or start from scrolling text or a fade between colours, then play it back with fading between frames. You can keep up to 30 scenes of your own.

Marketplace

The marketplace has looks, rule packs, Ambient scenes, key maps and integrations, from keybars and from people who use it. In the app, Marketplace lists them by type, popular or latest, with search and an Installed view.

  • Try plays a look on your keyboard for 10 seconds, or a pack’s rules one after another, without saving anything.
  • Install applies it, and Remove undoes exactly what it changed.
  • Each file is signed by keybars.app and checked before it’s used; items are data, never code.

Offline, keybars’ own items are still there. To publish your own, see publishing.

Devices

Devices has the details behind the status pill: the keyboard, how it’s connected and its frame rate, the map in use, the sound source, OpenRGB, and any warning. The frame rate drops by itself while the keyboard or the computer can’t keep up. An unplugged keyboard reconnects by itself, and the keys go back to their layout before the computer sleeps.

The tray

The tray menu says what the keys show and switches what plays, the Ambient scene and the theme. It runs Focus, turns the lights off for a while or until you turn them back on, and opens the problem report and feature forms.

App settings

  • Licence: activate, move or buy a licence. See Free and Pro.
  • Appearance: light, dark or your system’s, one of six themes for the window and tray icon, a different theme each launch, and Match the keyboard to light the bars in the theme.
  • Command line: puts keybars-pro on your PATH, where the Linux packages haven’t already. See the command line.
  • App: start in the tray, run the setup guide again, transitions, the daily update check, and the open source licences.
  • Help: report a problem, suggest a feature, copy diagnostics, the version and the changelog.

Free and Pro

keybars Pro is free to use with the essentials: the equaliser in green at full brightness, with the settings it needs to work (the audio source, gain, keyboard, map and bar height). Every other setting and mode works in the preview, so you see it before you buy; a licence puts it on the keyboard.

A licence is US$29 once (€29, £24 or A$45, tax included), with a year of updates. Buy a licence in App settings opens the checkout, and the key arrives by email. Paste it into App settings > Licence and choose Activate.

  • Three computers per licence. Deactivate frees this one. When a key’s active on another computer, Activate here moves it.
  • Checked offline. After activating, the app never checks the licence online again.
  • After the year, everything you have keeps working in every release. Only modes added since need another year, at half price, and the app says which they are. Renew any time after your year ends: you lose nothing by waiting, and the new year starts the day you buy. It comes as a new key; activate it the same way.

Ask within 14 days of buying for a full refund.

Updates

Once a day keybars Pro asks keybars.app whether a newer release is out, and the header says so when one is. The request carries nothing about you, and App settings > Check for updates turns it off. Install a new release the same way as the first; your settings stay. The changelog lists what’s in each.

Where things are kept

Settings and everything else the app keeps live in one folder:

SystemFolder
Linux~/.config/keybars-pro
macOS~/Library/Application Support/keybars-pro
Windows%AppData%\keybars-pro

settings.json is the settings, which you can share. The folder also has the alert history, today’s typing, what you installed from the marketplace, and the relay’s addresses and secrets, readable only by you.

If something’s wrong

  • The keyboard isn’t found. On Linux, unplug it and plug it back in after installing; with the tarball, install the udev rule. Quit Keymapp. For other keyboards, check OpenRGB’s SDK server is running. Retry in the window starts the checks again.
  • The bars stay dark. Run test: if the keys light, the sound is the problem, so check the audio source and, on macOS, the recording permission. If they don’t, see Devices.
  • Some keys are in the wrong place. Use Find keys.
  • There’s no tray icon on GNOME: add the AppIndicator extension.
  • Anything else: App settings > Report a problem sends what went wrong with the app’s diagnostics, with your licence key, tokens, email addresses and names taken out. The form shows exactly what’s sent. Or write to support@jwarykowski.dev.