Spotibot - guide and updates

Getting started

Three ways to ask for a song. They all do the same thing.

Join a voice channel.
Type /play and start typing a song (suggestions appear as you type), or !play africa toto, or paste a YouTube or Spotify link (songs and playlists both work).
The bot joins, and the queue message appears. Use its buttons for everything else.

Tip: !playnext <song> (or /play with next: true) puts a song right after the current one instead of at the end.

The queue message and its buttons

Spotibot keeps one message per server and edits it as songs load and play, so the chat doesn't fill up. !queue moves it back to the bottom if it scrolls away.

Now Playing

Africa - Toto

1:23 / 4:55 ━━━━○────────

Up next
1. Mr. Brightside - The Killers 3:42
2. Dreams - Fleetwood Mac 4:17
3. ...

Page 1/4 | 18 queued | 2 loading
Skipped Yellow (Sam)
Gaming mode on: say "Spotibot, play <song>" | leaves after 30 min idle

-10s-5sPause+5s+10s

SkipStopLeave◀ PrevNext ▶

Gaming mode: onRadio: onShuffleRepeat: offSave

Leave after 30 min idle ▾

Guide & updates

Button	What it does
-10s -5s +5s +10s	Jump back or forward in the current song.
Pause / Resume	One button; it changes label.
Skip	Next song. If the next one is still loading it starts as soon as it's ready.
Stop	Clears the music. The bot stays in the channel.
Leave	Dismisses the bot from the voice channel.
Prev / Next	Page through the queue, 5 songs per page.
Gaming mode	Turns voice commands on or off. More below.
Radio	When the queue runs out, keep playing similar songs.
Shuffle	Shuffles the songs waiting in the queue.
Repeat	Cycles off, this song, the whole queue.
Save	Saves the song to your Jellyfin favorites (and library), if this server has Jellyfin set up.
Leave after idle	Dropdown: how long the bot waits in the channel with nothing playing before it leaves (5 min to 2 hours, or never). Set it long while gaming so it's there when you say "Spotibot, ...".

The footer shows who did what ("Paused (Chris)"). Buttons for features a server hasn't set up are simply not shown.

Gaming mode

Control the music by voice while you play. No alt-tabbing, no typing.

Turn it on or off

Press Gaming mode on the queue message, type !gaming on / !gaming off, or use /gaming. The setting is remembered per server. The bot must be in your voice channel (/join or any /play).

How to talk to it

Start with "Spotibot", then the command: "Spotibot, play Africa by Toto". Saying "by <artist>" helps it pick the right song. You can also say "Spotibot", pause, then the command within 8 seconds. What it heard shows up on the queue message.

Privacy

While Gaming mode is on, what people say in that voice channel is turned into text by a speech server run by whoever hosts this bot (it never goes to an outside company). Audio is processed in memory and not saved, and only lines that start with "Spotibot" are acted on or logged. Let people in the channel know, and turn it off any time.

Voice commands

Say "Spotibot, ..."	Does
play song [by artist]	Add a song. Add "next" at the end to play it next.
play my name playlist	Play one of the server's Jellyfin playlists (if set up).
play something like this	Queue songs similar to the current one, right after it.
skip / next	Next song.
pause / resume	Pause or continue.
stop	Clear the music (the bot stays).
shuffle	Shuffle the queue.
repeat / repeat all / stop repeating	Repeat this song, the queue, or turn repeat off.
louder / quieter	Volume up or down.
what's playing	Shows the song and time on the queue message.
save this	Save the song to Jellyfin favorites (if set up).
radio on / radio off	Turn radio autoplay on or off.
gaming mode off / stop listening	Turn voice commands off.
leave / go away / bye	Dismiss the bot.

Not hearing you? Check that the bot isn't server-muted for you, that Gaming mode shows "on", and that you start with "Spotibot". Background music picked up by your mic can make it harder to hear you; push-to-talk helps.

Radio, playlists and staying in the channel

Radio

With Radio on, when the last song ends the bot keeps going with similar songs (marked "(radio)" in the queue). !radio now or "Spotibot, play something like this" queues songs like the current one straight away. !radio off to stop.

Playlists

Paste a Spotify or YouTube playlist link into /play. If the server has Jellyfin set up, !playlists lists its playlists and /playlist plays one (with autocomplete).

Staying in the channel

The bot stays after the queue ends, so you can keep asking for songs. It leaves when someone presses Leave (or !leave, "Spotibot, leave"), after the idle timer runs out (30 minutes with nothing playing unless you change it with the Leave after idle dropdown; "never" is an option), or after 5 minutes alone. Paused counts as nothing playing.

All commands

Slash commands reply only to you. ! commands work too; control commands report on the queue message and the command itself is tidied away (if the bot has Manage Messages).

Command	Does
`/play` `!play`	Song, YouTube or Spotify link, or playlist link. `!playnext` plays it next.
`/join` `!join`	Join your voice channel and wait (handy for Gaming mode).
`/leave` `!leave`	Dismiss the bot.
`/skip /pause /resume /stop`	Same as the buttons. `!skip !pause !resume !stop` too.
`/queue` `!queue`	Move the queue message to the bottom of the chat.
`/np` `!np`	What's playing and how far in.
`/shuffle` `/repeat`	Shuffle; repeat off, song or queue (`!repeat song`).
`/volume` `!volume 50`	Volume 0-100.
`/radio` `!radio on\|off\|now`	Radio autoplay.
`/gaming` `!gaming on\|off`	Gaming mode (voice commands).
`/playlist` `!playlists`	Jellyfin playlists.
`/save` `!save`	Save the song to Jellyfin.
`/settings` `!settings`	Server settings. Managers can change the idle timeout, tidy commands, Gaming mode and Radio defaults: `!settings idle 45`, `!settings tidy off`.
`!blackjack`	Yes, there is blackjack. `!blackjack help`.

Running your own Spotibot

The bot works on its own. The extras are optional services you can add later. Code and setup: github.com/Toe-Fur/Spotibot.

Mode	You run	You get
Classic (default)	Just the bot (`docker-compose.example.yml`)	Everything except Radio, Gaming mode and Jellyfin. Each song is downloaded with yt-dlp before it plays.
Streaming	+ ytmusic-stream-server and bgutil-pot	Songs start in about 5 s (instantly when cached), the next songs pre-load, Radio, suggestions in `/play`.
Gaming mode	+ spotibot-stt	Voice commands, speech-to-text on your own machine.
Jellyfin	Your Jellyfin server + API key	Playlists and the Save button.

All of it in one file: docker-compose.streaming.example.yml. See companion/README.md for details. YouTube needs a signed-in session from most servers: put an exported cookies.txt (youtube.com and google.com cookies) in config/.

Updates

What changed in each version. Loaded from CHANGELOG.md, so this is always current.