applemusic-tui

command module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 25 Imported by: 0

README

applemusic-tui — Apple Music in your terminal, on macOS and Linux

English · Русский

Go 1.26 Platforms

amtui is a terminal Apple Music player — a full TUI client with catalog search, a live audio spectrum visualizer and synced lyrics, running on Linux as well as macOS. It drives the official Apple Music web player inside a hidden Chromium, so playback is the real thing. No DRM hacks: the browser plays the audio legally, amtui just gives it a terminal face.

Why amtui

Terminal Apple Music clients are usually AppleScript remotes for the macOS Music.app: Mac-only, and limited to steering an app that has to be running anyway. amtui talks to Apple Music's web player through MusicKit instead, which changes what is possible:

  • Linux, not just macOS. The same Go binary runs on both. (Linux support is newer — see the note under Requirements.)
  • The full catalog, in the terminal. Search songs, albums and playlists straight from MusicKit — no desktop app in the loop.
  • A real spectrum visualizer. Actual system-audio PCM through an FFT, not a decorative animation.
  • Synced lyrics from LRCLIB, with the album cover rendered next to them.
  • Your credentials stay out of the terminal. You sign in inside a real browser window, so 2FA and captcha just work.

Features

  • Full Apple Music catalog — search songs, albums and playlists, plus your recently played, straight from MusicKit.
  • Queue — jump to any track, append to queue, play next.
  • Recently played — a cover grid under the queue: your last ten albums, playlists and singles as half-block artwork, arrow keys to pick, ↵ to play.
  • Live visualizer — what is actually playing: system-audio PCM through a 4096-sample Hann-window FFT into 32 bands (denser at low frequencies), 30 fps. CoreAudio process tap on macOS, PipeWire/PulseAudio monitor on Linux. Falls back to a clearly labeled simulated animation when live capture is unavailable. Three looks, cycled with v: Winamp-style bars, a spinning torus whose tube corrugates with the spectrum, and a wireframe sphere that turns slowly and pumps with the bass.
  • Synced lyrics — timestamped lines from LRCLIB, no API keys, with the album cover rendered beside them in half-block color.
  • Last.fm scrobbling — optional, off until you set it up. Counts time actually listened, so seeking to the end does not scrobble a track.
  • MPRIS on Linux — media keys, panel widgets, lock screens and playerctl drive it like any desktop player. Appears automatically when there is a session bus.
  • Themes — six built-in palettes cycled with t, overridable per color in a config file, plus an auto mode that pulls the accent from the artwork.
  • Transport — play/pause, next/prev, seek, volume, shuffle, repeat, and a progress bar drawn as the waveform of what you have already heard.
  • Safe sign-in — you log in inside a real browser window; your Apple ID credentials never touch the terminal.

How it works

Apple Music has no public streaming API, and grabbing the stream would mean breaking DRM — off the table. Instead, the browser plays the music legally and amtui remote-controls it:

┌──────────────┐   chromedp (CDP)   ┌───────────────────────────┐
│  amtui (Go)  │ ◄────────────────► │ hidden Chromium           │
│  Bubble Tea  │                    │ music.apple.com, signed in│
└──────────────┘                    │ window.MusicKit (JS API)  │
                                    └───────────────────────────┘

One Go binary. It spawns a hidden Chromium with a persistent profile in ~/.config/amtui/chrome and talks to window.MusicKit in page context — search, queue, play/pause, seek, now playing. No DOM scraping. Audio goes out through the system mixer (the web player serves AAC 256; no lossless).

Requirements

  • An active Apple Music subscription
  • Go 1.26+ (to build from source)
  • Chrome or Chromium
    • macOS: any recent Chrome/Chromium
    • Linux: a Widevine-capable browser — google-chrome, or Chromium with the Widevine plugin (e.g. chromium-widevine on the AUR)
    • Windows: Google Chrome or Microsoft Edge (auto-detected; AMTUI_CHROME overrides)
  • macOS 14.2+ (the live visualizer uses a CoreAudio process tap), or Linux with pipewire-pulse (or plain PulseAudio) for live capture

