SponsorBlock Integration in yt-dlp

yt-dlp integrates seamlessly with SponsorBlock, a crowdsourced database that identifies and marks sponsored segments, intros, outros, and other non-content parts of YouTube videos. This powerful integration allows you to automatically skip or remove unwanted segments during download.

What is SponsorBlock?

SponsorBlock is a community-driven project that maintains a database of user-submitted timestamps for various types of segments in YouTube videos, including:

Sponsor segments - Paid promotions and sponsorships
Introductions - Intro sequences and channel introductions
Outros - End screens and outro sequences
Self-promotion - Creator promoting their own content
Interaction reminders - "Like and subscribe" reminders
Non-music sections - Talking over music in music videos
Preview segments - Recap of upcoming content
Filler content - Tangential or off-topic content
Highlight segments - Points of interest marked by users

SponsorBlock Categories

yt-dlp supports all SponsorBlock categories:

Category	Description	Common Use
`sponsor`	Paid promotions, sponsorships	Most commonly blocked
`intro`	Intro sequences, channel branding	Often skipped
`outro`	End screens, credits, outros	Often skipped
`selfpromo`	Self-promotion of creator's content	Selectively blocked
`preview`	Recap or preview of video content	Sometimes skipped
`filler`	Tangential or off-topic content	Selectively blocked
`interaction`	"Like and subscribe" reminders	Often skipped
`music_offtopic`	Non-music sections in music videos	Music-specific
`poi_highlight`	Points of interest (not blocked)	For reference only
`chapter`	Chapter markers (not blocked)	For navigation

Special Category Groups

all - All categories including poi_highlight and chapter
default - Default categories: sponsor, intro, outro, selfpromo, preview, filler, interaction, music_offtopic

Basic SponsorBlock Usage

Enable SponsorBlock Processing

SponsorBlock is disabled by default. Enable it with:

Mark all default categories as chapters

yt-dlp --sponsorblock-mark default URL

Remove all default categories from video

yt-dlp --sponsorblock-remove default URL

Mark sponsors, remove intros and outros

yt-dlp --sponsorblock-mark sponsor --sponsorblock-remove intro,outro URL

Mark vs Remove

Marking (--sponsorblock-mark):

Adds chapter markers to the video file
Segments remain in the video but are marked
Allows viewers to skip manually or with compatible players
Preserves original video length and continuity

Removing (--sponsorblock-remove):

Physically cuts out the segments from the video
Creates a shorter video without unwanted content
Cannot be undone without re-downloading
May affect video continuity

Advanced SponsorBlock Options

Category Selection

Mark specific categories

yt-dlp --sponsorblock-mark sponsor,intro,outro URL

Remove all except music_offtopic

yt-dlp --sponsorblock-remove default,-music_offtopic URL

Mark sponsors and highlights, remove intros

yt-dlp --sponsorblock-mark sponsor,poi_highlight --sponsorblock-remove intro URL

Custom Chapter Titles

Customize how SponsorBlock segments are labeled:

Default chapter title format

yt-dlp --sponsorblock-mark default --sponsorblock-chapter-title "[SponsorBlock]: %(category)s" URL

Custom format with timestamps

yt-dlp --sponsorblock-mark default --sponsorblock-chapter-title "%(category_names)s (%(start_time)s-%(end_time)s)" URL

Simple category names

yt-dlp --sponsorblock-mark default --sponsorblock-chapter-title "%(category_names)s" URL

Available Template Fields

%(category)s - Category name (e.g., "sponsor")
%(category_names)s - Human-readable category name (e.g., "Sponsor")
%(start_time)s - Segment start time (HH:MM:SS format)
%(end_time)s - Segment end time (HH:MM:SS format)
%(duration)s - Segment duration

Custom SponsorBlock API

Use alternative SponsorBlock API servers:

Use custom API endpoint

yt-dlp --sponsorblock-api "https://sponsor.ajay.app" --sponsorblock-mark default URL

Use local SponsorBlock instance

yt-dlp --sponsorblock-api "http://localhost:8080" --sponsorblock-mark default URL

Disable SponsorBlock

Explicitly disable SponsorBlock (useful in config files)

yt-dlp --no-sponsorblock URL

Practical Usage Examples

Content Creator Workflow

Download with sponsor segments marked for editing

yt-dlp --sponsorblock-mark sponsor,selfpromo --sponsorblock-chapter-title "Edit: Remove %(category_names)s" -f "bestvideo+bestaudio" URL

Clean Viewing Experience

Remove all distractions for clean viewing

yt-dlp --sponsorblock-remove sponsor,intro,outro,interaction --embed-chapters -f "best[height<=1080]" URL

Music Video Processing

Keep music, remove talking segments

yt-dlp --sponsorblock-remove music_offtopic --sponsorblock-mark sponsor,intro,outro -x --audio-format mp3 URL

