How to use CatchTunes

A short guide to adding CatchTunes, playing music in voice with Tunes, and using the dashboard.

1. Add CatchTunes to your server

You need Manage Server or Administrator in the server, or to own it.

Open the invite link.
Pick your server and keep every permission ticked.
Press Authorize. CatchTunes joins and its slash commands show up when you type /.

You can also sign in to the dashboard. Servers you manage that don't have CatchTunes yet show under "Add CatchTunes" with an "Add to server" button.

The permissions it asks for

View Channels, Send Messages: To post the Tunes player card and answer commands.
Embed Links: For the cards it posts (the player, the queue, history and lyrics).
Attach Files: Part of the invite link. Nothing in CatchTunes posts files now.
Read Message History: To see when chat has buried the player card, so it can post it again at the bottom.
Connect, Speak: To join a voice channel and play music with Tunes.

Added CatchTunes before Tunes existed? It won't have Connect and Speak. Add it again with the invite link, or give its role Connect and Speak in your voice channel.

2. Set up Tunes

Tunes works without any setup. These settings are optional. Only people with Administrator or Manage Server, or the server owner, can change them.

In Discord, use /setup tunes. Options you leave out stay as they are. It replies with the current Tunes settings.

voice_channel: The voice channel the bot plays in. Not set: the voice channel of whoever uses /play.
text_channel: Where the player card goes. Not set: the channel where /play is first used.
playlist: The server playlist shown in the player card's menu.
dj_only: DJ-only mode. Only DJs and server managers can control playback. Anyone in the voice channel can still add songs.
dj_role: The role that counts as DJ.
max_minutes: The longest song that can be queued, 1 to 60 minutes (default 15).
person_limit: How many songs one person can have queued, 1 to 200 (default 25). Server managers have no limit.
autoplay: Keep playing related songs when the queue runs out.
volume: The starting volume, 0 to 150% (default 100).

On the website, open the dashboard, press Settings next to your server and scroll to "Tunes (voice playback)". It has the same settings: Voice channel, Player message channel, Server playlist, DJ-only mode, DJ role, Longest song, Songs one person can have queued, Autoplay and Starting volume. Press Save settings when you're done.

3. Playing music in Discord

Join a voice channel (the Tunes voice channel, if your server set one).
Type /play and a song name, or paste a YouTube or YouTube Music link. Pick a suggestion from the list, or just press Enter.
CatchTunes joins your voice channel and starts playing. A player card appears in the chat.

/play takes a song name, a YouTube or YouTube Music video link, or a YouTube playlist or album link (up to 200 songs at once). /playnext works the same way but puts the songs at the front of the queue.

Spotify links: Spotify playlist links can't be played. Import the playlist on the dashboard instead (see Importing). Spotify song and album links can't be played either. You'll see "Spotify links can't be played. Search by the song name instead." Type the song name instead.

To add or control music you must be in the bot's voice channel (admins and DJs can still stop it from anywhere). Until the bot joins one, that's the Tunes voice channel if one is set, or any voice channel if not.

How the queue order works

Songs people ask for play first, in the order they were asked.
Songs from a playlist, an album, autoplay or repeat wait behind them. On the dashboard these show a small "playlist", "autoplay" or "repeat" tag.
Play next (/playnext or the dashboard button) puts songs at the very front.
Shuffle mixes each group on its own, so requests stay ahead of playlist songs.
Songs longer than the server's limit (15 minutes unless changed) are left out, and so are songs past your per-person limit (25 unless changed). One add takes up to 200 songs.

The player card

The card shows the cover, the song, who queued it, when it ends, the volume and the repeat mode, and what's up next. Anyone in the voice channel can press its buttons. In DJ-only mode only DJs and server managers can. Volume and Disconnect have their own rules, below. With nothing playing, Skip and Wrong song? are hidden.

⏮ Previous: Go back a song. More than 5 seconds into a song, it starts that song again.
⏸ Pause / ▶ Resume: Pause or carry on. It says Play when nothing is loaded.
⏭ Skip: Skip the song the card shows. Two people pressing at once skip just one song.
🔁 Repeat: Switches between Off, One song and Whole queue.
🔀 Shuffle: Shuffle the queue.
📜 Queue: Opens this server's Tunes page on the dashboard. If the website is off, it shows the queue just to you.
🔄 Wrong song?: Wrong video found? This swaps in the next YouTube match and remembers it for your server.
🔉 −10% · 🔊 +10%: Change the volume for everyone. Server admins only (Administrator, Manage Server or the owner), not DJs. Tip: to make CatchTunes quieter just for you, right-click it in the voice channel and use User Volume (on mobile, tap it).
⏏️ Disconnect: Stops the music, clears the queue and leaves. Admins and DJs can use it from anywhere, even outside the voice channel. Anyone else can only when they're alone with the bot in its voice channel.
Queue from the playlist menu: Shows when the server playlist has songs. Pick one of its first 25 songs to queue it. Use /serverplaylist pick for the rest.

The card only exists while the bot is in voice. If 10 messages bury it, it's posted again at the bottom.

Tunes commands

