Setup guide

Getting started

You'll need OBS Studio 28 or newer and a StreamerSongList account. The app's setup has three steps, and the last one is optional: connect your songs, put BubbleFacts on your stream, and tell us about your music. BubbleFacts needs to run on the same computer as OBS.

Install the app

Download the version for your computer from the download page, then follow the steps for your system. The Mac button gets the version for Apple silicon, which most Macs since late 2020 have. There's also an Intel version: see which Mac do I have. Not sure your computer is up to it? Check the system requirements.

About the security warnings

The app isn't signed yet. Signing is a paid registration with Apple and Microsoft that tells your computer who made an app. Until that's done, your computer will warn you the first time you open BubbleFacts. The steps below show how to get past it. These warnings go away once the app is signed.

Mac

Open the BubbleFacts .dmg file from your Downloads folder.
Drag BubbleFacts into the Applications folder.
Open your Applications folder, right-click BubbleFacts (or Control-click), and choose Open.
Your Mac may say the app "can't be opened because Apple cannot check it for malicious software." Click Open again in that message.

If there's no Open button: open System Settings, go to Privacy & Security, scroll down, and click Open Anyway next to the note about BubbleFacts. You only need to do this once.

Windows

Open the BubbleFacts .exe file from your Downloads folder. If your browser says the file isn't commonly downloaded, choose to keep it.
Windows may show a blue box saying Windows protected your PC. Click More info, then Run anyway.
The installer sets up BubbleFacts just for you. It doesn't need an administrator password.

Linux

Ubuntu, Debian and similar: use the .deb file (its name ends in _amd64.deb).

Double-click the BubbleFacts .deb file in your Downloads folder.
If it opens in an archive viewer instead, close that. Right-click the file, choose Open With, then App Center (Ubuntu 24.04 and newer) or Software Install.
Click Install and type your computer's password when asked.

Other Linux: use the AppImage.

Right-click the BubbleFacts .AppImage file and choose Properties.
Turn on Allow executing file as program (the wording varies).
Double-click the file to open it.

On Ubuntu 24.04 and newer, an AppImage may not open without an extra system part. If that happens, use the .deb instead.

Connect your songs

The first time you open BubbleFacts, a short setup starts. Its first step connects the app to your StreamerSongList, so it can see which song you're playing.

Click the big Sign in with StreamerSongList button. Your web browser opens.
Sign in with the Twitch account you use on StreamerSongList.
Go back to BubbleFacts. Your channel is filled in for you, and setup moves on.

Having trouble signing in?

You can connect with a token instead. Open Having trouble signing in? under the sign-in button. It asks for two things.

Your channel name. Type your StreamerSongList channel name.
Your Streamer Access Token. To get it:
1. In your web browser, sign in at streamersonglist.com.
2. Go to Settings, then Access.
3. Create a Streamer Access Token and copy it.
4. Back in BubbleFacts, paste it in.
Click Connect. If it doesn't work, check the channel name, or create a new token and paste it again.

Treat a token like a password. Keep it off your stream and out of screenshots.

Your sign-in stays private

BubbleFacts stores your sign-in, or your token, encrypted on your computer.

The built-in AI downloads on its own

As soon as the app opens, it starts downloading its built-in AI in the background. That's Llama 3.2 3B, about 2 GB, and it's a one-time download. You don't need to wait for it. Until it's ready, songs get backup facts, so BubbleFacts works right away. If your connection drops, the download tries again on its own. The app's dashboard shows how far along it is.

Put BubbleFacts on your stream

The second step puts BubbleFacts into OBS, on top of your scene. You do this once. BubbleFacts needs to run on the same computer as OBS.

Open OBS Studio.
Choose the scene you normally stream from.
Drag the Drag this into OBS tile from BubbleFacts into the Sources list in OBS.

As soon as OBS loads it, BubbleFacts puts a test bubble on your stream and says It's on your stream! OBS names the new source "BubbleFacts" and sizes it to fit your canvas.

Not ready yet? Click I'll add it later. The app's dashboard has a Drag into OBS tile for when you are.

Nothing happens when you drop it on Windows?

OBS may be running as administrator. Close OBS and open it the usual way, or add it by hand (below).

Add it by hand

