Getting started

Install the app

Download the version for your computer from the download page (not sure which Mac you have? Here's how to check), then follow the steps for your system.

Mac

1. Open the BubbleFacts .dmg file from your Downloads folder.
2. Drag BubbleFacts into the Applications folder.
3. Open BubbleFacts from your Applications folder. On macOS 15 (Sequoia) and newer, your Mac says "BubbleFacts" Not Opened. Click Done.
4. Open System Settings, then Privacy & Security. Scroll down and click Open Anyway next to the note about BubbleFacts, enter your Mac password, and click Open Anyway once more.

On older Macs: right-click BubbleFacts (or Control-click), choose Open, then click Open again. You only need to do this once.

Windows

1. Open the BubbleFacts .exe file from your Downloads folder. If your browser says the file isn't commonly downloaded: in Microsoft Edge, point at the download, click …, then Keep, Show more and Keep anyway.
2. Windows may show a blue box saying Windows protected your PC. Click More info, then Run anyway.
3. 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).

1. Double-click the BubbleFacts .deb file in your Downloads folder.
2. 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.
3. Click Install and type your computer's password when asked.

Other Linux: use the AppImage.

1. Right-click the BubbleFacts .AppImage file and choose Properties.
2. Turn on Allow executing file as program (the wording varies).
3. 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. Step 1 connects the app to your song requests, so it can see which song you're playing. It asks Where do your song requests come from? Leave StreamerSongList picked, or see StreamElements and a now playing file below.

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

Use StreamElements instead

Do viewers request songs through StreamElements' Media Request player? Connect that instead. StreamElements has no sign-in button for apps like this, so you paste a token.

1. Under Where do your song requests come from?, choose StreamElements.
2. In your web browser, open your StreamElements dashboard. (The Open StreamElements link in the app takes you there.)
3. Go to Account, then Channels, and click Show secrets.
4. Copy the JWT token (not the Overlay token).
5. Back in BubbleFacts, paste the token. Your channel name is optional: the token tells BubbleFacts which channel it is.
6. Click Connect. BubbleFacts checks the token, then setup moves on.

The JWT token works like a password. Keep it off your stream and out of screenshots.

StreamElements only knows each request's YouTube video title, such as "Artist - Song (Official Video)". BubbleFacts reads the artist and song out of it, so clearly titled videos get the best facts. There are no live learns with StreamElements, so that setting is hidden.

To switch later, or to paste a new token, open Settings, then Your song list, and click Save.

Follow a now playing file instead

Does your music app write the song that's playing to a text file? BubbleFacts can follow that file, with no sign-in and no token. DJs: most DJ software needs a helper app to write that file. Brand-new club tracks may get fewer facts, since BubbleFacts needs an article or database entry to work from.

1. Under Where do your song requests come from?, choose Now playing file.
2. Using Streamling on Windows? Leave Streamling picked. BubbleFacts reads the file Streamling keeps in your Documents folder, so there is nothing to choose.
3. Using Nightbot's desktop app on Windows or Mac? Pick Nightbot. BubbleFacts reads the newest song file Nightbot keeps in Documents/Nightbot, so there is nothing to choose. Keep Nightbot's desktop app running while you play, since it writes the file.
4. Using another app? Pick Another app's file, click Choose file, and select the text file your app writes the song to. Using the Now Playing app? In that app, add a File Output with the template {{artist}} - {{title}}, then choose that file here. File Output needs the app's Pro version.
5. Tell BubbleFacts how the line reads: Artist - Title, or Title only.
6. Click Continue, and setup moves on.

