StayTube

A modern music library for Discord bots built on discord.js v14. StayTube plays audio from YouTube and over a thousand other sites, keeps a per-server queue, and gives you filters, autoplay, and 24/7 voice support out of the box.

It leans on yt-dlp for extraction, which is the main reason it keeps playing when other libraries stop. yt-dlp is updated almost daily to keep up with YouTube, and StayTube talks to it directly, so you get those fixes without changing your code.

Why StayTube

• Plays YouTube, SoundCloud, Bandcamp, Vimeo, Twitter/X and 1000+ more sites through a single plugin.
• Survives YouTube's bot checks. Point it at a cookies file and it plays like a signed-in user.
• Smart queue: skip, back, jump, shuffle, remove, move, swap, seek.
• Audio filters: bassboost, nightcore, 8D, vaporwave, karaoke and many more, stackable live.
• Auto-leave when the channel empties or the queue ends, with cooldowns you control.
• Autoplay keeps the music going when the queue runs dry.
• Written in TypeScript. Full type definitions ship with the package.

Requirements

StayTube needs three things on the machine that runs your bot:

1. Node.js 18 or newer.
2. FFmpeg — for decoding and the audio filters.
3. yt-dlp — the extractor. It needs Python 3.9+ installed.

Install FFmpeg and yt-dlp:

# Windows (with winget)
winget install ffmpeg
winget install yt-dlp

# macOS (with Homebrew)
brew install ffmpeg yt-dlp

# Debian / Ubuntu
sudo apt install ffmpeg python3-pip
pip3 install -U yt-dlp

Check they're reachable:

ffmpeg -version
yt-dlp --version

If both print a version, you're good.

Install

npm install @staytube/staytube discord.js @discordjs/voice @discordjs/opus sodium-native

discord.js and @discordjs/voice are peer dependencies — you install them yourself so there's never a version clash. @discordjs/opus and sodium-native handle audio encoding and encryption.

Quick start

const { Client, GatewayIntentBits } = require("discord.js");
const { StayTube, YtDlpPlugin } = require("@staytube/staytube");

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.GuildVoiceStates,
    GatewayIntentBits.MessageContent,
  ],
});

const player = new StayTube(client, {
  plugins: [new YtDlpPlugin()],
  leaveOnEmpty: true,
  emptyCooldown: 60,
  defaultVolume: 50,
  maxVolume: 150,
});

client.on("messageCreate", async (message) => {
  if (message.author.bot || !message.inGuild()) return;

  if (message.content.startsWith("!play ")) {
    const query = message.content.slice(6);
    const channel = message.member.voice.channel;
    if (!channel) return message.reply("Join a voice channel first.");

    await player.play(channel, query, {
      member: message.member,
      textChannel: message.channel,
    });
  }

  if (message.content === "!skip") await player.skip(message.guildId);
  if (message.content === "!stop") await player.stop(message.guildId);
});

player.on("playSong", (queue, song) => {
  queue.textChannel?.send(`Now playing: **${song.name}** — \`${song.formattedDuration}\``);
});

client.login("YOUR_BOT_TOKEN");

That's a working music bot. !play <song or url> starts it, !skip and !stop do what they say.

Fixing YouTube with cookies

YouTube sometimes blocks servers with a "Sign in to confirm you're not a bot" message. The fix is to hand StayTube a cookies file from a logged-in account — use a throwaway account, not your main one.

1. Install the EditThisCookie or Get cookies.txt extension in your browser.
2. Log into YouTube with a spare account.
3. Export the cookies as a cookies.txt file (Netscape format).
4. Put the file next to your bot and pass its path:

new YtDlpPlugin({ cookies: "./cookies.txt" })

That single line clears up almost every YouTube playback problem on a server.

Playing Spotify and SoundCloud links

The YtDlpPlugin already understands SoundCloud URLs directly. Spotify links point to tracks that YouTube actually hosts the audio for, so the common approach is to read the track name from the Spotify link and let StayTube search for it. Drop a URL of any supported site into play() and it just works.

Options

Everything is optional and has a sensible default.

| Option | Default | What it does | | --- | --- | --- | | plugins | [] | Your extractors. Add new YtDlpPlugin() here. | | defaultVolume | 50 | Starting volume for new queues (percent). | | maxVolume | 100 | Ceiling users can raise the volume to. | | maxQueueSize | Infinity | Cap on songs per server queue. | | leaveOnEmpty | true | Leave when everyone else leaves the channel. | | emptyCooldown | 60 | Seconds to wait before leaving an empty channel. | | leaveOnFinish | false | Leave when the queue finishes. | | leaveOnStop | true | Leave when stop() is called. | | savePreviousSongs | true | Keep history so previous() works. | | nsfw | false | Allow age-restricted content (NSFW channels only). |

Pass yt-dlp its own options when you create the plugin:

| Plugin option | Default | What it does | | --- | --- | --- | | cookies | — | Path to a cookies.txt file (see above). | | path | "yt-dlp" | Path to the yt-dlp binary if it's not on PATH. | | searchLimit | 1 | How many results a text search fetches. | | requestTimeout | 60000 | Milliseconds before a stuck yt-dlp call is killed. | | noCheckCertificate | false | Skip TLS checks (only for broken proxies). |

Controlling the queue

Grab the queue for a server with player.getQueue(guildId), then:

const queue = player.getQueue(message.guildId);

queue.pause();
queue.resume();
queue.setVolume(80);
queue.seek(60);            // jump to 1:00
queue.shuffle();
queue.remove(2);           // drop the 3rd song
queue.move(4, 1);          // move a song up the list
queue.setRepeatMode(1);    // 0 off, 1 song, 2 queue
queue.toggleAutoplay();

for (const song of queue.songs) {
  console.log(song.name, song.formattedDuration);
}

Events

Listen on the StayTube instance:

player
  .on("playSong",  (queue, song) => {})
  .on("addSong",   (queue, song) => {})
  .on("addList",   (queue, playlist) => {})
  .on("finish",    (queue) => {})
  .on("empty",     (queue) => {})
  .on("error",     (error, queue) => console.error(error));

Audio filters

const queue = player.getQueue(message.guildId);

queue.filters.add("bassboost");
queue.filters.add("nightcore");
queue.filters.remove("nightcore");
queue.filters.clear();

console.log(queue.filters.names); // active filters

Built-in presets include bassboost, 8d, vaporwave, nightcore, phaser, tremolo, vibrato, reverse, treble, surround, earwax, karaoke, flanger, gate, haas, mcompand, slowed, daycore, chorus and more.

Troubleshooting

yt-dlp was not found — yt-dlp isn't installed or isn't on your PATH. Run yt-dlp --version in the same terminal your bot runs in. If that fails, reinstall it, or pass the full path with new YtDlpPlugin({ path: "C:\\path\\to\\yt-dlp.exe" }).

Bot joins but there's no sound — you're missing the audio packages. Install @discordjs/opus and sodium-native, and make sure FFmpeg is installed.

"Sign in to confirm you're not a bot" — add a cookies file, as shown above.

Playback is choppy on a host — the machine is underpowered. A music bot wants at least 1 GB of RAM and a real CPU core.

License

MIT © StayTube