/play · /playnext: Add a song, album or playlist (query). Play next puts it at the front.
/pause · /resume: Pause or resume the music.
/skip · /previous: Skip this song, or go back one.
/seek: Jump to a point in the song, like 1:30 or 95 (seconds).
/repeat: Off, One song or Whole queue.
/shuffle: Shuffle the queue.
/volume: Set the volume, 0 to 150%. Admins only.
/queue: See the queue, 10 songs a page.
/skipto: Play a song from the queue now, by its number in /queue. The songs before it stay queued.
/remove · /move: Remove or move a song by its number in /queue. You can change songs you queued. DJs and managers can change any song.
/clear: Empty the queue. DJs and managers only.
/stop: Stop, clear the queue and leave voice. Same rules as Disconnect.
/lyrics: Lyrics for the song playing now, from LRCLIB.
/history: The last 50 songs played, with a menu to queue one of the latest 25 again.
/savequeue: Save the song playing now and the queue to a server playlist (made if it doesn't exist). DJs and managers only.

When CatchTunes leaves

After 30 seconds with nobody else in its voice channel (bots don't count).
After 5 minutes with nothing playing and nothing queued.
When someone uses /stop or Disconnect.

When it leaves for any reason, the queue is cleared and the player card is deleted. The history stays.

4. The dashboard

Signing in

Press Sign in at the top of this site.
Approve CatchTunes on Discord. It sees your name, your avatar and your server list, including which servers you manage.
You land on Your servers.

The server list has three parts. "Manage" lists servers you manage that have CatchTunes, with Settings and Tunes. "Member of" lists other servers with CatchTunes, with Tunes. "Add CatchTunes" lists servers you manage that don't have it yet. Sign out and back in to refresh the list.

The Tunes page

Anyone in the server can open it. To control or add music from it, you still have to be in the bot's voice channel in Discord. The page tells you when you aren't.

Player: the song playing now, a position slider to jump around, Previous, Play/Pause, Skip, Repeat, Shuffle and a volume slider (admins only). It also shows the voice channel and how many people are listening.
Add a song: search YouTube Music. Each result has + Queue, Play next, and + Playlist (DJs and managers, for the playlist picked below).
Up next: the queue. ↑ and ↓ move a song and ✕ removes it. You get these on songs you queued, and DJs and managers get them on every song. DJs and managers also have Save queue as playlist and Clear.
History: songs played here, each with Queue again.
Activity: who did what, like who skipped or queued a song.

Playlists

Pick a playlist from the menu to see its songs. Press ▶ Play all to queue the whole playlist, or + Queue next to one song. DJs and managers can edit:

Open "Edit playlists" to make a New playlist (1 to 50 characters), or Rename or Delete the one picked.
Add songs with + Playlist on a search result, or the + Playlist button next to the song playing now.
Use ↑, ↓ and ✕ to reorder or remove songs. A playlist holds up to 500 songs.

Importing a playlist

DJs and managers can make a server playlist from somewhere else. Open "Import playlist" on the Tunes page and pick a tab:

From Spotify: Open Exportify and sign in with Spotify. Press Export next to the playlist to download a .csv file. Drop the file on the page, or press Choose file. CatchTunes never sees your Spotify login.
YouTube link: Paste a YouTube or YouTube Music playlist or album link. Its videos are copied as they are. Lists tied to an account (Liked videos, Watch later, Liked music, My Mix) are refused.
CSV file: A .csv with title and artist columns (an Exportify file works as it is), or a .txt with one "Artist - Title" per line.
Paste list: Type or paste one "Artist - Title" per line.

Give the new playlist a name if you like, then press Import. Files can be up to 1 MB. A playlist takes up to 500 songs, and the rest are left out. Each row is looked up on YouTube, and rows with no match are listed under "Not found". One import runs per server at a time.

Server settings

Managers press Settings next to a server. It has the same Tunes settings as /setup tunes.

5. Server playlists from Discord

Server playlists live inside CatchTunes, not on Spotify. Everyone can list, show, play and pick from them. Only DJs and managers can change them.

/serverplaylist create: Make a new playlist (1 to 50 characters).
/serverplaylist rename: Give a playlist a new name.
/serverplaylist delete: Delete a playlist.
/serverplaylist list: This server's playlists and how many songs each has.
/serverplaylist show: The songs in a playlist, with their numbers.
/serverplaylist add: Add a song name or link, or type now for the song playing now.
/serverplaylist remove: Remove a song by its number in show.
/serverplaylist move: Move a song to a new number.
/serverplaylist play: Queue the whole playlist. Set shuffle to mix it first.
/serverplaylist pick: Choose songs from a menu to queue, 25 a page.
/serverplaylist import: Make a playlist from a YouTube or YouTube Music playlist or album link, or an attached file (.csv or .txt, up to 1 MB). Give one, not both.

6. Other features

/help: Every command in Discord. The full list is also on the Commands page.

7. Getting help

Open the Contact page and sign in.
Pick a topic, write your message (10 to 2000 characters) and press Send message. This opens a ticket.
Replies come by Discord DM from CatchTunes. To get them, share a server with CatchTunes and allow DMs from server members.
Answer with the Respond button on the reply. Press Close ticket when you're done.

You can have up to 3 open tickets, and you can send a new one every 10 minutes.

8. Your data

CatchTunes doesn't connect to Spotify and doesn't read your messages or your Discord status. The My data page says what it keeps.

Delete my data on that page, or /deletemydata in Discord, removes:

songs you queued in Tunes,
your support tickets,
your dashboard sign-ins.

What stays: Tunes history and activity (kept up to 30 days) stay without your name. Songs you added to server playlists stay, with your name removed. Deleting can't be undone.

Read the Privacy Policy and the Terms of Service for the details.