The app shows which folder it reads (your OneDrive Documents folder, if that's where yours lives). The Songs light says Following your file while a song is in it, and Watching your file when there isn't one. An empty file means no song is playing, and so does a file that hasn't changed in 15 minutes. A file says nothing about who requested a song, so there are no live learns with it.

A line with only a title, like "Song - Official Music Video", gets an artist only when exactly one artist has a recording with that title. Common titles stay without one. That song gets basic facts from the music databases, without written captions.

Put BubbleFacts on your stream

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

1. Open OBS Studio.
2. Choose the scene you normally stream from.
3. In BubbleFacts, drag the tile that says Drag this into your Sources list onto 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.

Next time, open OBS and BubbleFacts in either order. For a few seconds after BubbleFacts starts, the dashboard says Connecting to OBS while OBS picks it back up. If the BubbleFacts source reloads in the middle of a song, its bubbles catch up within a few seconds, without repeating the ones viewers already saw.

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

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.

Streaming vertically too? (Twitch, TikTok, YouTube Shorts, Instagram Live)

Phone-shaped streams get their own overlay, BubbleFacts Vertical. Its bubbles are sized for a phone screen and stay clear of the buttons, top bar and chat those apps show over your video, including Twitch's phone view. It runs beside the usual one, so one BubbleFacts can feed a landscape scene and a vertical scene at the same time.

If OBS's canvas is vertical (1080 by 1920 in Settings, then Video):

1. In BubbleFacts, open Settings and find Vertical stream.
2. Drag the tile that says Drag this into your vertical scene onto the Sources list in OBS. OBS sizes it for you.

If you use Aitum Vertical (or another plugin that adds a second, vertical canvas), its Sources list doesn't take a dragged file, so add it there once by hand:

1. In the vertical Sources list, click + and choose Browser. Name it "BubbleFacts Vertical" and click OK.
2. In BubbleFacts, open Settings, then Vertical stream, then Using Aitum Vertical, or a second canvas?, and click Copy.
3. In OBS, check Local file, click Browse and choose the file at the location you copied.
4. Set Width to 1080 and Height to 1920, and click OK.

On Twitch, landscape and vertical at once (Twitch calls this Dual Format): people watching on a computer see your usual layout, and people holding a phone upright see the vertical one. You need OBS 32 or newer and the free Aitum Vertical plugin. Twitch's own steps are in Dual Format Streaming on Twitch; in short:

1. Install Aitum Vertical, then open OBS.
2. In OBS, open Settings, then Stream. Under Multitrack Video, check Enhanced Broadcasting. In the same window, set Additional Canvas to Aitum Vertical (if it isn't there, close and reopen OBS). Click OK.
3. Add BubbleFacts Vertical to your vertical scene, in Aitum Vertical's own Sources list, with the four steps just above.
4. Don't add a chat box to the vertical scene: Twitch shows chat over the phone view by itself.
5. Click Start Streaming as usual. Both layouts go live together.

To check, watch your stream in the Twitch app on your phone, held upright. Viewers can make Twitch's chat taller; bubbles stay clear of it either way.

Click Show a test bubble on the dashboard: it shows on both overlays. If the vertical one says to set the width and height, open the source's properties in OBS and set 1080 and 1920.

Under Vertical stream you can also choose its own Bubble size on the vertical stream, and whether bubbles show Near the top or Just above the chat. On a phone screen there's room for one bubble at a time, so each new one replaces the last.

About your music (optional)

Setup is done once the test bubble shows: click Start using BubbleFacts. This part is optional. Open it from the link under the OBS step, or any time 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. Their bubbles show how often you've played it and who asked for it. They don't say you wrote it, because your name is already on screen.

When it's checked, an optional box appears: About your own 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, and only for StreamerSongList. When someone requests a song that isn't on your list, a LIVE LEARN banner shows while you learn it (to hide just the banner, uncheck Show a LIVE LEARN bubble during a live learn under Bubbles). Facts still show when BubbleFacts can find the song, or when you've added facts for it; it never fills in with custom facts. If you uncheck it, those requests are treated like any other song.

Check that it works

1. Make sure BubbleFacts is open.
2. Play a song from your StreamerSongList queue or your StreamElements song requests, or start one in the music app that writes your now playing file.
3. A Now Playing bubble (gold, in the Classic style) appears at the bottom of your OBS preview. A few seconds later, the first fact bubble pops up. Basic facts, like a song's year and album, can come first. The written facts follow when they're ready.

The dashboard shows three lights: Songs, Facts and Stream. To check the overlay any time, click Show a test bubble. It shows on top of whatever's playing and leaves that song's bubbles alone.

Under Songs, a small line says how BubbleFacts hears about your songs: Hearing your queue live (StreamerSongList) or Hearing your song requests live (StreamElements) when changes arrive as they happen, Checking your list every 15 seconds (StreamerSongList) or Checking your song requests every 15 seconds (StreamElements) when it has to ask, or Checking your file every 2 seconds for a now playing file. Either way your songs come through; live is just quicker.

Few or no facts at first? BubbleFacts may still be getting ready. The dashboard's Facts light shows how far along it is.

Bubbles coming late? Under the Facts light, Facts took 45 s says how long the AI needed for the song on now. A long time usually means the computer is busy with the stream.

BubbleFacts notices this by itself, with nothing to set. When facts keep coming late, it asks the built-in AI for fewer of them, and the dashboard says Your computer is busy, so fewer facts. When a song ends before its facts are ready, it shows only the quick facts from the music databases and says Your computer is busy, so quick facts only. While a game or OBS keeps the processor nearly full, the AI also works more slowly in the background, so your stream doesn't stutter. Every fact is still checked the same way. Once songs get their facts on time again, everything goes back to normal on its own.

Seeing a small red dot in the bottom-right corner instead? The overlay can't reach the app. See If something goes wrong.

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. They stay paused even if BubbleFacts fixes itself mid-song; quitting and reopening the app turns them back on.
• 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 Wrong next to it on the dashboard. See If a fact is wrong.
• Something else wrong? 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. Click Update now, then Install now between songs. Your settings are kept. To try betas before everyone else, choose Beta under Settings, then General, then Updates. See Updating and what's new.

If a fact is wrong

The dashboard's On stream now list shows the facts for the song you're playing. Each one has a Wrong button.

1. Click Wrong next to the fact. It comes off your stream right away, even if its bubble is showing, and so do the song's other bubbles from the same source.
2. BubbleFacts never uses that fact's source for that song again: the Wikipedia article, or Wikidata and MusicBrainz. When a song's own article says little about how it was made, some facts come from a related article, like its album's or a game's "Music of" page; the dashboard names that article. Wrong on the song's own article takes those off too. It remembers this after you quit and reopen the app. A wrong fact almost always means it found the wrong source. Clicked by mistake? Click Undo. (Your own facts are only taken off for now, and show again until you change them. The note after Wrong has an Edit it button that opens the fact for you.)
3. Optional: click Report it (opens GitHub). A report opens on GitHub in your browser, with the song and the fact filled in, for you to read before you send it. You need a free GitHub account.

Playing when you spot it? No need to stop. After the song, open Earlier songs under On stream now and click Wrong there. It won't come off the stream (it's already gone), but BubbleFacts won't use it, or its source, for that song again.

Or mark it without your hands, with a foot pedal or a Stream Deck:

1. In Settings, then Bubbles, set Hands-free Wrong to a key, for example Ctrl+Alt+W (Control+Option+W on a Mac). Click Save.
2. Set your pedal or Stream Deck button to press that key. Most can send a key combination; see their own instructions.
3. When a wrong bubble shows, press it. That bubble comes off your stream, just as if you'd clicked Wrong. If no bubble is up, it's the last one shown for this song. Nothing on stream shows it happened.

The dashboard says which fact it was, with Undo, for after the song. It works while BubbleFacts is in the background. While bubbles are paused it does nothing.

Reports of wrong facts are the most useful kind. They show where the fact check needs to be stricter.

Make it yours (any time)

None of this is needed to start. Come back to it whenever you like.

Custom facts

When a song has no Wikipedia article, or BubbleFacts isn't sure the article is about that song, the AI isn't used. BubbleFacts looks the song up on Wikidata, then MusicBrainz, two free music databases, and fills in plain sentences such as the year and the album. Facts from the music databases and the AI's captions all stay about the music and family-friendly: no scandals, crime or threats, and nothing that labels who a person is.

If neither has the song, the app shows your custom facts: short facts you write yourself. With none, that song gets no bubbles rather than filler, which suits request channels.

Custom facts can show during any song no source knows, so write facts that fit any song, like something about you or your instrument. For a fact about one song, start the line with its title in brackets, like [Song of Storms] It plays in a windmill. It then shows only for that song, ahead of other facts. Start it with an artist or game instead, like [Chopin] …, and every song by them shares it: each song gets one, taking turns, so a game with hundreds of songs on your list doesn't open every one the same way. You can also add facts while the song plays.

Add or change your facts later

1. In the app, open Settings, then Custom facts.
2. In Your own facts, type one fact per line.
3. Optional: facts about your original pieces go under You and your music. Check I play my own compositions, then type them in About your own compositions just below. These show when the song's artist is your channel name or Your name on stream, so a friend's piece never gets them.

Your custom facts take turns, and one that showed in the last hour waits, so a song may get fewer bubbles instead of a repeat. Five or more custom facts keep the bubbles full.

Add facts for one song

Some songs aren't on Wikipedia or in any music database: a music content creator's original, a friend's band, a song you wrote together. You can give a song its own facts.

1. While the song plays, click Add facts for this song under On stream now (it says Edit your facts for this song once you have some). Getting ready before a show? Click Add facts for another song (or Add facts for a song when nothing is playing) and start typing the title. With StreamerSongList, songs from your list that match show up under it; pick one with the mouse or the arrow keys and Enter, and the title and artist fill in exactly as your list has them. Not on your list, or using StreamElements? Type the title and the artist or game as they'll appear on the request.
2. Optional: under Who wrote it?, type the songwriter, but only if you're sure. BubbleFacts never guesses who wrote a song.
3. Optional: add their link, like their Twitch page. It always gets its own bubble: "More from" the songwriter you named, or "More from this song's creator" if you didn't name one.
4. Another music content creator's song? Once the artist ends with their @name (like "Jane (@janeplayskeys)") or their link is their Twitch page, click Fill from their Twitch About to add the text from their channel's About, then check it and edit it. The first time, connect Twitch in Settings, under You and your music: Twitch opens with a code already filled in. Check it matches the one BubbleFacts shows, then click Authorize.
5. Type your facts, one per box (Add another fact gives you another box), and click Save and show. About 160 characters fit in a bubble. A fact can be up to 300 characters, and a song can have up to 20 facts; the editor shows a count as you get close.

With Twitch connected, you often won't need to. When no source knows a song and its artist is one name that exactly matches a Twitch channel, BubbleFacts shows a line or two from that channel's About, starting "From their Twitch About:". If it found the wrong channel, click Wrong. To turn this off, uncheck Check Twitch for artists no source knows in Settings, under You and your music.

Want no facts at all for a song, or for everything by one artist? Check No facts for this song or No facts for this artist in the same place, or click them under Earlier songs after the song. BubbleFacts then looks nothing up for it, and only your own facts show.

Playing commercials, station IDs or jingles between songs? BubbleFacts skips a track with no bubbles when its title says what it is, like "Moonbrew Cola (Commercial)", "(Jingle)" or "Station ID", or when its artist is "Commercials". A track without those words looks like any song, so add one to its title in your music player, or use the switches above.

Every song you've done this for is listed in Settings, under Songs with their own facts, with Edit and Remove.

If the song is still playing, they show right away. Either way, they show exactly as you wrote them every time that song plays. On the dashboard, each fact says where it came from, so you can tell your own from Wikipedia's. Click a Wikipedia source to see the sentence the fact was written from, and to open the article.

Where bubbles go, and how they look

• Bubbles covering your camera or keyboard? In Settings, then Bubbles, set Where bubbles appear to the top, bottom, left or right. To have every bubble show in the same place, choose one spot, like Top right or Bottom center: each new bubble replaces the last one there. For anything finer, resize and move the BubbleFacts source in OBS.
• 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. The new size shows on stream as soon as you save.
• Want viewers to know where the facts come from? Now and then, show where the facts come from is on to start with. It adds one extra bubble when the first song's facts start, then about every 5 songs, for viewers who join later. To show it less often, uncheck it in Settings, then Bubbles. It still shows when you click Start Streaming in OBS, and again after 20 minutes without facts, so your viewers know where the facts come from and that they can be wrong. Songs you play before you go live don't use it up.
• More facts per song? In Settings, then Bubbles, set Facts per song. BubbleFacts finds up to 4 facts for a song, so a higher number only adds bubbles when you've written your own. Your own facts can go past 4, up to the number you set.
• Already show the song yourself? In Settings, then Bubbles, turn off Show a Now Playing bubble when a song starts. Fact bubbles stay.

To change how the bubbles look:

1. Open Settings, then Bubbles.
2. Under Style, pick Classic (dark blue), Light, Minimal, Retro game or High contrast (the easiest to read, for viewers with low vision or on small screens). It changes the fact bubbles and the Now Playing bubble, on your vertical stream too.
3. Want your own colors? Check Use my own colors and pick an Accent (the border and the Now Playing label) and a Background. BubbleFacts picks light or dark text, whichever is easier to read on your background.
4. Click Save. The bubbles change on stream right away; there's no need to touch OBS. To see it, click Show a test bubble on the dashboard.

Every style keeps the text the same size and easy to read, and never changes what a fact says. Already styling the bubbles yourself in OBS's Custom CSS box? It keeps working, and wins over the style you pick here.

Prepare my songs: facts ready before you play

Writing a song's facts takes the AI on your computer a little while, so the first bubble of a song can come late. BubbleFacts can write them ahead of time, while you're not streaming, so they show as soon as each song starts.

1. Open Settings.
2. Under Prepare my songs, check Prepare facts for my songs while I'm not streaming, then save.
3. Leave BubbleFacts running with OBS closed and your computer plugged in, for example overnight.

It starts with the songs your viewers request most. It works only while OBS is closed and your computer is plugged in, and stops the moment you open OBS, keeping everything it has done. Next time your computer is free, it carries on where it stopped.

It prepares every song on your StreamerSongList list, and every song that has played on your stream, so requests from StreamElements, Streamling or Nightbot get ready too after you've played them once.

To see how far it has come, click Your songs at the top of the BubbleFacts window. It says how many songs are ready and about when the rest will be, for example "1,240 of 5,000 songs ready. The rest by about Thursday.", worked out from how fast your computer has been going. It also shows how much of what your viewers request is ready, and the songs no source knows anything about. It's just information: there's nothing to check or approve.

It uses the AI on this computer, never an online AI. The facts, and the list of songs played on your stream, stay on this computer. A fact you mark Wrong never shows again, prepared or not.

Share song facts with other apps

An app that takes song context can use the song's facts to answer chat's questions.

1. Get the web address and an API key from the other app.
2. In BubbleFacts, open Settings and turn on Share song facts with other apps.
3. Enter the address and your channel name, paste the key, click Test connection, then save.

Only the song and its facts are sent, and it's off until you turn it on. Pausing bubbles pauses sharing too. See the privacy page.

Your facts are backed up

• Your facts are backed up for you. BubbleFacts saves a copy of your settings and facts whenever they change, without your sign-in, your keys, which AI writes your facts, or the facts Prepare my songs wrote. To move to a new computer, open Settings, then Advanced, click Back up…, and use Restore… on the new one.