BubbleFacts

Help

Help and support

BubbleFacts is a free project maintained by one person, so replies may take a few days. Thanks for your patience.

Only the newest version gets help. If yours is older, click Update now in the app first: it may already be fixed.

While a new version is being tested, only the newest test version gets help. If yours is older, click Update now in the app first: it may already be fixed.

  1. 1. Check the troubleshooting table

    Most problems have a quick fix. Find what you're seeing in the troubleshooting table.

  2. 2. Click "Report a problem" in the app

    You'll find it under Help and troubleshooting on the dashboard. The app fills in a GitHub report with your app version, your system and recent log lines, with your token removed. It opens in your browser, so you can read and change it before you send it. You need a free GitHub account, and the report is public. See how reports work.

    No GitHub account? Click Copy report next to it instead. It copies the same report, with your token removed, so you can paste it in a post in #help on the Discord or in an email. Read it first and take out anything you'd rather keep private.

  3. 3. Wrong fact? Click "Wrong"

    Click Wrong next to the fact on the dashboard. It comes off your stream right away. Then Report it (opens GitHub) fills in a report with the song and the fact. These are the most useful reports of all. See What if a fact is wrong?

  4. 4. Ask a question

    Search #help on the BubbleFacts Discord first: other music content creators may have asked already. If your answer isn't there, start a new post for each question.

    No Discord account? Email bubblefacts@frolic.org.

  5. 5. Share an idea

    Post it in #feature-requests on the BubbleFacts Discord. Approved ideas become GitHub issues, so you can follow them.

Found a security problem?

Please don't post it in public. Report it privately on GitHub instead.

Also useful: system requirements, how to uninstall, and the short list of questions on the home page.

Known issues

  • Not signed yet. Your computer asks you to confirm the first time you open a fresh download. The download page shows what to click.
  • A wrong fact can still slip through. The small built-in AI sometimes joins two true statements into one that isn't. Click Wrong, during the song or after it under Earlier songs.
  • Linux is tested automatically, but no tester uses it day to day yet. Tell us how it goes.

The full, current list is on GitHub.

More questions

Which computers does it work on?

Macs with macOS 13 Ventura or newer (Apple silicon or Intel), Windows 10 or 11 (64-bit), and 64-bit Linux, tested on Ubuntu 24.04 and newer. You need at least 8 GB of memory and OBS Studio 28 or newer. It doesn't run on phones, tablets or Chromebooks. See the system requirements for details.

What if my computer can't run the built-in AI?

You can still use BubbleFacts. On Windows and Linux, the app first tries a simpler mode that uses only the processor. If that doesn't work either, it tells you, and songs still get facts from music databases and your own facts. See If the built-in AI can't run.

Will it slow down my stream?

BubbleFacts runs beside OBS. The boxes on screen are light, simple animations. The work happens when a song starts: the built-in AI spends a few seconds writing facts, using your graphics chip or processor.

On most computers you won't notice. If your computer is busy, BubbleFacts notices by itself: it asks the AI for fewer facts and gives the processor back to OBS, and the dashboard says so. To have facts ready before you stream, turn on Prepare my songs.

Does it work offline?

Partly. The built-in AI downloads once, on its own, when you first open the app. After that, it runs without the internet. But the app still needs the internet to look songs up on Wikipedia, Wikidata and MusicBrainz, and to read your song requests from StreamerSongList or StreamElements, if you use one. Since you're streaming, you'll be online anyway.

Can I use it without StreamerSongList?

Yes. BubbleFacts learns which song you're playing from your StreamerSongList queue, your StreamElements song requests (Media Request player), or a text file your music app writes, such as Streamling's, Nightbot's or the Now Playing app's. Both services are free, and a file needs no account. See how to connect StreamElements or follow a now playing file.

What does the built-in AI do?

It turns a few details from a Wikipedia article into short captions that fit on screen. That's all. It never writes from memory, and every caption is screened against the article before it's shown: names, who did what, years and similar claims have to appear there. That catches most mistakes, not every one. Facts also stay about the music and family-friendly: no scandals, crime or threats, and nothing that labels who a person is. The built-in AI is Llama 3.2, a small AI model made by Meta that runs on your own computer. It downloads once, about 2 GB.

Where does my data go?

Almost nowhere. The app runs on your computer and reads your song requests from StreamerSongList or StreamElements, or from a file on your computer. It sends song titles and artist names to Wikipedia, Wikidata and MusicBrainz to look songs up. If you pick an online AI, the song title and article text go to that service. Nothing is sent to this project. Your sign-in, token and keys are stored encrypted on your computer (on Linux, that needs a keyring). The privacy page has the details.

What if a fact is wrong?

Click Wrong next to it on the dashboard: it comes off your stream right away, and BubbleFacts stops using that source for that song. Playing when you spot it? Mark it after the song, under Earlier songs. See If a fact is wrong for what happens next and how to report it.

StreamElements stopped following my songs. What do I do?

Usually nothing. Pausing the StreamElements player doesn't stop BubbleFacts. If StreamElements says a song is playing but BubbleFacts can't see which one for 30 seconds, the dashboard says Reconnecting. If that lasts about two more minutes, BubbleFacts restarts its connection on its own. Your song queue isn't touched.

If the app says StreamElements didn't accept your JWT token, paste a new one in Settings, under Your song list. If it keeps happening, click Report a problem and add your logs (see How do I send my logs?).

How do I send my logs?

Logs show what BubbleFacts saw and did, which helps us find a problem.

  1. On the app's dashboard, open Help and troubleshooting.
  2. Click Show logs. A folder opens.
  3. Find the newest files whose names start with bubblefacts- (there's one for each day), plus songs.log.
  4. Attach them to your GitHub report.

Logs list the songs you played. Look them over before you share them in public.

Where else can I get help?

Start with the troubleshooting table. Then ask in #help on the BubbleFacts Discord, or click Report a problem under Help and troubleshooting in the app. The steps at the top of this page list every option.