Educational Content

Remove sponsors but keep educational content

yt-dlp --sponsorblock-remove sponsor --sponsorblock-mark intro,outro --write-info-json URL

Batch Processing with Archive

Process playlist with SponsorBlock and archiving

yt-dlp --sponsorblock-remove sponsor,intro,outro --download-archive processed.txt -o "%(uploader)s/%(title)s.%(ext)s" PLAYLIST_URL

Integration with Other Features

Combining with Format Selection

High-quality download with SponsorBlock

yt-dlp -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" --sponsorblock-remove sponsor --merge-output-format mp4 URL

With Subtitle Processing

Download with subtitles and SponsorBlock

yt-dlp --write-subs --embed-subs --sponsorblock-mark default --sub-langs en,en-US URL

With Post-Processing

Convert to MP3 with sponsor removal

yt-dlp -x --audio-format mp3 --sponsorblock-remove sponsor,intro,outro --embed-metadata URL

With Chapter Splitting

Split by chapters and remove sponsors

yt-dlp --split-chapters --sponsorblock-remove sponsor -o "%(title)s/%(section_title)s.%(ext)s" URL

Configuration File Examples

Default SponsorBlock Config

# ~/.config/yt-dlp/config
# Default SponsorBlock settings

# Mark sponsors and intros, remove outros
--sponsorblock-mark sponsor,intro
--sponsorblock-remove outro

# Custom chapter titles
--sponsorblock-chapter-title "[%(category_names)s]"

Content-Specific Configs

For music downloads:

# ~/.config/yt-dlp/music.conf
--sponsorblock-remove sponsor,intro,outro,music_offtopic
--sponsorblock-mark interaction
-x --audio-format mp3

For educational content:

# ~/.config/yt-dlp/education.conf
--sponsorblock-remove sponsor,interaction
--sponsorblock-mark intro,outro
--write-subs --embed-subs

Performance and Behavior

Network Requests

SponsorBlock integration requires additional API calls:

One request per video to fetch segment data
Minimal impact on download speed
Cached results for repeated downloads

Processing Order

Video extraction and format selection
SponsorBlock API query for segment data
Video download
Segment processing (marking/removing)
Post-processing (if any)

Error Handling

Continue if SponsorBlock data unavailable

yt-dlp --sponsorblock-mark default --ignore-errors URL

Verbose output for debugging

yt-dlp --sponsorblock-mark default --verbose URL

Troubleshooting

Common Issues

No SponsorBlock data available:

Check if video has SponsorBlock data

yt-dlp --simulate --verbose --sponsorblock-mark default URL

API connectivity issues:

Test API connectivity

curl "https://sponsor.ajay.app/api/skipSegments?videoID=VIDEO_ID"

Use alternative API

yt-dlp --sponsorblock-api "https://sponsor.ajay.app" URL

Segment processing errors:

Skip problematic segments

yt-dlp --sponsorblock-mark default --ignore-errors URL

Debug segment processing

yt-dlp --sponsorblock-mark default --verbose --keep-fragments URL

Verification

Check chapter markers in output

ffprobe -v quiet -show_chapters -print_format csv output.mp4

Verify removed segments

ffprobe -v quiet -show_format -print_format json output.mp4

Category Selection Strategy

Conservative approach:

yt-dlp --sponsorblock-remove sponsor --sponsorblock-mark intro,outro URL

Aggressive cleaning:

yt-dlp --sponsorblock-remove sponsor,intro,outro,interaction,selfpromo URL

Content-aware:

Music videos

yt-dlp --sponsorblock-remove music_offtopic URL

Educational content

yt-dlp --sponsorblock-remove sponsor,interaction URL

Performance Optimization

Batch processing optimization

yt-dlp --sponsorblock-remove sponsor --concurrent-fragments 4 --sleep-interval 1 --batch-file urls.txt

What is SponsorBlock?​

SponsorBlock Categories​

Special Category Groups​

Basic SponsorBlock Usage​

Enable SponsorBlock Processing​

Mark vs Remove​

Advanced SponsorBlock Options​

Category Selection​

Custom Chapter Titles​

Available Template Fields​

Custom SponsorBlock API​

Disable SponsorBlock​

Practical Usage Examples​

Content Creator Workflow​

Clean Viewing Experience​

Music Video Processing​

Educational Content​

Batch Processing with Archive​

Integration with Other Features​

Combining with Format Selection​

With Subtitle Processing​

With Post-Processing​

With Chapter Splitting​

Configuration File Examples​

Default SponsorBlock Config​

Content-Specific Configs​

Performance and Behavior​

Network Requests​

Processing Order​

Error Handling​

Troubleshooting​

Common Issues​

Verification​

Category Selection Strategy​

Performance Optimization​