hum

hum

Every song ever made, free, in a player that feels like a room lit by the album cover.

• Search any song, or paste a Spotify playlist, album or track link (or press ⌘V anywhere).
• Tap a station and it plays forever in that mood.
• Time-synced lyrics, an endless autoplay mix, liked songs, shareable song links.
• No accounts, no keys, no database. Your library lives in your browser.

Playback runs through YouTube's official embedded player, so ads and royalties work the normal way and artists still get paid.

Run it

One command (Node 18+). Starts hum and opens it in your browser:

npx github:anzal1/hum

From a clone:

node server.js

Docker (home server, VPS, NAS):

docker build -t hum . && docker run -p 3737:3737 hum

Put it online for free

hum is a folder of static files plus one small function, so it fits the free tier of Cloudflare Workers: static files are unlimited and 100,000 searches a day are included.

• One click: the Deploy to Cloudflare button on /developers.html, or https://deploy.workers.cloudflare.com/?url=https://github.com/anzal1/hum
• From this folder: npx wrangler deploy

Vercel works too (api/ and vercel.json are ready), but its free plan is for non-commercial use.

Tested: node server.js, npx from a packed tarball, Docker, and Cloudflare's own runtime locally (npx wrangler dev). Every route answered in all four.

Put hum inside your app

One script tag adds a floating player to any page:

<script src="https://YOUR-HUM-HOST/embed.js" data-station="lofi beats"></script>

Then drive it from code: hum.play('Blinding Lights'), hum.station('deep focus'), hum.playlist(spotifyUrl), hum.pause(), hum.next(), hum.volume(60), hum.on('state', fn). Or use the iframe directly: widget.html?station=lofi and postMessage({ hum: 'play', query }). Live demo at /developers.html.

In your coding agent

hum works with any agent that speaks MCP. Your agent is the remote, and the music plays in a hum browser tab. It can play, start a station, import a Spotify link, skip, set the volume, and tell you what is playing, down to the line being sung. Needs Node 18+.

claude mcp add --scope user hum -- npx -y -p github:anzal1/hum hum-mcp

VS Code:

code --add-mcp '{"name":"hum","type":"stdio","command":"npx","args":["-y","-p","github:anzal1/hum","hum-mcp"]}'

Claude Desktop (one-click extension), Cursor (install link), Codex, Gemini CLI, Windsurf, Zed, Copilot CLI, opencode, Cline, Kiro, Amp, Goose and Continue are all in docs/agents.md.

From your terminal

Install once, and the commands start hum and open it for you when needed.

npm i -g github:anzal1/hum

hum play blinding lights       # a song or artist
hum station lofi beats         # an endless mix
hum playlist <spotify link>
hum pause | resume | toggle | next | prev
hum vol 40
hum duck                       # lower the music; hum unduck brings it back
hum now                        # title, artist, progress and the line being sung

hum now --line prints one short line for status bars, and nothing when hum is not running: ♪ Amazing Grace · Judy Collins · I once was lost, but now I am found. It never starts hum and returns in about 30 ms. hum now --json is for scripts.

In tmux (~/.tmux.conf):

set -g status-right '#(hum now --line)'
set -g status-interval 2

In Claude Code (~/.claude/settings.json):

"statusLine": { "type": "command", "command": "hum now --line" }

Anything else can POST to the local remote, which only listens on 127.0.0.1 and only accepts JSON:

curl -X POST localhost:3737/api/remote -H 'content-type: application/json' -d '{"cmd":"station","mood":"lofi"}'

Playback always happens in the hum window, through YouTube's own player, so keep it open. The terminal is a remote and a display. HUM_PORT picks another port and HUM_NO_OPEN=1 stops it opening the browser.

How it works

Piece	Source
Search, song metadata, autoplay mixes	YouTube Music's public web API, called from api/_core.js
Playback	YouTube IFrame Player API, always visible as the rules require
Lyrics	LRCLIB, called straight from the browser
Spotify import	Spotify's public embed page for that playlist
Colours	Pulled from the cover art in the browser, painted with a WebGL shader

If a song's main upload refuses to play outside YouTube, hum quietly tries the next best upload.

Desktop app with a live notch

desktop/ is a small Electron app: hum in its own window, plus an island that sits over the MacBook notch. The compact island wraps the notch (cover on the left, bars on the right); hover it and it drops down into a mini player with the lyric being sung, progress and controls. On Windows and on Macs without a notch it floats at the top centre of the screen. The island talks to the player over a BroadcastChannel, so any window of the same site can drive it.

cd desktop && npm install && npm start          # uses https://hum.anzalabidi.dev
cd desktop && npm run dev                       # uses your local server on :3737

In the browser, press N for the same island inside the page.

Pop-out mini player

Press P or the pop-out button and the player moves into a small always-on-top window (Chrome and Edge, via Document Picture-in-Picture). Chrome can also open it by itself when you switch tabs mid-song. Close it and playback slides back into the page at the same second.

Share links

Song links look like /s/<id>. Chat apps and social sites see the song's own cover and title; people who click land straight in the player. The default preview image is public/og.jpg, made from og/og.html. Set the og:image in public/index.html to your full domain after deploying, since some crawlers ignore relative paths.

Tests

test/e2e.js is an end-to-end suite of 52 checks covering every search path, button, slider, switch, list action, keyboard shortcut, the widget, share pages and the remote. It passes in Chromium, Firefox and WebKit (Safari's engine). Serve it next to the app (cp test/e2e.js public/__e2e.js), start the app, press play once, then run in the console:

(await import('/__e2e.js')).run().then((r) => console.table(r))

Keys

Key	Does
/ or ⌘K	Search
Space	Play or pause
← →	Seek 5s
Shift + ← →	Previous or next
L	Lyrics
Q	Up next
S	Shuffle
M	Mute
P	Pop out the mini player
N	Notch mode

Limits worth knowing

• YouTube's rules say the player must stay visible and can't play in the background, so music stops when a phone locks. Desktop, tablets and TVs are fine.
• Spotify import brings over the first 100 songs of a playlist.
• Search and mixes use YouTube Music's unofficial web API, which can change without notice.
• YouTube may show ads in the player. hum does not and should not block them. People signed in to YouTube Premium in the same browser usually get no ads.
• A fresh tab needs one click before the browser allows sound. After that, agents and the widget API play freely.