Linux terminal control for AirPods. Battery, listening modes, conversation awareness, ear detection, microphone selection, button mappings, audio profile/codec/volume, Bluetooth lifecycle — all behind short commands.
podctl status full snapshot
podctl b battery
podctl m anc noise cancellation
podctl v 60 volume 60 %
podctl watch live event stream
podctl debug paste-friendly diagnostic report
Daemon + CLI are wired end-to-end. The Apple Accessory Protocol channel
(L2CAP PSM 0x1001) is implemented from scratch — no external bluetooth
crate. Battery, in-ear detection, listening mode, conversation
awareness, AutoANC strength, one-bud-ANC and the mic-selection setting
are real on-device against AirPods Pro 2 USB-C. Audio (volume / mute /
profile / codec / default sink / latency) goes through PipeWire /
PulseAudio. BlueZ basics (list, connect, disconnect, pair, unpair,
trust) shell out to bluetoothctl; rename writes the BlueZ Alias
property via dbus-send.
podctld also does the host-side part an iPhone would: taking a bud out
pauses whatever MPRIS player is playing and putting it back resumes it
(tied to podctl ear). Conversation awareness uses the AirPods' own
speech detection with a volume stage of podctl's own: it measures how
loud the music really plays and fades it to a level you can talk over,
more for loud music, less for quiet (tied to podctl conv).
Spatial audio, loud-sound reduction and the per-bud press-action / tone-on-press configs are not implemented — their AAP setting IDs aren't pinned down yet, and asking for one answers with a clear error rather than pretending. Press events (which bud, how many taps) are likewise unimplemented: the parser exists, the opcode doesn't.
Two optional desktop components ship alongside the CLI:
podctl-tray— a StatusNotifierItem whose icon shows both buds over a level bar, and a menu that leads with the name and a line per bud and the case, then the listening modes, volume, audio output and the settings your model has. A middle click toggles noise cancellation against transparency, the wheel changes the volume, and low levels warn per bud in two steps. Works on Plasma, Hyprland/waybar, sway, Xfce, MATE; GNOME needs the AppIndicator extension.podctl-popup— the case-open bubble. Slides in at the bottom of the screen, shows model + L / R / Case rings, auto-hides after 5.5 seconds (duration_msin~/.config/podctl/popup.toml). Backend is auto-detected (wlr-layer-shell on Hyprland / KDE / sway / Wayfire, a small shell extension on GNOME 46–51, X11 override-redirect on i3 / Xfce / MATE, freedesktop Notification as the last resort).
podctl-popup rendered headlessly via podctl-popup --dump, so what you
see is the actual frame the compositor would draw.
| Dark | Light |
|---|---|
![]() |
![]() |
The tray menu as podctl-tray --demo half lays it out, drawn in the
default style rather than captured from one desktop's theme:
| Dark | Light |
|---|---|
![]() |
![]() |
Prebuilt, statically linked binaries for x86_64 and aarch64 are attached
to every release as a
tarball with a .sha256, a build attestation and an SBOM next to it
(see INSTALL.md). From source:
git clone https://github.com/Rockykln/podctl && cd podctl
cargo build --release
./target/release/podctl install # core: CLI + daemon
./target/release/podctl install --with-tray --with-popup
podctl install puts the binaries in ~/.local/bin/, drops completion in
the right place for your shell (bash/zsh/fish autodetected from $SHELL),
installs man pages, and asks whether you want a systemd user service that
keeps the daemon running. No root needed; podctl uninstall rolls it back.
If ~/.local/bin isn't on your $PATH, the installer prints the line
your shell rc needs.
On Arch, the AUR has podctl-bin (prebuilt release) and podctl-git (latest
main). Both ship the binaries, man pages, completion and systemd user units:
yay -S podctl-bin # or any other AUR helper
systemctl --user enable --now podctld
systemctl --user enable --now podctl-tray podctl-popup # optional
podctl uninstall also handles the AUR install: if the binary lives in
/usr/bin/ it delegates to sudo pacman -R podctl-bin (or podctl-git)
after stopping the user services. Same exit point either way.
Per-distro dependencies and the desktop-compatibility matrix are in INSTALL.md.
podctl is daemon-first but works without one. Every call tries the Unix
socket at $XDG_RUNTIME_DIR/podctl.sock; if the daemon's there, you get
fresh cached state. If not, the CLI falls back to running the audio +
Bluetooth operations in-process.
| Mode | What works | What needs the daemon |
|---|---|---|
| Daemon up | Everything | — |
| Standalone | audio (volume / mute / profile / codec / default / latency), Bluetooth (list, connect, disconnect, pair, unpair, auto-connect, rename), status snapshot without live battery |
podctl watch, live AAP state (battery, in-ear, mode echo), every AAP setter (mode, conv, mic, ear, one-bud-anc, auto-anc, chime) |
Skip the daemon on install: podctl install --no-daemon. Re-enable it
later by re-running podctl install (idempotent).
| Feature | 1/2/3 | 4 | 4 ANC | Pro | Pro 2 | Pro 3 | Max |
|---|---|---|---|---|---|---|---|
| Battery L / R / C | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | L / R |
| ANC / Transparency | — | — | ✓ | ✓ | ✓ | ✓ | ✓ |
| Adaptive | — | — | ✓ | — | ✓ | ✓ | — |
| Conversation Awareness | — | — | ✓ | — | ✓ | ✓ | — |
| In-Ear Detection | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — |
| Loud-Sound Reduction | — | — | ✓ | — | ✓ | ✓ | ✓ |
| Spatial Audio | 3 / 4 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Press-and-Hold | — | — | ✓ | ✓ | ✓ | ✓ | ✓ |
| Microphone Selection | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — |
| Rename | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
Source of truth for this matrix is src/caps.rs::Model::capabilities.
AirPods Max (2nd gen, 0x202D) shares the original Max capability row.
AirPods 4 (non-ANC) is not in the table yet: its product code 0x2019
is known, the capability row is not, so the bud shows up via the BlueZ
headphones icon and resolves to Unknown until a capture lands.
podctl refuses commands the connected device can't do with a clear
not supported on <model> error rather than silently failing.
podctl help top-level list
podctl help <cmd> detailed page
podctl <cmd> --help same
podctl --json <cmd> machine-readable response (every command)
| Command | What it does |
|---|---|
podctl status (s) |
full snapshot |
podctl battery (b) |
battery levels |
podctl ping |
daemon health |
| Command | What it does |
|---|---|
podctl mode <off|anc|transparency|adaptive|next> |
switch noise-control; next goes round the modes the model has, without off |
podctl conv <on|off> |
conversation awareness (daemon lowers the volume while you talk) |
podctl spatial <off|fixed|head-tracked> |
spatial-audio mode |
| Command | What it does |
|---|---|
podctl ear <on|off> |
in-ear detection: pause on removal, resume on return |
podctl mic <auto|left|right> |
microphone selection |
podctl loud-reduction <on|off> |
cap loud sound spikes (4 ANC, Pro 2, Pro 3, Max) — AAP id TBD |
podctl press <left|right> <mode-cycle|siri|none> |
stem long-press — AAP id TBD |
podctl tone <on|off> |
acoustic feedback on press — AAP id TBD |
podctl rename "name" |
bluetooth name |
podctl one-bud-anc <on|off> |
keep ANC active when only one bud is in |
podctl auto-anc <less-noise|default|more-noise> |
how much noise Adaptive lets in (switches to Adaptive) |
podctl chime <0..100> |
system tone / chime volume |
| Command | What it does |
|---|---|
podctl connect / podctl disconnect (dc) |
bring the link up/down |
podctl pair / podctl unpair (forget) |
BlueZ pairing |
podctl list (ls) |
paired AirPods on this adapter |
podctl auto-connect <on|off> |
BlueZ trusted/auto-connect flag |
| Command | What it does |
|---|---|
podctl volume <0..100|+N|-N> (v) |
audio sink volume, set or stepped |
podctl mute <on|off> |
mute toggle |
podctl profile <high|headset|off> (p) |
audio profile |
podctl codec <sbc|aac|aptx|ldac|…> |
A2DP codec |
podctl default |
set as default sink |
podctl latency <ms> |
sink latency offset |
| Command | What it does |
|---|---|
podctl watch (w) |
live event stream — Ctrl-C to stop |
podctl meter [--plain|--json] [--interval N] |
live RMS / peak dBFS of audio going to the buds (software meter, not SPL) |
podctl ble [on|off] |
listen for the case over Bluetooth LE (see below) |
podctl completion <bash|zsh|fish> |
emit completion script |
podctl debug [--no-redact] |
diagnostic report (DSGVO-redacted by default) |
podctl tray <start|stop|status|restart> |
status-bar icon (podctl-tray) |
podctl popup |
show the case-open bubble now (podctl-popup) |
podctl reboot |
restart the running podctld, tray and popup |
podctl install [--with-tray] [--with-popup] / podctl uninstall |
installer / rollback |
podctl version (-V) |
CLI + daemon version |
podctl help [cmd] |
this list / detailed page |
mode next and volume +5 need no idea of where the AirPods are now,
so they fit on a key:
# Hyprland (hyprland.conf)
bind = SUPER, N, exec, podctl mode next
bind = SUPER, equal, exec, podctl volume +5
bind = SUPER, minus, exec, podctl volume -5
# sway (config)
bindsym $mod+n exec podctl mode next
bindsym $mod+equal exec podctl volume +5
bindsym $mod+minus exec podctl volume -5On KDE Plasma: System Settings → Keyboard → Shortcuts → Add New → Command or
Script, with podctl mode next as the command.
podctl debug is meant to be pasted into a bug report. Identifying data
is redacted by default:
- MAC addresses → only the Apple OUI (first three bytes) shown
- custom Bluetooth names →
<custom name redacted>(default Apple names like "AirPods Pro" pass through) $HOMEpaths →~,/run/user/<uid>masked- the journal lines at the end → host name, user name and serial numbers taken out
Use podctl debug --no-redact for local diagnostics only. Note that
podctl status --json is not redacted: it carries the full address
and the serial numbers.
Apple's BLE manufacturer-data prefix (0x4C 0x00 0x07 0x19 …) carries
proximity-pair info — the bytes that identify the model before any
classic-Bluetooth connection exists. Once connected, AirPods accept an
L2CAP SeqPacket socket on PSM 0x1001 (Apple Accessory Protocol).
Frames are:
04 00 04 00 <opcode> <subop> <payload …>
Battery (0x04) and in-ear (0x06) arrive unsolicited, as do settings
echoes (0x09); those same families are written back to change a
setting. Button presses are not wired up — aap::parse_press and the
press counts block in podctl status are ready for it, but no press
opcode has been confirmed yet, so the counters stay at zero and
podctl watch never emits a press event. See src/aap.rs for the
opcode table.
The classic Bluetooth link takes three to five seconds to come back after the case opens — long enough that the bubble shows up once you already have a bud in your ear. The case says it much earlier: while the lid moves it advertises over Bluetooth LE, battery levels included, the same announcement an iPhone listens for. The daemon listens for it too, but only while the buds are disconnected, and the bubble now appears as the lid opens.
Those announcements go out under an address that changes with every lid
open, so every Apple device nearby produces them. The buds hand out their
identity resolving key over AAP once, on a link you already own; the key
lands in ~/.local/state/podctl/keys-<address> with mode 0600 and
never leaves the machine. Only an address that resolves against it is
read — everyone else's stays an anonymous packet that is counted and
dropped. Nothing is sent anywhere, and the encrypted tail of the
advertisement is not touched.
To switch the listening off:
podctl ble off # podctl ble on to listen again, podctl ble to ask
That writes ble = false to ~/.config/podctl/daemon.toml, which can be
edited by hand just as well. A running daemon notices within a few
seconds; nothing needs restarting.
Without the key file there is no scanning either: delete it and the
daemon asks for a new one on the next connect, unless ble = false.
- Find My — Apple iCloud only
- Personalized Spatial Audio — proprietary HRTF
- Hearing Test — iOS-only flow
- Announce Notifications via Siri — needs Siri
The bud still accepts the underlying setting toggles, but the rendering doesn't exist on Linux.
Four binaries linking one library crate.
src/
caps.rs per-model capability matrix
model.rs domain types
ipc.rs daemon ↔ cli wire types
audio.rs PipeWire/PulseAudio via pactl
bluez.rs BlueZ via bluetoothctl
aap.rs Apple Accessory Protocol
l2cap.rs raw AF_BLUETOOTH SEQPACKET socket
aes.rs AES-128 single block (FIPS-197)
ble.rs proximity advertisement + address resolving
keys.rs the buds' proximity keys on disk
config.rs ~/.config/podctl/daemon.toml
exitcode.rs BSD sysexits.h
lib.rs re-exports
bin/
podctl.rs CLI entry
podctld.rs daemon entry
help.rs help text
fmt.rs output formatting
completion.rs shell completion emitter
debug.rs diagnostic report (`podctl debug`)
install.rs podctl install / uninstall
meter.rs podctl meter (sink capture)
standalone.rs no-daemon fallback dispatcher
tray_cli.rs podctl tray start/stop/status/restart wrapper
daemon/
mod.rs request dispatch + state
server.rs Unix-socket accept loop
link.rs BlueZ + PipeWire poll loop
aap.rs L2CAP runtime + AAP frame pump
scan.rs BLE listener for the case lid
media.rs auto-pause + ducking on the host
tray/ podctl-tray binary (SNI + DBusMenu)
popup/ podctl-popup binary (wlr-layer-shell / X11 / notify)
Wire format between CLI and daemon: newline-delimited JSON, one request
per line, one response per line. watch opens a long-lived subscription
that streams Events.
- AAP captures for spatial audio, loud-sound reduction, and the per-bud press-action / tone-on-press setting IDs (the four unimplemented settings listed under Status)
- AAP captures from AirPods 4 ANC and AirPods Max to confirm the capability matrix beyond Pro 2 USB-C
- AUR packages (
podctl-bin,podctl-git) - deb and rpm packages
MIT OR Apache-2.0. See LICENSE-MIT and LICENSE-APACHE.
Inspired by LibrePods (GPL-3.0); no GPL code is included.