Linux support is experimental — designed for Arch/Ubuntu, currently less tested than macOS. On Hyprland the browser window is auto-hidden into a special workspace (Wayland forbids offscreen positioning); other Wayland compositors may leave the window visible for now.

Windows is now built and tested in CI, but there is still no system-audio capture backend, so the visualizer always runs in its labeled simulated mode. Use Windows Terminal — the legacy console does not render the TUI correctly. From Git Bash, run it with winpty amtui.

Install

Prebuilt binaries

Grab the archive for your platform from the latest release — macOS (Apple Silicon / Intel), Linux (x86-64 / arm64) and Windows (x86-64 / arm64):

tar -xzf amtui-*-linux-amd64.tar.gz
sudo install -m755 amtui-*/amtui /usr/local/bin/amtui
amtui --version

Every release ships a SHA256SUMS file; verify with shasum -a 256 -c SHA256SUMS.

macOS binaries are unsigned, so the first launch needs xattr -d com.apple.quarantine amtui (or right-click → Open).

Windows: unzip the archive and run amtui.exe from Windows Terminal or PowerShell. The binary is unsigned, so SmartScreen may say "Windows protected your PC" — click More info → Run anyway. If Defender quarantines it (a known false positive for stripped Go binaries), build from source with install.ps1 instead.

From source
git clone https://github.com/k1y0miiii/applemusic-tui
cd applemusic-tui
./install.sh

The script builds from source and installs amtui (plus applemusic and applemusic-tui aliases) into ~/.local/bin, adding it to PATH for zsh / bash / fish. --prefix DIR installs elsewhere, --no-path leaves your shell config alone. If Chrome is missing, the installer offers to install it (Homebrew on macOS, the official .deb or AUR on Linux).

On macOS the live visualizer needs the Xcode Command Line Tools (xcode-select --install) — the installer checks for them.

Prefer doing it by hand? go build -o amtui . works too; a CGO_ENABLED=0 build runs the visualizer in simulated mode instead of capturing real audio.

Run the test suite with make test, or make verify for the full check.

Windows
git clone https://github.com/k1y0miiii/applemusic-tui
cd applemusic-tui
powershell -ExecutionPolicy Bypass -File .\install.ps1

The script builds amtui from source and installs it (plus applemusic and applemusic-tui shims) into %LOCALAPPDATA%\Programs\amtui, adding that directory to your user PATH. -Prefix DIR installs elsewhere, -NoPath leaves your PATH alone. Needs Go 1.26+ and Git on PATH; no admin rights required.

Building all release archives yourself: make dist. macOS is the only host that produces a complete set — the darwin builds need cgo for the CoreAudio visualizer, while the Linux and Windows targets are pure Go and cross-compile from anywhere.

First run

  1. Launch ./amtui — a visible browser window opens on music.apple.com.
  2. Sign in with your Apple ID. It is a normal browser, so 2FA and captcha just work.
  3. Done — the window hides and the TUI takes over. The session persists in ~/.config/amtui/chrome, so next launches go straight to the player.

Keys

Player
Key Action
Space Play / pause
n / p Next / previous track
Tab Cycle focus: queue → recently played → transport
j k / ↓ ↑ Queue: move selection · Recent: move a grid row · Transport: volume down / up
Enter Play the selected queue track or recently-played cover
← / → Recent: previous / next cover · Transport: seek −5 s / +5 s
s Toggle shuffle
r Cycle repeat mode
? Show every key
v Cycle visualizer: bars → torus → sphere
t Cycle color theme
R Reload the web player if it wedges
/ Open search
q / Ctrl+C Quit
Mouse

Click a queue row or a cover to play it, click the progress bar to seek, and scroll the wheel over the queue or the cover grid to move the selection.

Key Action
typing Edit the query
Enter In input: search (empty query — your library) · In list: play selection
Tab Next tab: RECENT / SONGS / ALBUMS / PLAYLISTS
↓ ↑ / j k Move through results (↓ from the input dives into the list)
a / A Add to the end of the queue / play next
Esc Close search

