SponsorBlock Integration

Remove or mark sponsor segments in YouTube videos using SponsorBlock

Overview

yt-dlp integrates with the SponsorBlock API to automatically skip or mark various segments in YouTube videos, including sponsors, intros, outros, self-promotion, and more.

SponsorBlock is a crowdsourced database of sponsor segments. The community submits timestamps, which are then used to skip these segments.

Segment Categories

SponsorBlock recognizes these segment types:

Category	Description
sponsor	Paid promotion, paid referrals, and direct advertisements
intro	Intermission/intro animation, typically at the start
outro	Endcards/credits at the end of the video
selfpromo	Unpaid/self-promotion (e.g., merch, donations, social media)
preview	Quick recap of previous episodes, or preview of what’s coming
filler	Tangential scenes added only for filler or humor
interaction	Reminder to like, subscribe, or follow on social media
music_offtopic	Non-music section in a music video
poi_highlight	Point of interest highlight (not available for removal)
chapter	Video chapters (not available for removal)
all	All categories
default	For marking: all categories; for removing: all except filler

Marking Segments

Create chapter markers for sponsor segments without removing them:

Mark All Segments

# Create chapters for all segment types
yt-dlp --sponsorblock-mark all URL

Custom Chapter Titles

Customize how SponsorBlock chapters appear:

# Default format
yt-dlp --sponsorblock-mark all \
  --sponsorblock-chapter-title "[SponsorBlock]: %(category_names)l" \
  URL

# Simple format
yt-dlp --sponsorblock-mark all \
  --sponsorblock-chapter-title "[%(category)s]" \
  URL

# With timestamps
yt-dlp --sponsorblock-mark all \
  --sponsorblock-chapter-title "%(start_time)s - %(category_names)l" \
  URL

Available template fields:

• start_time: Segment start time
• end_time: Segment end time
• category: Category ID (e.g., “sponsor”)
• categories: List of category IDs
• name: Category name
• category_names: List of category names

Removing Segments

Removing segments requires re-encoding the video with ffmpeg, which takes time and may reduce quality slightly.

Permanently remove segments from the downloaded video:

1. Remove sponsors only

   yt-dlp --sponsorblock-remove sponsor URL
   
2. Remove multiple categories

   # Remove sponsors, self-promotion, and intros
   yt-dlp --sponsorblock-remove sponsor,selfpromo,intro URL
   
3. Use default removal

   # Remove all segments except filler
   yt-dlp --sponsorblock-remove default URL
   

Exclude categories

# Remove all except filler and interaction
yt-dlp --sponsorblock-remove all,-filler,-interaction URL

Combining Mark and Remove

You can both mark and remove different categories:

# Remove sponsors, mark outros
yt-dlp --sponsorblock-remove sponsor \
  --sponsorblock-mark outro \
  URL

# Remove ads and promos, mark all others
yt-dlp --sponsorblock-remove sponsor,selfpromo \
  --sponsorblock-mark intro,outro,interaction \
  URL

If a category appears in both --sponsorblock-mark and --sponsorblock-remove, removal takes precedence.

Common Use Cases

Clean viewing experience

# Remove all distractions
yt-dlp --sponsorblock-remove sponsor,selfpromo,interaction \
  --sponsorblock-mark intro,outro \
  URL

Music videos

# Skip non-music sections
yt-dlp --sponsorblock-remove music_offtopic,sponsor URL

Podcast/long-form content

# Keep chapter structure, remove sponsors
yt-dlp --sponsorblock-remove sponsor,selfpromo \
  --sponsorblock-mark intro,outro \
  --embed-chapters \
  URL

Educational content

# Remove sponsor but keep other content
yt-dlp --sponsorblock-remove sponsor \
  --sponsorblock-mark selfpromo,interaction \
  URL

Audio Extraction with SponsorBlock

Remove segments when extracting audio:

# Extract audio without sponsors
yt-dlp -x --audio-format mp3 \
  --sponsorblock-remove sponsor,selfpromo \
  URL

# Music downloads without non-music sections
yt-dlp -x --audio-format mp3 \
  --sponsorblock-remove music_offtopic,sponsor,intro,outro \
  --embed-metadata \
  URL

SponsorBlock API Configuration

Custom API server

