API Reference

If the API reference does not have the documentation for any method. See the source code, since all methods do have docstrings that you can use.

Submodules

sponsorblock.client module

The client module provides a Client for the SponsorBlock API.

Module for the client class.

class sponsorblock.client.Client(*args, **kwargs)

Bases: object

A client for making requests to the sponsorblock server.

add_skip_segments(video_id: str, *, segment: Segment | None = None, segments: List[Segment] | None = None, service: str = 'YouTube') → None

Add a skip segment to the server.

Parameters:

video_id (str) – The id of the video to add the skip segment to, can be a video url too.
segment (Segment) – The skip segment to add
segments (List[Segment]) – The list of skip segments to add
service (str) – The service to use, default is ‘YouTube’. See https://wiki.sponsor.ajay.app/w/Types#service.

Raises:

ValueError – No segments were specified
ValueError – The video id is invalid
InvalidJSONException – The server returned invalid JSON
BadRequest – The server returned a 400 error, most likely because your inputs are wrong/impossible
Forbidden – The server returned a 403 error, most likely because you are not allowed to add skip segments
RateLimitException – The server returned a 429 error, most likely because you are making too many requests
DuplicateException – The server returned a 409 error, most likely because the skip segment already exists
ServerException – The server returned a 500 error, most likely because the server is down
UnexpectedException – The server returned a response code that is not handled

Examples

>>> """Adding new segments to a YouTube video (Note: this is a example and don't try this yourself)"""
>>> import sponsorblock as sb
>>> client = sb.Client()
>>> client.add_skip_segments(
        "https://www.youtube.com/watch?v=kJQP7kiw5Fk",
        segment=sb.Segment(category="music_offtopic", start=0, end=21.808434, action_type="skip")
    )

get_saved_days_formatted()

get_saved_time_for_user()

get_segment_info()

get_skip_segments()

get_skip_segments_with_hash()

get_top_users()

get_total_stats()

get_user_info()

get_user_name()

get_views_for_user()

post_viewed_video_sponsor_time(uuid: Segment | str)

Notifies the server that a segment has been skipped.

Parameters:

uuid (Union[Segment, str]) – The uuid of the segment that was skipped

Raises:

BadRequest – The server returned a 400 error, most likely because your inputs are wrong/impossible
ServerException – The server returned a 500 error, most likely because the server is down
UnexpectedException – The server returned a response that was not 200, 400, or 500

Examples

>>> import sponsorblock as sb
>>> client = sb.Client()
>>> segments = client.get_skip_segments("https://www.youtube.com/watch?v=kJQP7kiw5Fk")
>>> client.post_viewed_video_sponsor_time(segments[1])

search_for_user()

set_user_name(user_name: str)

Sets the user name for the current user.

Parameters:

user_name (str) – The user name to set for the current user.

Raises:

BadRequest – The server returned a 400 error, most likely because your inputs are wrong/impossible
ServerException – The server returned a 500 error, most likely because the server is down
UnexpectedException – The server returned a response that was not 200, 400, or 500

Examples

>>> import sponsorblock as sb
>>> client = sb.Client("your local user id")
>>> client.set_user_name("NoobMaster69")

Votes on a skip segment.

Parameters:

uuid (Union[Segment, str]) – segment or uuid of the segment being voted on
vote (Union[str, int, bool], optional) – The vote to vote on the skip segment. Can be any of yes, upvote, up, good, 1, True for upvoting, no, downvote, down, bad, 0, False for downvoting, and undo for undoing a given vote
category (Category, optional) – The category of the skip segment. This can be used as an alternative to the vote parameter, by default None

Raises:

ValueError – You passed both vote and category.
BadRequest – The server returned a 400 error, most likely because your inputs are wrong/impossible
Forbidden – The server returned a 403 error, most likely because you are not allowed to vote on the skip segment
ServerException – The server returned a error, most likely because the server is down
UnexpectedException – The server returned a response that was not 200, 400, 403, 429, 409, or 500

Examples

>>> import sponsorblock as sb
>>> client = sb.Client()
>>> segments = client.get_skip_segments("https://www.youtube.com/watch?v=kJQP7kiw5Fk")
>>> client.vote_skip_segment(segments[0], 'yes')

sponsorblock.client.raise_request_exception(response: Response)

If the server returns a status code, which is not 200, it needs to raise an exception:

Every exception inherits from HTTPException

Parameters:: response –
Returns:

sponsorblock.models module

class sponsorblock.models.SearchedUser(data)

Bases: object

A user gotten by searching for his name

name

The name of the user

Type:: str

id

The id of the user

Type:: str

Warning

You should not make a instance of this yourself, this should only be created by the libray

class sponsorblock.models.Segment(category: Literal['sponsor', 'selfpromo', 'interaction', 'intro', 'outro', 'preview', 'music_offtopic', 'poi_highlight', 'filler'], start: float | timedelta, end: float | timedelta, uuid: str | None = None, duration: timedelta | None = None, action_type: str | None = None, *, data: dict | None = None)