Search overlay

Queue, live visualizer and synced lyrics

Visualizer

Press v to cycle three shapes; the choice is remembered in ~/.config/amtui/vizmode.

Mode What it draws
bars 32-band spectrum with peak-hold markers. The default.
torus A spinning donut. Its tube thickness at each angle comes from the band that owns that slice of the ring, so the shape corrugates with the spectrum.
sphere A wireframe globe of latitude rings and meridians, shaded by depth. Frequency maps to latitude symmetrically, so the bass swells its waist.

The two 3D shapes answer the beat differently. The torus answers with motion: a bass kick speeds its spin up. The sphere answers with size — it turns at about a third of that pace and instead swells and contracts on the beat, so the pump is what you watch rather than the rotation.

Both read the beat as how far the low end rises above its own running average, not as how loud it is. The bands are normalized over a 63 dB window, so a kick riding 6 dB above the sustained bass moves the absolute number by a tenth and across a track the low end sits high and nearly flat — driving anything from it leaves the shape sitting still.

The bars do neither; they are the spectrum itself. Independent of the mode, the panel borders pulse with the bass — visualizer.pulse turns that off.

Both 3D shapes are plain ASCII over the same 32 bands the bars use, so they cost no extra audio work and follow the active theme's accent colors.

MPRIS (Linux)

amtui publishes itself on D-Bus as org.mpris.MediaPlayer2.amtui, so the desktop can drive it without the terminal being focused:

playerctl -p amtui play-pause
playerctl -p amtui metadata

Media keys, panel applets and lock screens pick it up on their own. Play, pause, next, previous, seek and volume are wired; there is no track list and nothing to raise, and both are declared as such. It appears whenever a session bus is present and is silently skipped when there is not — a TTY, a container, or macOS.

Last.fm

Scrobbling is opt-in. Create an API account at last.fm/api/account/create, put the key and secret under [lastfm] in ~/.config/amtui/config.toml, then run:

amtui lastfm-auth

It prints a link to approve, and saves the session key to ~/.config/amtui/lastfm (mode 600) — the key never has to go in the config file. Nothing is sent until all three parts are present.

Tracks scrobble after half their length or four minutes, whichever comes first, and never below 30 seconds — Last.fm's own rules. The clock counts time actually listened rather than the playback position, so dragging the progress bar to the end does not count as a play.

Themes

Six built-in themes: apple (default), catppuccin, gruvbox, nord, mono and auto. Press t to cycle them; the choice is remembered in ~/.config/amtui/theme.

auto takes its accent from the dominant color of the current track's album art. Only the accent changes — background and text stay neutral, so no cover can make the interface unreadable.

To pick a theme up front or override individual colors, copy docs/config.example.toml to ~/.config/amtui/config.toml. The same file switches the peak markers, the bass pulse, the waveform progress bar and the album art on or off.

Configuration

Environment variable Effect
AMTUI_CHROME Path to the Chrome/Chromium binary (overrides auto-detection; also covers Microsoft Edge on Windows)
AMTUI_CONFIG_DIR Config directory (default ~/.config/amtui)
AMTUI_DEBUG Run the browser visibly, with verbose logging

License

MIT

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
Package engine drives a headed Chromium running music.apple.com via CDP.
Package engine drives a headed Chromium running music.apple.com via CDP.
Package lastfm scrobbles played tracks to Last.fm.
Package lastfm scrobbles played tracks to Last.fm.
Package lyrics fetches lyrics from LRCLIB (lrclib.net, free, no keys) and parses synced LRC into timestamped lines.
Package lyrics fetches lyrics from LRCLIB (lrclib.net, free, no keys) and parses synced LRC into timestamped lines.
Package mpris exposes the player on D-Bus so the desktop can drive it: media keys, panel widgets, playerctl and the lock screen all speak MPRIS and none of them can see a TUI otherwise.
Package mpris exposes the player on D-Bus so the desktop can drive it: media keys, panel widgets, playerctl and the lock screen all speak MPRIS and none of them can see a TUI otherwise.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL