This is a wrapper for the sponsorblock api, enabling you to get the timestamps of sponsor segments from youtube videos.
Go to file
Hazel dd3714f8c8
ci/woodpecker/push/woodpecker Pipeline was successful Details
ci/woodpecker/tag/woodpecker Pipeline was successful Details
feat: fetches per default every category
2024-05-13 13:53:36 +02:00
.vscode feat: wrote proper documentation 2024-04-25 14:37:08 +02:00
assets feat: created logo 2024-04-25 21:59:30 +02:00
development fix: implemented better and more generalized error handling for the api 2024-04-25 12:46:57 +02:00
python_sponsorblock feat: fetches per default every category 2024-05-13 13:53:36 +02:00
tests feat: implemented more tests 2024-04-25 15:00:54 +02:00
.gitignore ci: add version file to gitignore 2024-04-25 19:45:09 -07:00
.woodpecker.yml ci: install requests package 2024-04-25 19:50:11 -07:00
LICENSE Initial commit 2024-04-24 08:34:28 +00:00 docs: add ci badge 2024-04-25 19:56:55 -07:00
pyproject.toml ci: add pipeline 2024-04-25 19:43:08 -07:00

Python Sponsorblock


python-sponsorblock logo

This is a wrapper for the sponsorblock api, enabling you to get the timestamps of sponsor segments from Youtube videos.


# using this gitea repository (recommended)
pip install --index-url python-sponsorblock
# using pip
pip install python-sponsorblock

Why does this exist?

I decided against using the already existing for one main reason. It sometimes throws exceptions that do not belong to the project itself. An example for this are request exceptions. This is fine, but it shows a diverging philosophy from what I want to achieve with this project. I want to have an wrapper that just gets all data it can in a structured way. I don't want a library that does the requests for you, I want a library that gives you the data. I want to stress, this is not an attack on the project, it is just a different approach. My other "issue" with the project is, that it is way to complex. Thus fixing it would require more time than implementing the functionality I need from scratch.

I decided to catch all necessary exceptions, that cant be handled and either throw an exception inheriting from one base exception or return empty data.


Every relevant function can be found in the Sponsorblock class.

from python_sponsorblock import SponsorBlock
import requests

# all arguments are optional and are set to the default values in this example
sb = SponsorBlock(
    session=requests.Session(),    # a requests session object
    silent=False,    # throw exceptions or return empty data
    base_url="",    # the url of the sponsorblock api, make sure there is no trailing slash


You can import all of the exceptions that can be thrown like this:

from python_sponsorblock import exceptions

Get the Data

Because I don't need much functionality, I havent implemented a lot of api requests. The following list contains every function, that I plan to implement:

  • Get Segments

If you need more functionality, just raise an issue or create a pull request. Here is an overview for all api endpoints I could write wrappers for.

Every function that requires a video id as input, can also take a full url as input. The function will extract the video id from the url.

Get Segments

This function gets all segments of a video.

from python_sponsorblock import SponsorBlock, constants
from python_sponsorblock.constants import Segment

sb = SponsorBlock()
segments: List[Segment] = sb.get_segments("")

Data Objects

All Data Classes, Enums and simmilar objects can be found in the constants module.

from python_sponsorblock import constants


This is most arguably the most important object in this library. It represents a segment of a video that is a sponsor segment.

from python_sponsorblock.exceptions import Segment, Category, ActionType

    segment=(0.0, 10.0),
    description="This is a sponsor segment"

Enums (Types)

The enums are just representations of the types that are used in the sponsorblock api. This is the official documentation of the sponsor block types.