Skip to content

[fd/sabr] Add YouTube SABR protocol downloader #13515

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 19 commits into
base: master
Choose a base branch
from
Draft

[fd/sabr] Add YouTube SABR protocol downloader #13515

wants to merge 19 commits into from
+6,283 −285

Conversation

coletdjnz
Copy link
Member

@coletdjnz coletdjnz commented Jun 21, 2025 •
edited
Loading

Tip

How to test

Install
Latest build: https://github.com/coletdjnz/yt-dlp-dev/releases/tag/2025.07.12.000932
Using pip: pip install --force-reinstall "yt-dlp[default] @ git+https://github.com/coletdjnz/yt-dlp-dev@feat/youtube/sabr"

Example usage:
Default clients: To force SABR formats, use --extractor-args "youtube:formats=duplicate" -f "ba[protocol=sabr]+bv[protocol=sabr]"

With web client: --extractor-args "youtube:formats=duplicate;player-client=web" -f "ba[protocol=sabr]+bv[protocol=sabr]"

Debug/trace logging with web client:
--extractor-args "youtube:formats=duplicate;player-client=web;sabr_log_level=debug" -f "ba[protocol=sabr]+bv[protocol=sabr]"
Note for web: you will need to provide a PO Token

If encountering reproducible issues, please run with debug (or trace) logging and provide the output as this contains key information to help with debugging.

Adds support for YouTube's Server Adaptive Bit Rate (SABR) streaming protocol.

SABR formats are available for all clients that provide a SABR URL in the player response.

By default, yt-dlp will prioritize https formats over sabr formats. SABR formats can always be included with formats=duplicate extractor arg.

Closes #12482

Requires the protobug library to handle protobuf data (thanks @Grub4K for developing it). This is included in all builds by default.

Features:

  • Video support
  • Concurrent audio+video format downloads
  • Livestream support - including --live-from-start and post-live
  • Resuming downloads (inc. live, if filename is the same)
  • --retry-sleep
  • --audio-multistreams / --video-multistreams support
  • Live captions (experimental)
  • PO Token status detection - with automatic re-fetch from PO Token providers on expiration/invalidation
  • GVS URL expiry handling - for both videos and livestreams
  • GVS Fallback server handling
  • Robust error handling and retry logic
  • Sequence-based download part file logic - avoids clogging up directory with hundreds of segment files while still supporting resuming downloads.
  • Debug/trace log levels that provide necessary information for debugging without needing to mitm/dump requests.

Not supported but may be considered in the future:

  • --download-sections
    • Likely requires core changes to support sending data from downloader -> PP
  • --rate-limit
  • -N / concurrency support
    • Might be difficult due to the nature of the protocol
  • Split livestream broadcast support (currently bails when the broadcast ID changes)
  • Redirect to stdout - yt-dlp core only supports this for pre-merged streams. Single format streams were only supported by ffmpeg which does not support SABR. Would require some sort of built-in muxer.
  • Concurrent audio+video+live subtitle download. While the sabr downloader technically supports this, yt-dlp core does support it.

Other notes:

  • Any external users (e.g. media player) will have to support the SABR protocol if they are to use SABR format metadata extracted by yt-dlp.
  • Due to server-side ad enforcement, the downloader may need to wait an amount of time specified by the server before receiving video data. There is a full bypass for this however it is not a long term solution, so I have not included it in this PR as we need to test the wait logic.
  • Added guards to try prevent video corruption / server trying to control the client in ways we do not expect.

Useful resources:

Template

Before submitting a pull request make sure you have:

In order to be accepted and merged into yt-dlp each piece of code must be in public domain or released under Unlicense. Check those that apply and remove the others:

  • I am the original author of the code in this PR, and I am willing to release it under Unlicense
  • I am not the original author of the code in this PR, but it is in the public domain or released under Unlicense (provide reliable evidence)

What is the purpose of your pull request? Check those that apply and remove the others:

@coletdjnz coletdjnz added needs-testing Patch needs testing site:youtube core:downloader downloader related labels Jun 21, 2025
@coletdjnz coletdjnz mentioned this pull request Jun 14, 2025
Open
This was referenced Jun 21, 2025
Closed
Open
@Figim
Copy link

Figim commented Jun 21, 2025 •
edited
Loading

How will the SSAP ads be?
Could there be a solution for these? Will ads appear in apps like newpipe?

@NHOrus
Copy link

NHOrus commented Jun 23, 2025

My current main gripe is that yt-dlp with SABR doesn't print the name of the video it is downloading until after download is complete.

@ALRBP
Copy link

ALRBP commented Jun 23, 2025 •
edited
Loading

My current main gripe is that yt-dlp with SABR doesn't print the name of the video it is downloading until after download is complete.

It will if you download the thumbnail. Anyway, I am testing it right now on some DRM+SABR experiment burner account (no premium), with BgUtils POT provider plugin (also got some random DRM+SABR experiment without cookies). Seems like it works perfectly fine. Best formats (checked against "stats for nerds" in normal browser) are downloaded. Thanks a lot.

@coletdjnz
Copy link
Member Author

coletdjnz commented Jun 24, 2025 •
edited
Loading

How will the SSAP ads be? Could there be a solution for these? Will ads appear in apps like newpipe?

we don't have full technical details nor able to reproduce them, so can't say at this time. hoping the guards we have will cause the downloader to fail if the server tries to do anything funny with ad insertion for videos.

similarly, SSDAI and SSLIFA ads for livestreams (which I have been able to reproduce) do not impact the downloader at this stage as the client has to ask the server to stitch them (lol).

@coletdjnz
Copy link
Member Author

My current main gripe is that yt-dlp with SABR doesn't print the name of the video it is downloading until after download is complete.

fixed, thanks (I presume you are referring to the destination filename message)

@Figim Figim mentioned this pull request Jun 29, 2025
Open
@coletdjnz coletdjnz mentioned this pull request Jul 5, 2025
Merged
8 tasks
@Figim Figim mentioned this pull request Aug 3, 2025
Merged
@pha1n0q pha1n0q mentioned this pull request Aug 8, 2025
Open
6 tasks
@taran1250 taran1250 mentioned this pull request Aug 9, 2025
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
core:downloader downloader related needs-testing Patch needs testing site:youtube
Projects
None yet
Milestone
No milestone
4 participants
@coletdjnz @Figim @NHOrus @ALRBP