SomaFM in your terminal.

Keyboard controls

Background playback

Audio is streamed and decoded by a separate soma daemon process that the TUI and the CLI talk to over a Unix socket. It starts automatically when first needed; run soma daemon yourself to watch its logs or run it under a service manager — see Install for the systemd unit and launchd plist this repo ships.

The daemon keeps running until soma daemon stop or the tray's Quit item. Set --idle-timeout (or server.idle_timeout) to make it exit on its own once playback is stopped and no client is connected. While it runs it shows a tray / menu-bar icon with the current track, a channel picker and playback controls; --no-tray or server.tray: false turns that off, and headless hosts skip it automatically.

After an upgrade, the running daemon is restarted onto the new version the next time you change channel, pause or stop, never mid-song.

soma stop --in 45m arms a sleep timer instead of stopping right away; the daemon owns it, so it fires even if you close the TUI or the terminal, and a new --in replaces it. soma stop --cancel drops a pending timer without stopping. soma status and the TUI status line show “sleep in Nm” while one is pending.

The server picks each channel's best stream quality by default; set --quality (or server.quality) to highest, high, or low to prefer a lower one, e.g. to save bandwidth — a channel lacking that exact quality falls back to the nearest one it has.

Set --notify (or server.notify: true) to show a desktop notification — title as the heading, artist and channel as the body — on every track change. Off by default, and fired from the daemon itself so it works with the TUI closed.

Somad can send now-playing updates and scrobbles to Last.fm, opt-in and driven from the daemon so it works with the TUI closed. First create an API key/secret pair at last.fm/api/account/create and add them to the configuration file:

lastfm:
  api_key: your-api-key
  api_secret: your-api-secret

Then authorize soma with your Last.fm account:

soma lastfm login

This prints an authorization URL (and tries to open it in a browser), waits for you to press Enter once you've approved it on last.fm, then saves the resulting session. soma lastfm status reports whether scrobbling is configured and logged in; soma lastfm logout removes the saved session. The session key lives in a separate file in the state directory, not the config file, so logging in never edits your hand-written config; a running daemon picks up a fresh login immediately, without a restart.

Once logged in, the daemon sends a now-playing update on every track change and scrobbles the previous track when it ends (next title change, stop, or channel switch) if it played for at least 30 seconds. Each track is scrobbled at most once: live radio cannot skip or rewind, so a pause, a stream drop and reconnect, or a switch to another channel and back while the same track is still on air resume the same play rather than start a new one, and only the time actually listened counts towards the 30 seconds. A title with no identifiable artist (many ambient/genre streams don't follow the “Artist - Title” convention) is never sent, since Last.fm scrobbles need one.

By default the daemon only listens on a local Unix socket. To control a daemon on another machine, say a server wired to the living-room speakers, generate a pre-shared key and make it additionally listen on TCP:

# on the machine with the speakers
soma daemon --gen-psk
soma daemon --listen 0.0.0.0:5454 --tls --psk-file ~/.config/somad/psk

soma daemon --gen-psk writes 32 random bytes to the PSK file (--psk-file/server.psk_file, defaulting to a psk file next to the configuration file) at mode 0600, refusing to overwrite an existing one. --tls encrypts the connection; without your own certificate (--tls-cert/--tls-key) a self-signed one is generated once and reused. The daemon prints its SHA-256 fingerprint at startup, and soma daemon --show-cert reprints it. --psk-file points at that key, which TCP clients must know; it is verified with an HMAC challenge-response and never travels over the wire. Both the daemon and any client reject a PSK file that is readable by group or others, or owned by another user.

On the laptop, copy the key over, point the frontend at the server, and pin the certificate by its fingerprint:

scp myserver:~/.config/somad/psk ~/somad-psk
soma --server myserver:5454 \
     --tls-fingerprint sha256:... \
     --psk-file ~/somad-psk

That works with every command, or permanently via $SOMAD_SERVER and the client: section of the configuration file. Instead of pinning the fingerprint you can trust the certificate file itself (--tls-ca) or, with a CA-issued certificate, use plain --tls with the system trust store.

A listener reachable from other machines requires both TLS and a PSK; the daemon refuses to start without them (--insecure overrides that on a trusted isolated network). A remote daemon is never auto-started or restarted by the client.

Daemon and TUI flags can also be set in a configuration file, which matters because the daemon is usually auto-spawned and therefore runs without any flags. It lives at ~/.config/somad/config.yaml on Linux and ~/Library/Application Support/somad/config.yaml on macOS.

On the first daemon start the file is created as a template with every setting present but commented out. All settings are optional; anything omitted keeps its built-in default, and explicit flags take precedence. A file that fails to parse or contains unknown keys stops the daemon with an error naming the offending line, so a typo never silently falls back to defaults.

Where Somad keeps its files

• Config: ~/.config/somad/ (Linux) or ~/Library/Application Support/somad/ (macOS)
• State: ~/.local/state/somad/ (Linux) or the same macOS directory. Also holds server.log, the generated TLS certificate, and lastfm.json (the Last.fm session from soma lastfm login, mode 0600).
• Cache: ~/.cache/somad/ (Linux) or ~/Library/Caches/somad/ (macOS)
• Socket: $XDG_RUNTIME_DIR/somad.sock (Linux) or a per-user temp directory (macOS); override with $SOMAD_SOCKET