HuddleFM

A self hosted music bot for Slack huddles, controlled from Slack.

Warning: This codebase is almost entirely generated by AI, and most of the code hasn't been read. Use at your own risk.

Features

Search YouTube for songs, albums and playlists, or paste links from YouTube, SoundCloud and more
A shared queue to reorder, shuffle and loop
Playback, volume and permissions, all from buttons in Slack
Album art, progress and synced lyrics on the bot's video tile
Autoplay from YouTube or a Huddle mix of what people listen to, and 💖 to hear more like a song
Video mode: watch YouTube or Jellyfin together on a screen share, with captions and chapters
Live streams from YouTube and Twitch
Scrobbling to Last.fm and ListenBrainz
Auto-ducking while people talk
Multiple huddles at once, recaps and a stats canvas
One Docker container to self host

Client plugins

Put HuddleFM's controls, queue and settings in the huddle's own toolbar. Built from fbf1c23.

Taut About

HuddleFM.jsInstall from Slack's Preferences → Taut

Slick About

HuddleFM.jsFor the desktop app and the browser extension

HuddleFM.user.jsUserscript, for Violentmonkey beside Slick

Usage

Invite the bot to a huddle, or mention it in the huddle's thread. It joins and posts a player in the thread, and you're the host. Mention it again with nothing else to bring the player back to the bottom.

Settings has permissions, video mode, autoplay and the rest. Channel managers can save a channel's defaults, and Your data shows and deletes what HuddleFM keeps about you.
Video mode takes one of the huddle's two screen share slots while it's on.
Jellyfin: paste a link from Jellyfin's web app into Add to queue and approve the Quick Connect code. The server has to be reachable from the internet, and only you can use servers you link.
Ask it: with OPENROUTER_API_KEY set, mention the bot with a request like @HuddleFM add something by Radiohead. It has your own permissions, and replies only to you.

Self hosting

You need a dedicated Slack user for the bot, with a Slack app (Socket Mode) and browser session credentials from that same user.

Get compose.yaml:

curl -fsSL -o compose.yaml https://raw.githubusercontent.com/ingoau/huddlefm/main/compose.yaml

Create .env next to it:

SLACK_WORKSPACE_URL=https://example.slack.com
SLACK_XOXP=xoxp-...   # Slack app user token (Web API)
SLACK_XAPP=xapp-...   # Slack app-level token (Socket Mode)
SLACK_XOXC=xoxc-...   # Browser session token for joining Huddles
SLACK_XOXD=xoxd-...   # Browser `d` cookie for that session

SLACK_XOXP, SLACK_XOXC and SLACK_XOXD must belong to the same Slack user; HuddleFM checks on startup. On Enterprise Grid, set SLACK_ENTERPRISE_XOXC instead of SLACK_XOXC.

Start it:

docker compose up -d

Data and logs live under ./data. To update, run docker compose pull && docker compose up -d; active sessions resume after a short restart.

Everything else, from scrobbling to limits and YouTube sign-in, is in docs/configuration.md.

About this project

I Codex built this for the Hack Club Slack because we didn't really have any music bots. We did have a bot that could join huddles, but it was more for video, and required one of the two precious screen sharing slots to be used.

I decided to build a bot that was really intuitive for music, and would just work. I started planning it, going back and forth with Codex and making sure it was on the right track. I was happy with the plan and told it to implement it. One hour later I had something that mostly worked!

I worked on it for a few days, fixing bugs, adding lots of features, and I'm mostly happy with the state of it now! I even got Claude to review it and it said it wasn't just classic AI slop so I guess that's good?