Bases: object

A skip segment

category

The category of the segment

Type:: Category

start

The start time of the segment

Type:: float

end

The end time of the segment

Type:: float

uuid

The uuid of the segment, by default None

Type:: Optional[str], optional

duration

The duration of the segment, by default None

Type:: Optional[timedelta], optional

action_type

The action_type of the segment, by default None

Type:: Optional[str], optional

data

The raw data that was used to create the segment, can be None if the segment was created manually

Type:: Optional[dict], optional

Note

While creating your own instance you should only pass the category, start and end time. The other attributes won’t do anything, those are only useful for segments gotten from the API.

classmethod from_dict(data: dict)

Generates a Segment object from a JSON dictionary.

Parameters:: data (dict) – The dictionary containing the segment data.
Returns:: The segment object gotten form the data.
Return type:: Segment

Warning

This should not be used manually, this is for the library

class sponsorblock.models.SegmentInfo(data)

Bases: object

A class representing the segment info

video_id

The id of the video

Type:: str

start_time

The start time of the segment

Type:: float

end_time

The end time of the segment

Type:: float

votes

The amount of votes the segment has

Type:: int

locked

Whether the segment is locked

Type:: int

uuid

The uuid of the segment

Type:: str

user_id

The id of the user that created the segment

Type:: str

time_submitted

The time the segment was submitted

Type:: datetime.datetime

views

The amount of views the segment has

Type:: int

category

The category of the segment

Type:: str

action_type

The action type of the segment

Type:: str

service

The service of the segment

Type:: str

video_duration

The duration of the video

Type:: float

hashed_video_id

The hashed video id of the video

Type:: str

user_agent

The user agent of the segment

Type:: str

Warning

You should not make a instance of this yourself, this should only be created by the libray

class sponsorblock.models.TopUser(user_name: str, view_count: int, total_submissions: int, minutes_saved: float)

Bases: object

A top user.

user_name

The name of the user

Type:: str

view_count

The total number of views of the user’s segments

Type:: int

total_submissions

The total number of submissions the user has made

Type:: int

minutes_saved

The amount of time the user has saved

Type:: float

Warning

You should not make a instance of this yourself, this should only be created by the libray

class sponsorblock.models.TotalStats(data)

Bases: object

The total stats

user_count

The amount of users, only available if count_contributing_users was true

Type:: int

active_users

Sum of public install stats from Chrome webstore and Firefox addons store

Type:: int

api_users

48-hour active API users

Type:: int

view_count

The total number of views

Type:: int

total_submissions

The total number of submissions

Type:: int

minutes_saved: The total amount of time saved

Warning

You should not make a instance of this yourself, this should only be created by the libray

class sponsorblock.models.User(data: dict)

Bases: object

A user

user_id

The id of the user

Type:: str

user_name

The name of the user

Type:: str

minutes_saved

The amount of minutes saved by the user

Type:: int

segment_count

The amount of segments created by the user

Type:: int

ignored_segment_count

The amount of segments that were ignored by the user

Type:: int

view_count

The amount of views by the user

Type:: int

ignored_view_count

The amount of views that were ignored by the user

Type:: int

warnings

The amount of warnings the user has

Type:: int

reputation

The amount of reputation the user has

Type:: int

vip

Whether the user is a VIP

Type:: bool

last_segment_id

The id of the last segment created by the user

Type:: str

Warning

You should not make a instance of this yourself, this should only be created by the libray

sponsorblock.errors module

exception sponsorblock.errors.BadRequest(message, response: Response)

Bases: HTTPException

Raised when the status code is 400.

exception sponsorblock.errors.DuplicateException(message, response: Response)

Bases: HTTPException

Raised when the status code is 409.

exception sponsorblock.errors.Forbidden(message, response: Response)

Bases: HTTPException

Raised when the status code is 403.

exception sponsorblock.errors.HTTPException(message, response: Response)

Bases: Exception

Raised when the server returns an error code

exception sponsorblock.errors.InvalidJSONException(message, response)

Bases: Exception

Raised when the JSON gotten from the server is invalid

exception sponsorblock.errors.NotFoundException(message, response: Response)

Bases: HTTPException

Raised when the status code is 404.

exception sponsorblock.errors.RateLimitException(message, response: Response)

Bases: HTTPException

Raised when the status code is 429.

exception sponsorblock.errors.ServerException(message, response: Response)

Bases: HTTPException

Raised if the status code is bigger than 500.

exception sponsorblock.errors.UnexpectedException(message, response: Response)

Bases: HTTPException

Raised when an unknown error has occurred.

sponsorblock.utils module

class sponsorblock.utils.Singleton: Bases: type

class sponsorblock.utils.SortType(value)

Bases: Enum

0 for by minutes saved, 1 for by view count, 2 for by total submissions