Media Controls

cliamp integrates with operating system media controls. Desktop environments, hardware media keys, and command line tools can control playback, read track metadata, and adjust volume without using the TUI.

Platform Support

Platform	Backend	Requirements
Linux	MPRIS2 over D-Bus	Running D-Bus session bus (provided by most desktop environments and Wayland compositors)
macOS	MPNowPlayingInfoCenter / MPRemoteCommandCenter	None (built-in frameworks)
Other	No-op stub	None

Linux (MPRIS2)

Bus Name

cliamp registers this name:

org.mpris.MediaPlayer2.cliamp

Only one instance can hold this name. If a second cliamp process starts, its MPRIS registration fails without an error message. That instance runs without D-Bus integration.

Playback Control

The org.mpris.MediaPlayer2.Player interface supports all standard transport commands:

playerctl command	Effect
`playerctl play-pause`	Toggle play / pause
`playerctl play`	Resume playback
`playerctl pause`	Pause playback
`playerctl stop`	Stop playback
`playerctl next`	Skip to the next track
`playerctl previous`	Go to the previous track (or restart if more than 3 seconds in)

Seeking

You can seek by an absolute or relative value:

playerctl position 30          # seek to 30 seconds
playerctl position 5+          # seek forward 5 seconds
playerctl position 5-          # seek backward 5 seconds

Desktop widgets with a progress bar receive Seeked signals and stay in sync.

Volume

Volume is available as a linear value from 0.0 to 1.0. Internally, cliamp uses a decibel scale from -30 dB to +6 dB. It converts the values automatically.

playerctl volume               # print current volume (0.0 to 1.0)
playerctl volume 0.5           # set volume to 50%

Setting volume through playerctl updates the player immediately. When you change volume with the TUI + and - keys, D-Bus clients receive the new value on the next tick.

Metadata

cliamp publishes track metadata with standard MPRIS keys:

Key	Description
`mpris:trackid`	D-Bus object path for the current track
`xesam:title`	Track title
`xesam:artist`	Artist name as a list with one entry
`xesam:album`	Album name, when available
`xesam:url`	File path or stream URL
`mpris:artUrl`	Embedded album art from local files, when available
`mpris:length`	Duration in microseconds

Query metadata:

playerctl metadata              # all keys
playerctl metadata artist       # just the artist
playerctl metadata title        # just the title

For live radio streams with ICY metadata, artist and title update when the station sends new track information.

Status

playerctl status                # prints Playing, Paused, or Stopped

Hyprland bindings

Hyprland does not bind XF86Audio* keys by default. Add the following to the Hyprland config, usually ~/.config/hypr/bindings.conf or hyprland.conf, to bind hardware media keys to cliamp through playerctl:

bindl = , XF86AudioPlay,  exec, playerctl --player=cliamp play-pause
bindl = , XF86AudioPause, exec, playerctl --player=cliamp play-pause
bindl = , XF86AudioNext,  exec, playerctl --player=cliamp next
bindl = , XF86AudioPrev,  exec, playerctl --player=cliamp previous

Notes:

bindl runs even when the session is locked. Keys continue to work under hyprlock.
--player=cliamp limits the command to cliamp. Remove the flag to control the most recently active MPRIS player. Use this when cliamp shares the session with browsers or Spotify.
Run hyprctl reload after you edit the configuration.
Install playerctl, for example with pacman -S playerctl or apt install playerctl.

macOS

On macOS, cliamp publishes now-playing information to the system MPNowPlayingInfoCenter. This enables:

Control Centre and Lock Screen media controls
Touch Bar playback buttons
Hardware media keys (play/pause, next, previous)
Bluetooth headphone buttons

Local files with embedded cover art publish that art to Control Centre and Lock Screen media controls. cliamp caches art by content in ~/.local/share/cliamp/album-art/. It removes cached art as needed to keep the cache near 100 MB.

The macOS media-control runtime pins the main goroutine to thread 0 with runtime.LockOSThread. This lets the Cocoa run loop process events. Bubbletea runs on a background goroutine.

Architecture

The application playback command and notifier boundary is in internal/playback. The mediactl package translates platform APIs to and from this boundary. It owns the platform-specific interactive runtime helper.

Platform-specific Service implementations:

internal/playback/*: application playback commands and outbound notifier state.
mediactl/service_linux.go: connects to the session bus, claims the MPRIS bus name, translates D-Bus calls to playback commands, and publishes state through MPRIS properties.
mediactl/service_darwin.go: starts NSApplication as an accessory process, registers MPRemoteCommandCenter handlers, translates them to playback commands, and publishes now-playing state in the main-thread run loop.
mediactl/service_stub.go: no-op implementation for unsupported platforms.

The model sends playback state through the playback notifier when state changes. On Linux, mediactl uses SetMust, not Set, to bypass property-library writable checks and callback triggers. These checks and triggers apply to external D-Bus writes. For writable properties such as Volume, mediactl translates the D-Bus callback to an application playback command. It sends this command to the Bubbletea event loop.

Limitations

cliamp does not expose shuffle and loop status. The TUI z and r keys control shuffle and repeat locally. External tools cannot view or control these states.

On Linux, HasTrackList is false. cliamp does not implement the optional org.mpris.MediaPlayer2.TrackList interface.