Apple Music in your terminal. Vibe-driven. Keyboard-first.
If you enjoy vibez, consider supporting its development — it helps keep the project alive! ☕
Installation · Usage · Features · Key Bindings · Roadmap
vibez is an open-source TUI Apple Music player for Linux and macOS. Search, queue, and control playback entirely from the keyboard.
Full tracks stream via Chrome with Widevine DRM. On Linux amd64, Chrome is auto-downloaded into vibez's private cache; on Linux arm64, vibez uses a system-installed Chromium plus a system Widevine CDM (Google publishes no arm64 Chrome for Linux). Where neither is available, WebKit + GStreamer remains available as a 30-second preview backend. On macOS, install Google Chrome before using Apple Music playback.
- Full-track streaming via headless Chrome + Widevine DRM — the real deal, not 30-second clips
- Linux preview backend via WebKit + GStreamer (30 s previews) when CDP playback is not selected
- Playback controls — play/pause, next, previous, seek ±10 s, volume up/down
- Repeat modes — cycle through off, repeat-all, and repeat-one
- Shuffle — randomise your queue with a single keypress
- Browse your library — playlists, albums, and tracks all in one place
- Real-time catalog search — find any song, album, or artist from the full Apple Music catalog as you type
- Secure authentication — MusicKit OAuth flow via an embedded Chrome window
- Add tracks to queue with
tabfrom search, library, or recommendation feed - Play next — insert any song, album, playlist, or recommendation next in the queue with
shift+tab - Navigate the queue — jump to any track or let it auto-advance
- Persistent queue panel — toggle it on/off without losing your place
- Desktop notifications — see the current track in your notification area
- MPRIS D-Bus on Linux — desktop media keys and notifications integrate with supported desktop environments
- No external music player needed — vibez does not depend on Cider, VLC, or Music.app
- Last.fm scrobbling — optional integration; connect with
vibez auth lastfm loginand your listening history is tracked automatically - WSL2 support — set
"wsl": truein config to enable audio workarounds for WSL2 environments
- Describe music in plain English — press
v, type your mood or activity ("late night coding", "Sunday morning chill"), and vibez builds a queue of matching tracks - Keyword-based mood engine — maps your description to a mood, energy level, genres, and multiple search query variants for variety
- Diverse results — runs several searches and shuffles up to 15 tracks into your queue so it never feels repetitive
- Works for any occasion — focus, workout, party, road trip, heartbreak, romance, and more
- Continuous automatic queuing — press
dto turn on discovery mode; vibez finds a similar track as soon as the last song in the queue starts playing, so the music never stops. Trigger timing will be fully configurable in a future release - Adjustable similarity — use
+/-to dial between "same artist" (0.9) and "pure discovery" (0.0), giving you full control over how adventurous the next pick is - Seed-aware — the currently playing track is used as the seed; searches adapt progressively from same artist → same genre → completely random as similarity decreases
- Toggle anytime — press
dagain to stop discovery and return to a manual queue
- Seed a station from any track — press
Ron the currently playing track, a highlighted queue track, orctrl+ron a search result to start an endless station built around it - Auto-refills like discovery — vibez queues up new picks from the seed's station as the queue runs low, so the music never stops
- Clears the runway — starting radio drops any tracks still queued after the seed (e.g. the rest of an album or playlist) so the station takes over immediately instead of waiting for them to finish
- Toggle anytime — press
Ragain to stop radio and return to a manual queue
- Fully keyboard-driven — every action reachable without touching the mouse
- Vim-style command mode — press
:to run commands like:save <name>,:vol 80,:mute, or:q/:quitto exit - Vim-style navigation —
ggto jump to top,Gto jump to bottom,j/kfor list scrolling in panels - Animated bear mascot 🐻 — sleeps when idle, dances when music is playing
- Built with Bubble Tea — a modern, composable TUI framework
- Provider architecture — the player core is decoupled from the music source
- More services coming — Spotify, YouTube Music, Deezer, and Tidal are on the roadmap
- 10-band parametric EQ — press
eto open a full-width equalizer panel - Per-band control — adjust frequency (32 Hz–16 kHz), Q factor, and gain (±12 dB) for each band
- Live preview — changes apply immediately to the audio stream via Web Audio API
- Persistent settings — your EQ curve is saved to
~/.config/vibez/config.jsonand restored on next launch
- Built-in themes —
default(Tokyo Night / Catppuccin),dracula,gruvbox,nord - Custom themes — create your own palette as a JSON file in
~/.config/vibez/themes/<name>.json
curl --proto '=https' --tlsv1.2 -sSf \
https://raw.githubusercontent.com/simonepelosi/vibez/main/scripts/install.sh | shInstalls the latest release binary to ~/.local/bin/ and updates your shell profile if needed.
You can also inspect the script before running it — that's always a good idea.
Covers Linux x86-64 and macOS (Apple Silicon and Intel). Linux/arm64 has no published binary yet — build from source instead.
Update: re-running the same command updates vibez to the latest release.
Custom install dir:
VIBEZ_INSTALL_DIR=/usr/local/bin curl ... | sh
Install Google Chrome before using Apple Music playback on macOS:
brew install --cask google-chromegit clone https://github.com/simonepelosi/vibez
cd vibez
make build-with-token # requires APPLE_KEY_ID, APPLE_TEAM_ID, APPLE_PRIVATE_KEY
make install # same, plus copies the binary to ~/.local/binmake install reads those credentials from the environment or a gitignored
.env, so the copy on your PATH is rebuilt rather than left to go stale.
Embedded tokens expire after 30 days — re-run it when the catalog starts
returning 401s. Override the location with make install PREFIX=/usr/local.
Requirements: Linux x86-64 or arm64, or macOS · Go 1.26+ · WebKit/GStreamer development packages on Linux · Google Chrome on macOS · on Linux arm64, a system Chromium + Widevine CDM for full-track playback (e.g. pacman -S chromium widevine) · Apple Developer Account with a MusicKit key
vibez # launch the TUI
vibez --demo # try vibez with built-in fake tracks — no account needed
vibez auth login # open Apple ID login (Chrome window)
vibez auth status # check current auth state
vibez auth logout # clear saved tokens
vibez auth lastfm login # connect your Last.fm account (optional)
vibez auth lastfm status # check Last.fm connection status
vibez auth lastfm logout # disconnect Last.fm
vibez version # print version
 default (Tokyo Night / Catppuccin) |
 dracula |
 gruvbox |
 nord |
