SomaFM in your terminal.⁠

Keyboard controls

The mouse works too: the wheel scrolls the channel list; a click selects a channel and a second click plays it; a click or drag on the volume bar sets the volume, the wheel over it steps it, and a click on its label toggles mute; a click on an item of the help bar at the bottom presses its key.

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 (which returns once the daemon has let go, so soma daemon stop && soma daemon starts a fresh one) 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; the icon is the full mark while playing, dimmed while stopped, and animates while a channel tunes in or reconnects; --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. If the upgrade changed the wire protocol, the old daemon cannot serve the new client at all: until then the other commands and the TUI fail with an error saying so (the music keeps playing), and soma daemon stop stops the old daemon right away. A sleep timer that is pending carries over to the restarted daemon.

If the daemon loses its audio device for good (the sound server it was connected to was restarted, say), it stops and says so in soma status and the TUI: only a new process gets a working device. The next soma play, soma pause, or channel you pick in the TUI replaces the daemon with a fresh one and plays. Asked to play in any other way (from the tray, with a media key, by a remote client), the daemon restarts itself and then plays.

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. It goes by the clock: suspending the machine in between does not push the stop back. soma stop --cancel drops a pending timer without stopping. soma status and the TUI's now-playing card 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. SomaFM offers the lower qualities (high, about 64 kbps, and low, about 32 kbps) only as HE-AAC, which only the macOS build decodes; on Linux, which plays MP3, every channel stays at its highest quality.

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 (or logout) immediately, without a restart, even one started before you added the key pair. The session belongs to the machine you log in on: for a daemon you control over TCP (--server), run soma lastfm login on the host the daemon runs on. If you set lastfm.session_key in the configuration file yourself, that key decides instead of the saved session: soma lastfm login then refuses to run, and soma lastfm logout removes the saved session but fails, telling you to take the key out of the file.

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. A key you wrote yourself works too, but the daemon warns about one shorter than 16 bytes: the key is all that keeps a guesser out. --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. --tls-ca also checks the name you connect by, and the generated certificate names only localhost, the loopback addresses, the server's hostname and a specific --listen host, so a bare LAN address like 192.168.1.20 fails; connect by one of the names the error lists, or pin the fingerprint.

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. Relative file paths in it are taken relative to the config directory, and soma warns when the file holds a secret but others can read it.

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, lastfm.json (the Last.fm session from soma lastfm login, mode 0600), and tui.json (the TUI's own preferences, such as the visualizer style).
• 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