SONIC

SONIC is a vibes-based CLI music player to join alongside your other terminal tabs
Supports YouTube, SoundCloud, Mixcloud, and Spotify.

Quick Start

One-liner (macOS / Linux — installs prereqs automatically):

curl -fsSL https://raw.githubusercontent.com/sethmills21/sonic/main/install.sh | bash

npm

npm install -g github:sethmills21/SONIC
sonic "lofi"

Hackable

brew install yt-dlp mpv                    # macOS prereqs
git clone https://github.com/sethmills21/sonic.git
cd sonic && npm install
npm start

Verify setup

sonic doctor

Commands

sonic                            # open the picker
sonic "deep house"               # search and play
sonic "james bond intro music, working"   # describe a vibe
sonic --soundcloud "liquid dnb"  # search SoundCloud
sonic --mixcloud "techno mix"    # search Mixcloud
sonic --spotify "daft punk"      # search Spotify
sonic connect                    # connect Spotify, step by step
sonic "https://youtu.be/..."     # play a link (quote it)
sonic doctor                     # check setup
sonic --help                     # full help

Controls

Key	Picker	Playback
Enter	Play selected	—
Space	—	Pause / resume
/	Describe a vibe	New vibe (stops playback)
j k / arrows	Move through lists	—
1–0	Quick pick a vibe	—
Tab / Left Right	Switch tabs	—
n / p	—	Next / previous track
f	Open favorites	Favorite track
r	Open recents	—
[ ]	—	Seek -/+ 10s
- +	—	Volume down / up
m	Cycle source	—
v	—	Cycle visualizer
t / T	Next / prev theme	Next / prev theme
d	Toggle dark/light	Toggle dark/light
o	—	Open in browser
b	—	Back to picker
q	Quit	Quit

macOS media keys work via Control Center.

Describe a vibe

Sonic opens on the describe tab: a text box where you type what you want in plain words, like a mood, a scene, an artist, or a song. ↑ ↓ fill in examples, Esc clears, and Tab moves to vibes and sessions, where the single-key shortcuts live. / anywhere brings you back to the box. Three or more words count as a vibe. Sonic searches your words and a long-mix version at once, then puts sets you can work to (20+ minutes, or live) first. On Spotify, a vibe finds playlists.

Themes

Six built-in themes with dark and light variants: Neon Night, Sunset Cassette, Ice Glass, Ember Void, Midnight Tokyo, Terminal Green. Press t to cycle, d to toggle mode.

Visualizers

Five modes: Bars, Tape, Wave, Rain, Flame. Press v during playback.

Sources

YouTube, SoundCloud, and Mixcloud play through mpv and need no account. Press m to cycle. Live streams show a LIVE badge instead of a fake length.

Spotify

Spotify is optional. Sonic acts as a remote: audio plays in a Spotify app (desktop, phone, or web player), and Sonic searches, starts, skips, seeks, and shows what is playing.

sonic connect        # or press c on the home screen

Connect walks you through three checked steps: install spogo (the Spotify CLI Sonic drives), bring over your Spotify login from your browser, and find a device to play on. macOS asks once to share your browser's saved logins; click Always Allow.

• Vibes and sessions open Spotify playlists. Search finds tracks. Spotify links (open.spotify.com/... or spotify: URIs) play directly.
• How auth works: spogo uses your own Spotify web session cookies, stored locally. Sonic never sees or stores your password, and no developer app is needed.
• Premium: Spotify only allows remote playback control for Premium accounts. On macOS with the Spotify desktop app open, spogo can drive the app directly instead.
• Press m to switch to Spotify any time. If it is not connected yet, Sonic opens Connect. sonic doctor reports whether you are logged in.
• Unofficial: this uses Spotify's web player endpoints the same way your browser does. Use it with your own account.

Requirements

Node.js 22+  ·  yt-dlp  ·  mpv  ·  macOS or Linux  ·  optional: spogo for Spotify

Project notes

Mission

Make Sonic feel like a real terminal product, not a code sketch. Favor changes that improve setup, safety, playback reliability, and the quality of the keyboard-driven UX.

Inspiration

Reference set for CLI/TUI quality:

• googleworkspace/cli: installation, prerequisites, agent-ready framing, structured output.
• cli/cli: command ergonomics, help UX, and polished distribution posture.
• alexknowshtml/api2cli: dual human/agent command design and self-documenting CLI patterns.
• asc: focused workflow automation with a strong install/onboarding surface.
• Polymarket/polymarket-cli: clear warnings, Homebrew install, scriptable terminal product design.
• google-gemini/gemini-cli and superagent-ai/grok-cli: examples of modern agent CLI presentation.
• rothgar/awesome-tuis: broad TUI idea bank.

What to steal for Sonic:

1. excellent --help
2. clean install paths
3. obvious warnings around risky behavior
4. strong README and release posture
5. future-friendly script/agent integration without sacrificing the live TUI

Preferred Roadmap

1. queue, favorites, recents, config
2. doctor/setup diagnostics
3. session integration
4. cleaner service adapter boundaries
5. broader platform support and release automation

Contributing

See CONTRIBUTING.md and SECURITY.md.

License

MIT

---

Cooked up by Seth Mills and Claude Code

_{Not claiming this is some groundbreaking piece of tech — just solving my own problem and had a lot of fun building it. Open to ideas, feel free to fork.}