beefy-player/README.md

# somafm-tui

![somafm-tui demo](assets/somafm-tui-demo.gif)

A flashy terminal radio for **[SomaFM](https://somafm.com)** — a live spectrum
analyser, song history, and full desktop media integration, drawn with your
terminal's own ANSI palette on the terminal's default background so it fits
any theme (including transparent terminals).

It runs the same way on **Linux** (PulseAudio/PipeWire) and **macOS**
(CoreAudio, iTerm2/Kitty/WezTerm): MPRIS on the desktop bus where that exists,
macOS Now Playing (Control Center and the media keys) where it does not.

No existing SomaFM client is used: the station list, playlists, song history,
audio control, spectrum visualiser and media-session integration are all
implemented here from the public SomaFM endpoints and open protocols.

## Features

- **Live spectrum analyser** — 72 log-spaced bands with peak caps, a moving
  gradient taken from your terminal's ANSI palette and a symmetric mirrored
  spectrum; or a full-height oscilloscope. Three modes (`v`).
- **Synced spectrum, not a guess** — by default the analyser records your
  actual audio output, so the bars follow what you hear (`SYNC`): the
  PulseAudio/PipeWire monitor via `parec` on Linux, an `ffmpeg`/avfoundation
  loopback input (BlackHole, Loopback, Soundflower, …) on macOS. Without an
  output capture it falls back to a muted second `ffmpeg` decode of the stream
  (`FFT`, can drift), then to a synthesized display (`SIM`).
- **Real artwork on iTerm2, Kitty and WezTerm** — Kitty uses the kitty
  graphics protocol; iTerm2 (including on macOS) and WezTerm use their native
  iTerm2 inline-image protocol. Images occupy exactly the ON AIR art cell box
  and fall back to the procedural ANSI mosaic for other terminals, failed
  loads, or blocked graphics passthrough. Images are cached in
  `~/.cache/somafm-tui/artwork`.
- **Now playing** — artist, title, album, DJ, listeners, format/bitrate and
  "played N minutes ago", with procedural ANSI-shaded album art that changes
  per track. When the current track can be found on Bandcamp, a clickable
  **Bandcamp ↗** link appears below it; otherwise the line stays hidden.
- **Last played** — the full recent history from `somafm.com/songs/<id>.json`.
- **Every station** — the whole `channels.json` roster (≈50 channels), live
  listener counts, genre search.
- **Favourites** that float to the top, remembered between runs.
- **Desktop media integration** — on Linux an
  `org.mpris.MediaPlayer2.somafmtui.instance<pid>` player exposes
  `PlaybackStatus`, `Metadata` (title/artist/album/artUrl), `Volume`, and
  `Play`/`Pause`/`PlayPause`/`Stop`/`Next`/`Previous`, so GNOME/KDE widgets,
  lock screens, `playerctl` and the media keys pick it up. On macOS the audio
  engine (mpv) publishes to the system **Now Playing** session, so Control
  Center, the menu bar and the keyboard media keys drive the app the same way.
- **Theme-aware** — every accent is emitted as native ANSI (not RGB), and the
  background is the terminal default (`SGR 49`), so transparent terminals stay
  transparent and the TUI adopts your shell/terminal colour scheme.
- **Graceful degradation** — works with cached data offline, falls back to a
  bundled station list, reconnects across ICE mirrors automatically, and uses
  `ffplay` if `mpv` is missing.

## Requirements

`somafm-tui` is a normal Python application: there is nothing to compile and
no distro-specific packaging. It runs on any Linux distribution or macOS with
Python **3.10+** and a few command-line audio tools on `$PATH`.

| tool | why |
| ---- | --- |
| `python3` | runtime (3.10 or newer; no exact version pin) |
| [`uv`](https://docs.astral.sh/uv/) | creates the venv and installs every Python dependency from `uv.lock` |
| `mpv` | playback and JSON IPC control |
| `ffmpeg` | muted stream decode for the fallback analyser, and the macOS output capture |
| `parec` / `pactl` *(Linux)* | synced monitor capture for the spectrum (`pulseaudio-utils`; works with PipeWire) |
| a loopback audio device *(macOS, optional)* | synced output capture for the spectrum: BlackHole, Loopback, Soundflower, … |
| D-Bus session bus *(Linux)* | MPRIS desktop media integration (`playerctl` is handy for testing) |

On macOS the media integration needs nothing extra: mpv is what the system's
Now Playing session (Control Center, media keys) talks to.

Install `uv` once (skip if it is already there):

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

`brew install uv`, `pipx install uv`, or a distro package also work. If your
system Python is older than 3.10, let uv manage one: `uv python install 3.12`.

### Linux

Install these with your package manager. Names are usually:

```bash
# Debian / Ubuntu
sudo apt install python3 mpv ffmpeg pulseaudio-utils dbus playerctl

# Fedora (enable RPM Fusion for ffmpeg if needed)
sudo dnf install python3 mpv ffmpeg pulseaudio-utils dbus-tools playerctl

# Arch / Manjaro
sudo pacman -S python mpv ffmpeg libpulse dbus playerctl

# openSUSE
sudo zypper install python3 mpv ffmpeg pulseaudio-utils dbus-1-tools playerctl
```

For other distributions, install the equivalents. On a headless machine you
can skip the audio/D-Bus tools and use `--no-audio` for a UI-only demo, though
the synced spectrum needs `parec`/`pactl`.

### macOS

```bash
brew install mpv ffmpeg uv        # ffplay ships with ffmpeg
```

That is enough to run: playback, artwork in iTerm2/Kitty/WezTerm, the muted
`ffmpeg` spectrum tap and the macOS Now Playing integration all work out of the
box. The first capture attempt makes macOS ask for **microphone** access for
whatever terminal you use — that permission is what lets `ffmpeg` read the
loopback device.

For a *synced* spectrum (`SYNC` instead of `FFT`) macOS needs an output
loopback, because CoreAudio does not let an ordinary process record the
speakers directly:

```bash
brew install blackhole-2ch        # or Loopback / Soundflower
```

Then either

1. create a **Multi-Output Device** in *Audio MIDI Setup* containing both your
   speakers/headphones and *BlackHole 2ch*, and select it as the system output,
   or
2. set *BlackHole 2ch* as the output and monitor the audio elsewhere.

The app auto-detects loopback-style inputs (BlackHole, Loopback, Soundflower,
“Multi-Output”, “Aggregate”) and never grabs a plain microphone by accident.
Pick one explicitly with `SOMAFM_SPECTRUM_DEVICE` (name or avfoundation index,
see `ffmpeg -f avfoundation -list_devices true -i ""`). If the loopback turns
out to be silent (nothing routed into it), the analyser notices after a few
seconds and falls back to `FFT` instead of showing dead bars.

Terminal image rendering uses [Pillow](https://python-pillow.org/) and is
implemented directly (Kitty TGP + iTerm2 OSC 1337) — no terminal probing.

## Run

From the repository root, sync the environment and start the app:

```bash
uv sync              # create .venv and install exactly what uv.lock pins
uv run somafm-tui    # run inside that environment
```

You do **not** need to activate the venv. `uv run` uses `.venv` automatically,
and re-syncs it first if `pyproject.toml` or `uv.lock` changed. If you prefer a
traditional shell, run `source .venv/bin/activate` and then `somafm-tui`.

### Keeping the uv environment in sync

`uv sync` is the command to remember. It is incremental, safe to re-run, and
should be run after pulling changes, switching branches, or editing
`pyproject.toml`:

```bash
uv sync                  # make .venv match uv.lock
uv sync --frozen         # strict: fail if uv.lock is out of date, never rewrite it
uv lock --upgrade        # refresh uv.lock to the newest allowed versions
uv sync --upgrade        # upgrade dependencies and sync .venv in one step
rm -rf .venv && uv sync  # last resort if the venv was built by an older Python
```

Useful flags:

```bash
uv run somafm-tui --play                # start the last station immediately
uv run somafm-tui --station defcon       # pick a station
uv run somafm-tui --volume 55
uv run somafm-tui --offline              # no network; cached/bundled stations
uv run somafm-tui --no-mpris             # no MPRIS / Now Playing, no media keys
uv run somafm-tui --list                 # print station ids
uv run somafm-tui --no-audio             # UI demo without mpv/ffmpeg
uv run somafm-tui --spectrum-source monitor  # force synced output capture
uv run somafm-tui --spectrum-source stream   # force the muted ffmpeg tap
SOMAFM_IMAGES=0 uv run somafm-tui             # force the ANSI artwork mosaic
SOMAFM_IMAGES=tgp uv run somafm-tui           # force Kitty/TGP artwork
SOMAFM_IMAGES=iterm2 uv run somafm-tui        # force iTerm2/WezTerm artwork
```

The UI wants roughly **84×24**; it also works smaller, just less pretty.

## Keys

| key            | action                                        |
| -------------- | --------------------------------------------- |
| `↑` / `↓`, `j` / `k` | move through stations                    |
| `enter`        | tune in to the selected station               |
| `space`        | play / pause                                  |
| `s`            | stop                                          |
| `]` / `[`      | next / previous station (tunes immediately)   |
| `+` / `-`      | volume                                        |
| `m`            | mute                                          |
| `f`            | favourite (favourites sort to the top)        |
| `/`            | filter by title, genre, description           |
| `esc`          | clear filter / close search                   |
| `v`            | visualiser: mirrored bars → bars → wave       |
| `r`            | refresh channels + song history               |
| `g` / `G`      | top / bottom                                  |
| `?`            | help                                          |
| `q`            | quit                                          |

## Desktop media widgets (MPRIS / Now Playing)

**Linux** — while playing, the app exports
`org.mpris.MediaPlayer2.somafmtui.instance<pid>` on the **session bus**. Check it:

```bash
playerctl -l
playerctl metadata --format '{{artist}} — {{title}} ({{album}})'
playerctl play-pause
```

`mpris:artUrl` is the track's album art when SomaFM provides it, otherwise the
channel logo. If there is no session bus (SSH without `dbus-run-session`,
containers, …) MPRIS is skipped and the status bar shows `mpris off`.

**macOS** — mpv owns the system Now Playing session, so Control Center, the
menu-bar widget and the keyboard media keys (▶︎/⏸, ⏭, ⏮) all target this app
while it is playing. mpv publishes the live stream title (the same
“Artist - Title” that SomaFM sends with the audio), and the media keys are
routed back into the TUI, so `⏭`/`⏮` really change station and the panel, the
spectrum and the station list stay in sync. The status bar shows
`nowplaying on`. There is no D-Bus and no extra dependency involved, and
`--no-mpris` (also spelled `--no-media`) turns the media keys off again.

> macOS shows one Now Playing app at a time. If Music/Safari/another mpv is
> playing, the media keys go there instead — quit it or pause it to hand the
> keys back.

## How it works

- `somafm_tui/api.py` — async `httpx` client for:
  - `channels.json` → stations, genres, listeners, `.pls` playlist URLs
  - `<station>.pls` → resolved direct icecast URLs (cached 8h)
  - `songs/<station>.json` → last played tracks (cached on disk)
  Playlist and channel caching means the UI opens instantly and still works
  offline.
- `somafm_tui/player.py` — mpv over a Unix-socket JSON IPC channel. Observes
  `pause`/`volume`, handles mirror failover on `end-file`, auto-restarts a dead
  engine, and uses `SIGSTOP`/`SIGCONT` when falling back to `ffplay`. On macOS
  it also asks mpv to publish Now Playing and maps the media keys onto
  `script-message`s that come back over the same IPC socket.
- `somafm_tui/spectrum.py` — 44.1 kHz mono s16le analyser. Prefers capturing
  the real output: `parec` (PulseAudio/PipeWire monitor) on Linux, or
  `ffmpeg -f avfoundation` on a loopback input on macOS (SYNC). Otherwise a
  muted low-latency `ffmpeg` decode of the stream (FFT). Hann-windowed
  2048-point FFT, log band grouping, auto-gain, fast attack/decay smoothing,
  peak hold and waveform downsampling.
- `somafm_tui/mediasession.py` — picks the desktop media backend (MPRIS on
  Linux, Now Playing on macOS) so the app has one platform-neutral interface.
- `somafm_tui/mpris.py` — `dbus-next` MPRIS service in its own thread with a
  thread-safe command queue back into the UI (only loaded on D-Bus platforms).
- `somafm_tui/bandcamp.py` — searches Bandcamp's public autocomplete API for
  the now-playing track (artist + track first, then artist + album, then the
  album page) and returns a track URL when there is a match.
- `somafm_tui/widgets/` — Textual widgets rendered with native ANSI colours;
  backgrounds are `ansi_default` (`SGR 49`), so transparent terminals stay
  transparent.

### Files

```
~/.config/somafm-tui/config.json     favourites, volume, last station, mode
~/.cache/somafm-tui/channels.json    last good station list
~/.cache/somafm-tui/playlists.json   resolved stream URLs
~/.cache/somafm-tui/songs/<id>.json  song history snapshots
~/.cache/somafm-tui/artwork/<sha1>  cached album/channel artwork
```

These stay in the XDG locations on every platform (macOS included), so the
same dotfiles/config work everywhere; `XDG_CONFIG_HOME`, `XDG_CACHE_HOME` and
`XDG_RUNTIME_DIR` are honoured when set.

## Notes / troubleshooting

- **Artwork shows the mosaic?** Real images are auto-enabled for Kitty,
  iTerm2 and WezTerm. Force a protocol with `SOMAFM_IMAGES=tgp` (Kitty/TGP) or
  `SOMAFM_IMAGES=iterm2` (iTerm2/WezTerm); `SOMAFM_IMAGES=0` forces the ANSI
  mosaic. iTerm2 on macOS is detected from `TERM_PROGRAM`/`LC_TERMINAL`, and
  empty or `0` values in `TMUX`/`ZELLIJ`/`STY` (exported by some wrappers) are
  ignored so they cannot downgrade it. Kitty inside tmux is attempted through
  tmux passthrough (enable `set -g allow-passthrough on`); iTerm2/WezTerm
  inside tmux default to the mosaic. Images are cached under
  `~/.cache/somafm-tui/artwork`.
- **Clock shows UTC?** The clock and song history use the system zone from
  `/etc/localtime`; a non-UTC `TZ` overrides it. A container or dev shell can
  inherit a build-time `TZ=UTC`, which the app deliberately ignores; bind the
  host's `/etc/localtime` or set e.g. `TZ=Europe/Berlin` in the shell that
  launches the app.
- **MPRIS says off/error?** No session bus. Run from your desktop session
  (the shell profile picks up `$XDG_RUNTIME_DIR/bus`). `dbus-run-session -- uv
  run somafm-tui` starts a private bus for testing, but desktop widgets won't
  see it. macOS does not use MPRIS at all — see “Now Playing” above.
- **No audio?** `somafm-tui` needs `mpv` (preferred) or `ffplay`. Without
  either, the UI still runs and tells you. Extra mpv args can be injected with
  `SOMAFM_MPV_ARGS` (e.g. `SOMAFM_MPV_ARGS='--audio-device=...'`, which is the
  macOS way to choose an output device).
- **Spectrum says `FFT` instead of `SYNC`?** `parec`/`pactl` are unavailable,
  the monitor device failed, or you forced the stream tap. The bars are still
  real audio, but the second stream can drift relative to playback. Use
  `--spectrum-source monitor` to force sync, or `SOMAFM_SPECTRUM_DEVICE=<source>`
  to pick a specific monitor/source. `SIM` means the bars are synthesized.
- **Diagnose artwork:** `uv run somafm-tui --diagnose-images` prints the
  detected protocol, widget class, terminal env, dependency versions and cache
  path. If `protocol` is `None`, force it with `SOMAFM_IMAGES=tgp` (Kitty) or
  `SOMAFM_IMAGES=iterm2` (iTerm2/WezTerm).
- **`SYNC` but the bars are flat?** mpv may be playing to a different sink (or
  directly to ALSA). Point `SOMAFM_SPECTRUM_DEVICE` at that sink's monitor, or
  use `--spectrum-source stream`.
- **macOS: spectrum stays `FFT`?** Install a loopback (BlackHole/Loopback) and
  route your speakers through a Multi-Output Device, then check
  `ffmpeg -f avfoundation -list_devices true -i ""` lists it. The first capture
  triggers a macOS microphone-permission prompt; grant it to your terminal
  (System Settings → Privacy & Security → Microphone), otherwise ffmpeg cannot
  open the device and the analyser stays on `FFT`.
- **macOS: media keys do nothing?** Another app currently owns the Now Playing
  session, or the app was started with `--no-mpris`, or the audio backend fell
  back to `ffplay` (mpv is required for Now Playing). The status bar shows
  `nowplaying on` when the integration is armed.
- **macOS: Control Center shows only a title?** mpv publishes the stream's live
  “Artist - Title” as the Now Playing title; artist/album fields and artwork are
  not filled in by macOS for plain audio streams. The TUI itself always shows
  the full metadata and album art.
- **Bandwidth** is unchanged in SYNC mode (the monitor capture creates no
  second stream). The FFT fallback opens one extra stream; if you are on a
  metered link, use `--spectrum-source monitor` (or `--no-audio` for a UI-only
  demo).
- SomaFM is listener-supported: if you enjoy it, [donate](https://somafm.com/support/).

## NixOS (optional aside)

None of the above needs Nix. If you *are* on NixOS, `shell.nix` wraps the same
`uv sync` / `uv run` workflow in an FHS environment, because uv installs
manylinux wheels such as NumPy that expect `libstdc++.so.6` in the usual
`/usr/lib` paths:

```bash
nix-shell            # enter the FHS dev shell
uv sync
uv run somafm-tui
```

- If you see `libstdc++.so.6: cannot open shared object file`, make sure you
  are inside `nix-shell`, then recreate the venv once with
  `rm -rf .venv && uv sync`.
- `nix-shell --run "..."` does not work with FHS `shell.nix` files; enter the
  shell interactively and run commands there.
- FHS shells need unprivileged user namespaces. `bwrap: No permissions to
  create a new namespace` means they are disabled (for example in a locked-down
  container); run the app on the host instead.

## Licence

WTFPL — Do What The Fuck You Want To Public License, Version 2. See
[LICENSE](LICENSE). SomaFM and its channel names are trademarks of
SomaFM.com, LLC.

Terminal image rendering uses [Pillow](https://python-pillow.org/).