Python Sponsorblock

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

Installation

# using this gitea repository (recommended)
pip install --index-url https://gitea.elara.ws/api/packages/music-kraken/pypi/simple/ python-sponsorblock

# using pip
pip install python-sponsorblock

Why does this exist?

I decided against using the already existing sponsorblock.py 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 sponsorblock.py project, it is just a different approach. My other "issue" with the sponsorblock.py 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.

Usage

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="https://sponsor.ajay.app",    # the url of the sponsorblock api, make sure there is no trailing slash
)

print(sb.get_segments("https://yt.artemislena.eu/watch?v=w5GmDRW975g"))

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("https://yt.artemislena.eu/watch?v=w5GmDRW975g")

Data Objects

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

from python_sponsorblock import constants

Segment

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(
    UUID="uuid",
    segment=(0.0, 10.0),
    category=Category.SPONSOR,
    videoDuration=100.0,
    actionType=ActionType.SKIP,
    locked=0,
    votes=10,
    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.

3.9 KiB Raw Permalink Blame History