PeerTube SponsorBlock Plugin

Automatically skip or permanently remove sponsored segments from YouTube videos imported into your PeerTube instance.

What it does: When you import a video from YouTube, this plugin checks the SponsorBlock database and automatically skips (or removes) sponsored segments, intros, outros, and more.

---

Quick Start

Installation

1. Go to Administration > Plugins/Themes in your PeerTube instance
2. Search for SponsorBlock in the plugins list
3. Click Install and then Enable

Or install via CLI:

cd /var/www/peertube
sudo -u peertube NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production \
  npm run plugin:install -- --npm-name peertube-plugin-sponsorblock

Basic Usage

1. Enable the plugin in Plugins/Themes
2. Configure your preferred settings (see below)
3. Import videos from YouTube as usual — SponsorBlock segments will be handled automatically!

---

Features

What works right now

Feature	Description
Auto-skip	Segments are automatically skipped during playback
Visual markers	See sponsor segments on the video progress bar
Multiple categories	Skip sponsors, intros, outros, self-promo, and more
Admin dashboard	View stats, manage mappings, and sync segments
Permanent removal	Optionally cut segments from video files permanently
Automatic detection	Works automatically when importing YouTube videos

Two modes of operation

Skip mode (default)

• Segments are skipped automatically during playback
• No files are modified
• Works for any video imported from YouTube
• Can be configured per category (sponsor, intro, interaction, etc.)

Remove mode

• Segments are permanently cut from the video file
• Saves bandwidth and storage
• Irreversible — use with backups
• Requires FFmpeg installed on your server

---

Configuration

Settings

Setting	Description
Mode	Choose skip (client-side) or remove (permanent)
Categories to skip	Select which segment types to skip (sponsor, intro, outro, self-promo, interaction, music_offtopic)
Storage path	Where to store processed videos (remove mode only)
Sync interval	How often to refresh segment data from SponsorBlock

Admin Dashboard

Access the dashboard at Administration > Plugins > SponsorBlock > Go to plugin settings:

• Stats cards: See mapped videos, total segments, time saved, and pending jobs
• Mappings table: View all YouTube-to-PeerTube mappings with actions
• Bulk actions: Scan imports, sync all, or process all videos at once

---

How it works

1. When you import a video from YouTube, the plugin detects the YouTube video ID
2. It queries the SponsorBlock API for sponsor segments
3. Segments are cached locally in your database
4. During playback, segments are automatically skipped (or removed from the file)

What is SponsorBlock?

SponsorBlock is a crowdsourced database of video segments. Users submit timestamps for:

• Sponsors - Paid promotions and sponsorships
• Intro - Animated introductions
• Outro - Credits and end screens
• Self-promo - Unpaid promotion of creator's content
• Interaction - Reminders to like, subscribe, follow
• Music off-topic - Non-music sections in music videos

Learn more at sponsor.ajay.app

---

Important Notes

Skip mode (recommended for most users)

• Segments are still downloaded (no bandwidth savings)
• Only works in the PeerTube web player
• Reversible — you can disable it anytime

Remove mode (advanced users)

• Irreversible — video files are permanently modified
• Saves bandwidth and storage space
• Removes all segment types (category settings don't apply)
• Comment timestamps may shift after removal
• Requires automatic backups — use at your own risk
• Requires ffmpeg and ffprobe installed on your server

---

Documentation

• User Guide - Detailed installation and configuration
• Development Guide - For contributors and developers
• Changelog - Version history and updates

---

Requirements

• PeerTube >= 6.0.0
• For remove mode: ffmpeg and ffprobe in system PATH

---

License

AGPL-3.0 (compatible with PeerTube)

---

Support & Contributing

• Issues: GitHub Issues
• Source Code: GitHub Repository

Contributions welcome! Testing on development instances is especially appreciated.

---

Author: Jean-Baptiste L.