In OBS, under Sources, click + and choose Browser. Name it "BubbleFacts" and click OK.
In BubbleFacts, click the Copy button next to the location of BubbleFacts.html. (Later, you'll find it under Help and troubleshooting on the dashboard.)
In OBS, check Local file. Click Browse and choose the file at the location you copied. (You can paste the location into the file window: on a Mac press Cmd+Shift+G first; on Windows paste it into the address bar.)
Set Width and Height to your canvas size. That's usually:
Width 1920

Height 1080
Not sure? In OBS, open Settings, then Video, and look at Base (Canvas) Resolution.
Click OK.

Use Local file, not a URL. It doesn't matter whether you open OBS or BubbleFacts first: the overlay keeps trying until the app is running.

Stream from more than one scene?

Add BubbleFacts to just one scene, for example a scene called "BubbleFacts overlay". Then, in each of your other scenes, click + under Sources, choose Scene, and pick "BubbleFacts overlay". That's easier than adding BubbleFacts six times, and any change happens everywhere at once.

Tell us about your music (optional)

Setup's last step is optional. Click Skip to use the defaults, or answer three things. You can change all of them later in the app's Settings.

I play my own compositions

This is off to start with. Check it if you play your own pieces. Songs tagged "Originals" in StreamerSongList, or with you as the artist, then get facts from your song list instead of a Wikipedia lookup: that it's yours, how often you've played it, and who requested it.

When it's checked, an optional box appears: About your compositions. Type facts about your pieces there, one per line. They show when you play your originals.

I do live learns

This is on to start with. When someone requests a song that isn't on your list, a LIVE LEARN banner shows while you learn it, with no fact bubbles. If you uncheck it, those requests are treated like any other song.

Backup facts

When a song has no Wikipedia article, the AI isn't used. Instead, the app shows backup facts from "packs": short lists of facts about a kind of music.

The included facts are only a few examples

BubbleFacts comes with only a few example facts. They're short, they aren't updated or maintained, and they won't know your songs. For facts that fit your stream, add your own.

Pick one of two options:

Set up my own facts later (already picked for you). The app uses the examples for now. You can add your own any time in Settings, under Backup facts.
Add my own facts now. Type your facts in the box, one per line.

Then click Next. That's the whole setup.

Only add facts you've checked

Your facts go on stream exactly as you write them. Nothing checks them for you.

Add or change your facts later

In the app, open Settings, then Backup facts.
In Your own facts, type one fact per line.
Optional: in About your own compositions, add facts about your original pieces. These show when you play one of your originals.

The app needs at least 5 backup facts in total. That counts the example packs you have checked plus your own facts.

The example packs

Video game music: 24 facts
Classical: 7 facts
Film and TV scores: 8 facts
Pop and rock: 7 facts
Piano: 4 facts
General music: 6 facts

Check that it works

Make sure BubbleFacts is open.
Play a song from your StreamerSongList queue.
A gold NOW PLAYING banner appears at the bottom of your OBS preview. A few seconds later, the first fact bubble pops up.

The dashboard shows three lights: Songs, Facts and Stream. To check the overlay any time, click Show a test bubble.

General facts instead of facts about the song? The built-in AI may still be downloading. Until it's ready, songs get backup facts. The dashboard shows its progress.

Seeing a small red dot in the bottom-right corner instead? The overlay can't reach the app. See the table below.

While you stream

Need the bubbles gone right now? Click Pause bubbles on the dashboard, or in the BubbleFacts menu in your menu bar (Mac) or system tray (Windows and Linux). Turn them back on the same way.
Closing the window doesn't stop it. BubbleFacts keeps running in your menu bar (Mac) or system tray (Windows and Linux), with a status light. To stop it, choose Quit from that menu.
It fixes itself. If something inside the app gets stuck, it restarts that part on its own, so you can keep playing.
Wrong fact? Click Report this fact in the app. For anything else, open Help and troubleshooting and click Report a problem. A report opens on GitHub in your browser for you to read before you send it. You need a free GitHub account. See how reports work.
New versions. When one is out, the app tells you and gives you a download link. See what's new.
Bubble size. The bubbles grow and shrink with the source, so they look the same on a 720p, 1080p or 4K canvas. If viewers on phones find them small, open Settings, then Bubbles, and set Bubble size to Large or Larger.
Add your own backup facts. Songs with no Wikipedia article get backup facts. The ones included are only a few examples, so add your own. If a song had no article and you haven't added any, the dashboard suggests it. See how to add them.

Optional: use an online AI instead

You don't need to choose an AI. The built-in AI downloads on its own and writes the facts on your computer. But on an older computer, or one that's already busy while you stream, you can have an online service write them instead.

In the app, open Settings, then Who writes the facts. You can switch back any time.

Who writes the facts
Option	Cost	What you need
Built-in AI (the default)	Free	Nothing. It downloads on its own (about 2 GB, one time). No account or key needed.
Online: Groq	Free, with a daily limit	A free Groq account and an API key from console.groq.com/keys. Good for older computers, or if yours is already busy while you stream.
Online: Anthropic	Paid, but cheap: a fraction of a cent per song	An Anthropic account and an API key from platform.claude.com/settings/keys.
Your own Ollama	Free	For people who already use Ollama, installed with its normal installer from ollama.com. Point BubbleFacts at it. The app downloads the Ollama model for you the first time.

An API key is a long password that lets the app use an online service for you. Copy it from the service's website and paste it into BubbleFacts. It's stored encrypted on your computer.

If the built-in AI can't run on your computer

This can happen on older processors. The app tries a simpler, processor-only mode on its own. If that doesn't work either, it walks you through switching to Online: Groq, which is free.

If something goes wrong

Find what you're seeing in the left column.

Troubleshooting by symptom
What you see	Likely reason	What to do
Mac says the app "can't be opened because Apple cannot check it"	The app isn't signed yet	Right-click the app, choose Open, then Open again. Or use System Settings, Privacy & Security, Open Anyway.
Windows says "Windows protected your PC"	The app isn't signed yet	Click More info, then Run anyway.
A small red dot in the bottom-right corner	The overlay can't reach the app	Open BubbleFacts. If it's already open, check the Stream light on the dashboard, or quit it from the menu bar or tray and open it again.
Nothing at all, not even a red dot	OBS isn't loading the overlay	Check the source is visible (the eye icon in Sources). Then drag the tile from BubbleFacts into OBS again. If you added it by hand, check it uses Local file and points at the file shown under Help and troubleshooting.
No test bubble, and no "It's on your stream!"	OBS didn't load the overlay, or BubbleFacts runs on a different computer	BubbleFacts needs to run on the same computer as OBS. Try dragging the tile again, or add it by hand.
The app says StreamerSongList rejected your sign-in or token	Your sign-in ran out, or the token is wrong or expired	Sign in again from the app's Settings (or paste a new token if you use one, see step 2).
The AI download stops or fails	Not enough disk space, or the connection dropped	If the connection dropped, the app tries again on its own. If you're low on space, free up at least 4 GB. Or use Online: Groq for now (see Optional: use an online AI instead).
Facts are general, never about the song	No Wikipedia article was found	For game music, put the game's name in the artist field in StreamerSongList. Obscure songs often have no article, so they get backup facts instead. The included ones are only a few examples: add your own.
Only general facts, soon after installing	The built-in AI is still downloading	Until it's ready, songs get backup facts. Check the progress on the app's dashboard.
Fewer bubbles than expected	Some captions failed the fact check	That's normal for songs with short articles. It means the check is working.
The banner is cut off, or the bubbles sit in the wrong place	The source isn't the size of your canvas	Remove the source and drag the tile from BubbleFacts into OBS again. Or right-click the source, choose Properties, and set Width and Height to your canvas size (see adding it by hand).
The source is blank, or stops updating	An OBS Browser source setting, or an old copy of the page	Right-click the source, choose Properties, and click Refresh cache of current page. Leave Shutdown source when not visible and Refresh browser when scene becomes active off, and don't clear the Custom CSS that OBS fills in.
Viewers on phones say the bubbles are small	Phone screens are small	In Settings, then Bubbles, set Bubble size to Large or Larger.
You need the bubbles off the screen right now	Anything	Click Pause bubbles on the dashboard, or in the menu bar or tray menu.
Your stream stutters when a song starts	The built-in AI is sharing your computer with OBS	Switch to Online: Groq in Settings, under Who writes the facts (see Optional: use an online AI instead). It's free and does the work online.
The app says the built-in AI can't run on this computer	The processor or graphics can't run it, even in processor-only mode	Follow the app's steps to switch to Online: Groq. It's free. See the system requirements.

Still stuck? In the app, open Help and troubleshooting and click Report a problem, or ask on Discord. The help page lists every option.