# Use different SponsorBlock instance
yt-dlp --sponsorblock-api "https://sponsor.example.com" \
  --sponsorblock-remove sponsor \
  URL

Default API: https://sponsor.ajay.app

Disable SponsorBlock

# Disable all SponsorBlock features
yt-dlp --no-sponsorblock URL

Working with Chapters

Split by chapters after removing sponsors

# Remove sponsors, then split into chapters
yt-dlp --sponsorblock-remove sponsor \
  --split-chapters \
  -o "chapter:%(title)s - %(section_number)s %(section_title)s.%(ext)s" \
  URL

Force keyframes for clean cuts

# Better quality cuts (slower processing)
yt-dlp --sponsorblock-remove sponsor \
  --force-keyframes-at-cuts \
  URL

Using --force-keyframes-at-cuts requires re-encoding and significantly increases processing time.

Playlist Processing

Apply SponsorBlock to entire playlists:

# Remove sponsors from all videos in playlist
yt-dlp --sponsorblock-remove sponsor,selfpromo \
  -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" \
  PLAYLIST_URL

# With download archive to skip processed videos
yt-dlp --sponsorblock-remove sponsor \
  --download-archive archive.txt \
  PLAYLIST_URL

Performance Considerations

Marking (Fast)

# Just adds chapter markers, no re-encoding needed
yt-dlp --sponsorblock-mark all URL

This is fast because it only modifies metadata.

Removing (Slow)

# Requires re-encoding with ffmpeg
yt-dlp --sponsorblock-remove sponsor URL

This takes time proportional to video length and requires ffmpeg.

If you want to preview segments before removal, use --sponsorblock-mark first, then manually check the chapters.

Advanced Examples

Complete automated workflow

yt-dlp \
  --sponsorblock-remove sponsor,selfpromo,interaction \
  --sponsorblock-mark intro,outro \
  --embed-chapters \
  --embed-metadata \
  --embed-thumbnail \
  --merge-output-format mp4 \
  -o "~/Videos/%(uploader)s/%(title)s.%(ext)s" \
  URL

Audio podcast with clean chapters

yt-dlp -x --audio-format mp3 \
  --sponsorblock-remove sponsor,selfpromo \
  --sponsorblock-mark intro,outro \
  --embed-metadata \
  --embed-thumbnail \
  --parse-metadata "%(uploader|)s:%(meta_artist)s" \
  -o "Podcasts/%(uploader)s/%(upload_date)s - %(title)s.%(ext)s" \
  URL

Minimal file size

# Remove all removable segments
yt-dlp --sponsorblock-remove sponsor,intro,outro,selfpromo,preview,interaction,music_offtopic \
  -S "+size" \
  URL

Verify Segments

Check what segments are available before downloading:

# Print information about SponsorBlock segments
yt-dlp --print "%(sponsorblock_chapters)s" URL

# Simulate to see what would be done
yt-dlp --simulate \
  --sponsorblock-remove sponsor \
  --verbose \
  URL

Troubleshooting

No segments found

Not all videos have SponsorBlock data. The database is crowdsourced and may not cover every video.

# Check if video has SponsorBlock data
yt-dlp --print "%(sponsorblock_chapters)s" URL

# Use verbose to see API responses
yt-dlp --sponsorblock-mark all --verbose URL

Segments not removed correctly

# Ensure ffmpeg is working
ffmpeg -version

# Use force keyframes for precise cuts
yt-dlp --sponsorblock-remove sponsor \
  --force-keyframes-at-cuts \
  URL

API connection issues

# Test with verbose output
yt-dlp --sponsorblock-mark sponsor --verbose URL

# Use alternative API server
yt-dlp --sponsorblock-api "https://sponsor.ajay.app" \
  --sponsorblock-remove sponsor \
  URL

SponsorBlock on Other Platforms

SponsorBlock integration currently only works for YouTube videos. Other platforms are not supported.

Contributing to SponsorBlock

Help improve the SponsorBlock database:

• Install the browser extension
• Submit segments while watching videos
• Vote on existing segments

Your contributions help the entire community!

Next Steps

Post-Processing

Other post-processing options

Format Conversion

Converting video formats

Playlists

Process entire playlists

Options Reference

SponsorBlock options reference