SponsorBlock for Lavalink: Skip Sponsors Automatically

Music on YouTube often comes with extras nobody asked for: sponsor reads, “like and subscribe” reminders, long intros and non-music sections in music videos. The SponsorBlock plugin for Lavalink skips them automatically using community-submitted data, which makes a music bot noticeably more pleasant to listen to.

What SponsorBlock is

SponsorBlock is a crowd-sourced database where viewers mark segments of YouTube videos by type — sponsor, self-promotion, intro, outro and so on. The Lavalink plugin looks up each YouTube track’s segments when it starts playing and seeks past the categories you’ve chosen.

It only applies to YouTube tracks (including Spotify tracks mirrored to YouTube by LavaSrc). Segments exist only where the community has submitted them, which is most popular videos but not all.

Categories

For a music bot, sponsor, selfpromo, interaction and music_offtopic are the most useful. Skipping intro and outro can occasionally cut part of a song, so offer those as options rather than defaults.

Installing the plugin

Add it to application.yml:

lavalink:
  plugins:
    - dependency: "com.github.topi314.sponsorblock:sponsorblock-plugin:VERSION"
      repository: "https://maven.lavalink.dev/releases"

Use the latest release from the plugin’s GitHub repository (topi314/Sponsorblock-Plugin) that supports your Lavalink version, and restart the node.

On Kerit Cloud’s managed Lavalink plans, SponsorBlock is pre-installed on every tier.

Choosing categories per player

The plugin doesn’t skip anything until your bot tells it which categories to skip for a given player. It adds REST endpoints under the player:

GET    /v4/sessions/{sessionId}/players/{guildId}/sponsorblock/categories
PUT    /v4/sessions/{sessionId}/players/{guildId}/sponsorblock/categories
DELETE /v4/sessions/{sessionId}/players/{guildId}/sponsorblock/categories

PUT takes a JSON array of category names. Because it’s per player, each server can have its own preference.

From Node.js

Most client libraries don’t wrap plugin endpoints, but a direct call is simple. With Shoukaku, the node’s session ID and REST details are available on the node object:

async function setSponsorBlock(node, guildId, categories) {
  const url = `http://${process.env.LAVALINK_HOST}:${process.env.LAVALINK_PORT}` +
    `/v4/sessions/${node.sessionId}/players/${guildId}/sponsorblock/categories`;
  const res = await fetch(url, {
    method: 'PUT',
    headers: {
      Authorization: process.env.LAVALINK_PASSWORD,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(categories),
  });
  if (!res.ok) throw new Error(`SponsorBlock update failed: ${res.status}`);
}

// after the player is created:
await setSponsorBlock(node, guildId, ['sponsor', 'selfpromo', 'interaction', 'music_offtopic']);

From Python

With Wavelink, the node exposes a send() helper for raw requests:

await player.node.send(
    "PUT",
    path=f"v4/sessions/{player.node.session_id}/players/{player.guild.id}/sponsorblock/categories",
    data=["sponsor", "selfpromo", "interaction", "music_offtopic"],
)

Exact attribute names vary between client versions; the pattern — a PUT to the player’s SponsorBlock endpoint with the session ID and guild ID — stays the same. The player must exist on the node before you set categories.

Events

The plugin sends extra events over the WebSocket, which your client passes through as raw or unknown events:

• SegmentsLoaded — segments were found for the current track.
• SegmentSkipped — a segment was skipped, including its category and time range.
• ChaptersLoaded and ChapterStarted — chapter information for videos that have it.

You can use SegmentSkipped to show a subtle “Skipped sponsor segment” note, or log it to understand how often skipping happens. Keep chat messages optional — some users find them noisy.

Let servers choose

A nice pattern is a /sponsorblock command that lets server admins pick categories, stored per guild in your database and applied whenever a player is created:

1. Admin runs /sponsorblock set with a multi-select menu of categories.
2. The bot saves the list for that guild.
3. Whenever the bot creates a player for the guild, it PUTs the saved categories.

Default to a conservative set (sponsor, selfpromo, interaction) and let communities opt into more.

Troubleshooting

Nothing is being skipped — categories haven’t been set for that player, the track isn’t from YouTube, or nobody has submitted segments for that video.

404 on the SponsorBlock endpoint — the plugin isn’t loaded (check the Lavalink startup log), or the player doesn’t exist yet on the node.

The start of a song is cut off — you’re skipping intro or music_offtopic on a video where the segment boundaries are imperfect. Remove those categories for music.

Skips happen late — segments are fetched when the track starts; a slow response from the SponsorBlock API can delay the first skip slightly.

How reliable is the data?

SponsorBlock’s data comes from viewers who mark segments while watching, and other users vote on submissions. For popular videos, segments are usually accurate to within a second or two. For less-watched videos, there may be no segments at all, or boundaries that start slightly early or late.

That’s why conservative defaults matter. Sponsor reads and subscription reminders are rarely part of the music, so skipping them is low-risk. Intros, outros and “non-music” sections are fuzzier — a music video’s intro might be a spoken skit, or it might be the first bars of the song.

It also helps to think about what your users expect:

• Playlists of official music videos benefit most from music_offtopic, which removes skits and talking sections.
• Podcasts and talk content benefit from sponsor, selfpromo and interaction.
• Live performances and mixes often have imperfect segment data; consider leaving SponsorBlock off for these, or letting users disable it per command.

Performance impact

The plugin makes one lookup per YouTube track when it starts, and then simply seeks at the right moments. It adds negligible CPU and memory to a node — seeking is far cheaper than decoding the skipped audio would be. The only noticeable effect is a small delay before the first skip on tracks where the lookup is slow.

Summary

The SponsorBlock plugin uses community data to skip sponsor reads, self-promotion, reminders and non-music sections in YouTube tracks. Install it on your node (it’s pre-installed on Kerit Cloud’s managed plans), then set categories per player with a PUT to the player’s SponsorBlock endpoint. Default to sponsor, selfpromo and interaction, let server admins opt into more, and use the skip events for optional feedback.