Set the theme key in ~/.config/vibez/config.json:
{
"theme": "dracula"
}Built-in themes: default, dracula, gruvbox, nord
Create ~/.config/vibez/themes/<name>.json with any subset of fields — missing or invalid values fall back to default:
{
"primary": "#ff79c6",
"secondary": "#50fa7b",
"muted": "#6272a4",
"error": "#ff5555",
"fg": "#f8f8f2",
"subtle": "#8be9fd",
"bg": "#282a36",
"love": "#ff6e6e",
"active": "#50fa7b",
"progress": "#8be9fd",
"surface": "#44475a",
"accent": "#bd93f9",
"accent_warm": "#f1fa8c",
"bear": "#ffb86c",
"glow_palette": ["#282a36","#383a52","#44475a","#6272a4","#9580ff","#bd93f9","#caa9fa","#e9e0ff"],
"mode_normal_bg": "#50fa7b",
"mode_search_bg": "#8be9fd",
"mode_command_bg": "#f1fa8c",
"mode_chip_fg": "#282a36"
}Then set "theme": "<name>" in config.json and restart vibez.
| Key | Action |
|---|---|
space |
Play / Pause |
n |
Next track |
p |
Previous track |
← / → |
Seek backward / forward 10 s |
+ / = |
Volume up |
- |
Volume down |
r |
Cycle repeat (off → all → one) |
s |
Toggle shuffle |
f |
Heart / favourite current track |
v |
Open vibe input (mood-driven search) |
e |
Toggle equalizer panel |
d |
Toggle discovery mode |
R |
Toggle radio mode (seeded by the currently playing track) |
/ |
Open search |
l |
Toggle library panel |
q |
Toggle queue panel |
:q / ctrl+c |
Quit |
| Key | Action |
|---|---|
| (type) | Filter results in real time |
↑ / ↓ |
Navigate results |
enter |
Play now |
tab |
Add to queue |
shift+tab |
Play next (insert after current track) |
ctrl+r |
Start radio seeded by the selected track |
esc |
Close |
| Key | Action |
|---|---|
↑ / ↓ |
Navigate list |
enter |
Open / play |
tab |
Add selected item/track to queue (when viewing albums/artists/playlists/tracks) or switch tab (when viewing library sections pane) |
shift+tab |
Play next (insert selected item/track after current track) |
esc |
Back / close |
| Key | Action |
|---|---|
↑ / ↓ |
Navigate list |
enter |
Play selected track |
d |
Remove track from queue |
K / shift+up |
Move track up |
J / shift+down |
Move track down |
c |
Clear entire queue |
s |
Save queue as playlist (opens command prompt) |
R |
Toggle radio mode (seeded by the highlighted track) |
esc |
Close |
Vim-style command mode — press : from anywhere to open the command prompt.
| Command | Description |
|---|---|
:save <name> |
Save the current queue as an Apple Music playlist |
:discover <n>|auto |
Queue n discovered songs now, or keep auto-discovering |
:vol <0-100> |
Set volume to an absolute level (e.g. :vol 80) |
:vol +n / :vol -n |
Raise or lower volume by n percent (e.g. :vol +10) |
:vol |
Show current volume in the status bar |
:art |
Toggle the album-art view: the cover (rendered as coloured half-blocks) with track, album, and elapsed time in place of the progress bar |
:mute |
Toggle mute (run again to restore the previous volume) |
| `:quality <high | standard |
:seek <seconds> |
Jump to an absolute position in the current song |
:debug-logs |
Toggle the debug log panel |
:q / :quit |
Quit vibez |
Use ↑ / ↓ (or ctrl+p / ctrl+n) to cycle through suggestions, and tab to autocomplete.
| Key | Action |
|---|---|
+ / = |
Increase similarity (stay closer to current artist / genre) |
- |
Decrease similarity (explore further afield) |
d |
Stop discovery mode |
| Key | Action |
|---|---|
← / → |
Navigate between bands |
↑ / ↓ |
Increase / decrease gain (±0.5 dB per step) |
0 |
Reset current band to flat (0 dB) |
r |
Reset all bands to flat |
e |
Close equalizer panel |
| Engine | Tracks | How it works |
|---|---|---|
| Chrome + Widevine | Full tracks | Chrome (amd64) or system Chromium (arm64) via Playwright; MusicKit JS + Widevine DRM |
| WebKit + GStreamer (Linux fallback) | 30 s previews | Embedded webkit2gtk-4.1; GStreamer decodes preview URLs |
On Linux amd64, Chrome is downloaded once to ~/.cache/vibez/chrome. On Linux arm64, vibez uses the system Chromium with a persistent profile in ~/.cache/vibez/chromium-arm64 and a system-registered Widevine CDM (registered on a one-time warm-up launch). The Playwright driver is stored in ~/.cache/vibez/driver. On macOS, vibez uses an installed Google Chrome app.
Running vibez inside WSL2 can cause audio underruns or sample-rate distortion because the Hyper-V scheduler introduces jitter and PulseAudio / Windows may run at mismatched rates (44 100 Hz vs 48 000 Hz).
Enable the WSL2 workaround by adding "wsl": true to ~/.config/vibez/config.json:
{
"wsl": true
}When enabled, vibez launches Chrome with:
| Flag | Purpose |
|---|---|
--audio-buffer-size=4096 |
Larger buffer absorbs Hyper-V scheduler jitter |
--disable-features=…,AudioServiceOutOfProcess |
Disables out-of-process audio service that causes distortion at mismatched sample rates |
The flag is false by default so native Linux users are unaffected.
Set audio_quality in ~/.config/vibez/config.json:
{
"audio_quality": "high"
}Supported values: "high"/"256" for 256 kbps AAC (default), "standard"/"64" for 64 kbps AAC. MusicKit JS/web playback maxes out at 256 kbps AAC; lossless and Hi-Res/ALAC are not available through the Chrome/CDP backend. WebKit + GStreamer uses fixed 30 s preview URLs and cannot change bitrate at runtime.
vibez/
├── cmd/ # CLI entry points (cobra)
├── internal/
│ ├── config/ # Config file management
│ ├── auth/ # MusicKit OAuth flow
│ ├── lastfm/ # Last.fm scrobbling (optional)
│ ├── provider/ # Provider interface + Apple Music implementation
│ ├── player/
│ │ ├── cdp/ # Chrome CDP player (Widevine, full tracks)
│ │ ├── webkit/ # WebKit player (30 s previews, Linux)
│ │ ├── gst/ # GStreamer decoder (Linux)
│ │ └── mpris/ # Linux MPRIS D-Bus server
│ ├── tui/
│ │ ├── model.go # Bubble Tea model + key handling
│ │ ├── views/ # Search, queue, library, now-playing, bear
│ │ └── styles/ # Lipgloss colour palette
│ └── vibe/ # Vibe agent: mood → search query
└── scripts/
└── gen-devtoken/ # Apple MusicKit JWT generator
- Queue management (add, navigate, auto-advance)
- Last.fm scrobbling
- Spotify provider
- YouTube Music provider
- LLM-powered vibe agent (OpenAI / Ollama)
- Lyrics display
- Desktop notifications on track change
Open an issue before sending a PR — happy to discuss ideas.
git clone https://github.com/simonepelosi/vibez
cd vibez
go mod tidy
# Linux
PKG_CONFIG_PATH=$PWD/pkg-config go build ./...
PKG_CONFIG_PATH=$PWD/pkg-config go test ./...
PKG_CONFIG_PATH=$PWD/pkg-config go run . --demo
# macOS
go build ./...
go test ./...
go run . --demoMIT © Simone Pelosi