Documentation

Setup guide and usage instructions for Cuefy.

Quick Start

Cuefy displays your now-playing music as an OBS overlay in real time. Setup takes just 4 steps.

Log in with Discord
Click "Login with Discord" on the top page to create your account.

Configure your data source
Spotify users set up "Spotify Integration", others install the "Cuefy+ Extension" for YouTube Music and more.

Pick a template and save
In the Dashboard, choose a template, customize colors and fonts, then click "Save Settings".

Paste the URL into OBS
Add the OBS URL shown on your Dashboard as a Browser Source in OBS Studio.

OBS Setup

Display the overlay using OBS Studio's Browser Source feature.

Adding a Browser Source

Open OBS Studio. In the Sources panel, click "+" → "Browser".

Paste your overlay URL (from the Dashboard) into the "URL" field.

Set the width and height according to the template you chose (see recommended values below).

Click "OK" and position the source on your scene.

Recommended Sizes

Template	Width	Height
Compact / Minimal / Text / Pill / Banner	`700–900px`	`120px`
Card / Animated / Vinyl / Color	`300px`	`380px`
Glass / Neon / iOS / Holographic / LiquidGlass	`420px`	`130px`
Spotify-Style / Widget / Lo-fi / Luxury	`340px`	`110px`
Cassette / Retro 80s / Cinema / Blueprint / Post-it	`500px`	`180px`
Gameboy / Pixel	`240px`	`320px`
Newspaper / Receipt / Typewriter / Comic	`400px`	`220px`
Netflix / Discord / Twitch / YouTube	`560px`	`160px`
Apple Music / SoundCloud / TikTok / Instagram / X	`380px`	`140px`
VHS / Matrix / Cyberpunk / Arcade	`500px`	`160px`
Polaroid / Kawaii / Manga / Cottagecore / Waveform	`360px`	`200px`

Recommended OBS Settings

✓"Shutdown source when not visible" — enable this

✓"Refresh browser when scene becomes active" — enable this

✓Add body { background: transparent !important; } to Custom CSS (applied by default)

✦

OBS 31+ uses Chromium 113+, so the LiquidGlass template (which requires WebGPU) works natively in OBS.

Data Source

Cuefy supports two data sources. Switch between them in the Dashboard's "Data Source" section.

🧩Extension (Recommended)

✓Supports YT Music, Apple Music, and 6 services
✓No Spotify account needed
✓Real-time from any supported browser tab
–Requires a Chromium browser

🎵Spotify

✓Real-time from the Spotify app
✓Works from any device, including mobile
–Requires a Spotify Developer App
–Spotify only

Cuefy+ Browser Extension

Cuefy+ is a Chrome extension that supports YouTube Music, Apple Music, Deezer, SoundCloud, Amazon Music, and Tidal.

Supported Services

YouTube MusicApple MusicDeezerSoundCloudAmazon MusicTidal

Installation & Connection

Chrome Web Store — install Cuefy+ from the Chrome Web Store.

Settings page — Cuefy+ automatically picks up the token. When the popup shows "接続中" (Connected), you're ready.

Start playing music on any supported service. The overlay updates automatically.

✦

Simply visiting the Settings page auto-connects the extension. No manual token entry needed.

How It Works

The extension monitors supported service tabs in the background and sends track info (title, artist, album art, play state, progress) to the Cuefy server. Closing the tab automatically sends a stop signal, hiding the overlay.

Spotify Integration

Cuefy requires your own Spotify Developer App to use the Spotify API (BYOA: Bring Your Own App). This is due to Spotify API terms of service.

Creating a Spotify Developer App

developer.spotify.com/dashboard — log in with your Spotify account.

Click "Create app". App name and description can be anything.

Add the following URL to "Redirect URIs" and click "Save".

https://cuefy.unitze.net/auth/spotify/callback

Copy "Client ID" and "Client Secret" from the app settings.

Cuefy Settings page → "Spotify Developer App" section → paste Client ID and Secret, then save.

In the same Settings page, under "Spotify Integration", click "Connect Spotify" and authorize.

⚠

Never share your Client Secret. If it leaks, rotate it in the Spotify Dashboard.

Templates

Cuefy offers many templates. Use the Template Selector on the Dashboard to preview them in real time.

Free Templates

CompactCardText OnlyAnimatedMinimalGlassiOSSpotify-StyleNeonVinylColorKawaiiPillBanner

Premium Templates　Premium

WidgetWindows XPTerminalCassetteRetro 80sVHS8-bit PixelHolographicWaveformLiquidGlassMatrixBlueprintTypewriterCinemaGameboyNewspaperReceiptPolaroidLo-fiLuxuryMangaPost-itComicCottagecoreCyberpunkArcadeNetflixDiscordTwitchYouTubeApple MusicSoundCloudTikTokInstagramX / Twitter

✦

LiquidGlass requires WebGPU — Chrome/Edge 113+ or OBS 31+. CSS fallback activates automatically on unsupported browsers.

Custom CSS

Enter any CSS in Dashboard → Style → Custom CSS. You can override any element in the template.

Examples

Change font size

.overlay-root { font-size: 18px; }

Fully transparent background

body { background: transparent !important; }

Hide album art

.album-art { display: none !important; }

Disable animations

* { animation: none !important; transition: none !important; }

⚠

Custom CSS may break on template updates. Verify your CSS after any template upgrade.

FAQ

Q. The overlay isn't showing

① Verify the browser source URL is correct. ② Right-click the browser source in OBS → "Refresh". ③ Check that your data source is properly configured in Settings.

Q. The overlay doesn't update when the track changes

For the extension: make sure the service tab is open and the popup shows "接続中" (Connected). For Spotify: verify your Client ID/Secret and that Spotify is connected in Settings.

Q. The extension doesn't auto-connect

First confirm Cuefy+ is installed from the Chrome Web Store. Then open the Cuefy Settings page (cuefy.unitze.net/settings) — just visiting that page triggers auto-connect. If it still doesn't work, reload the extension from chrome://extensions.

Q. Spotify authentication fails

Verify that the Redirect URI in your Spotify Developer Dashboard is exactly "https://cuefy.unitze.net/auth/spotify/callback". Copy-paste errors are a common cause.

Q. Can't select premium templates

Upgrade to Premium from the Plan section in Settings. All templates become available immediately after upgrading.

Q. LiquidGlass looks like half Compact

In environments without WebGPU, a CSS fallback is shown. Use Chrome 113+ or the latest Edge. Reloading after saving settings also helps.

Q. I want to change my overlay URL

In Settings → Streaming → "OBS Browser Source URL" → "Regenerate URL". The old URL is invalidated immediately. Update your OBS browser source too.