Skip to content
Now Playing

Overlay Tokens

Every Now Playing user has at least one overlay URL — the address you paste into an OBS browser source to show the currently playing track. These URLs need to be unguessable (so strangers cannot show up on your stream by spamming URLs) but also easy to share verbally with a collaborator. Overlay tokens solve both.

Two URL Formats, Same Destination

Section titled “Two URL Formats, Same Destination”

Each overlay is accessible two ways:

  • Friendly URL — /overlay/brave-orange-sunset
  • Token URL — /overlay/k7m3np9q-r4s8tv2w-fh3d5jxe-9mn2vq7s

Both point to the same overlay. Use whichever is more convenient for the context.

The Friendly Name

Section titled “The Friendly Name”

The friendly name is generated from three word lists — an adjective, a colour, and a noun — giving a string that reads like a memorable handle:

  • brave-orange-sunset
  • calm-azure-mountain
  • quiet-violet-harbor

The word lists are curated so that every combination is pronounceable, unambiguous to spell, and free of anything offensive or confusing. With around 300 adjectives × 130 colours × 450 nouns, there are roughly 17.5 million possible combinations — enough that collisions are vanishingly rare, and any new sign-up can claim a fresh unused name.

The High-Entropy Token

Section titled “The High-Entropy Token”

The token URL is 32 random characters plus three dashes, drawn from an alphabet of 30 unambiguous characters (no 0, 1, i, l, o, or u). The character set is chosen so that the token can be copied by hand or read over a video call without confusion.

Because the token is 32 characters from a 30-character alphabet, the space is about 30^32 ≈ 2 × 10^47 combinations — practically impossible to guess.

Resetting Your Overlay URL

Section titled “Resetting Your Overlay URL”

You can reset your overlay URL at any time from the dashboard. Resetting:

  • Generates a new token.
  • Generates a new friendly name.
  • Invalidates the old URL immediately.

Reset is the right action if:

  • You accidentally shared the URL with someone who should not have access.
  • You suspect the URL is being used elsewhere.
  • You want to change the friendly name to something more fitting.

After resetting, update your OBS browser source with the new URL or the old overlay will stop receiving updates.

What the Token Protects

Section titled “What the Token Protects”

The overlay URL grants read-only access to your on-air track. Holding the URL allows a browser source to:

  • Subscribe to your overlay’s SSE stream.
  • Display your currently playing track and artwork.
  • Render themes using your track data.

It does not grant access to your dashboard, your track history, your linked accounts, or any settings. Even if an overlay URL leaks, the blast radius is limited to someone being able to mirror your on-air track display.

Multiple Overlays

Section titled “Multiple Overlays”

You can generate multiple overlay URLs for the same account — for example, one for your main stream, one for a friend’s restream, one for a festival’s broadcast mix. Each URL has its own token and friendly name but points at the same underlying track data, so they all update in lockstep when you play a new track.

How the URL Resolves to You

Section titled “How the URL Resolves to You”

When an overlay loads:

  1. Now Playing extracts the token or friendly name from the URL.
  2. Looks it up in the database to find the associated userId.
  3. Subscribes that browser’s SSE connection to user:{userId}:track in Redis.
  4. As the output services publish your on-air track, the SSE connection streams it down.

The user identity behind an overlay URL is never exposed publicly — only the token or friendly name is in the URL, and the mapping from token to userId stays server-side.