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, segments: List[Segment] = None, service: str = 'YouTube') → None

Add a skip segment to the server.

Parameters:
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")
    )
add_user_as_temp_vip(public_userid: str, channel_video_id: str, *, enabled: bool = True) → None

Grants a user temporary (24 hour) VIP status on a channel.

Note

This can only be used by VIP users. A user can only be a temporary VIP of one channel at a time, the most recent channel takes precedence.

Parameters:

  • public_userid (str) – The public user id of the user to grant temporary VIP status to.

  • channel_video_id (str) – The id of a video of the channel to grant VIP status on, can be a video url too.

  • enabled (bool, optional) – True to grant, False to revoke, by default True.

Raises:

  • ValueError – The video id is invalid

  • 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 a VIP

  • NotFoundException – The server returned a 404 error, because no channel was found for the video id

  • DuplicateException – The server returned a 409 error, because the user is already a permanent VIP

  • 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

add_user_as_vip(public_userid: str, *, enabled: bool = True) → None

Adds or removes a user from the VIP list.

Note

This can only be used by the server administrator.

Parameters:

  • public_userid (str) – The public user id of the user to add to the VIP list.

  • enabled (bool, optional) – True to add the user, False to remove them, by default True.

Raises:

  • 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 the administrator

  • 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

clear_cache(video_id: str) → None

Clears the server’s redis cache for a video.

Note

This can only be used by VIP users.

Parameters:

video_id (str) – The id of the video to clear the cache for, can be a video url too.

Raises:

  • ValueError – The video id is invalid

  • 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 a VIP

  • 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

get_lock_reason(video_id: str, *, category: Literal['sponsor', 'selfpromo', 'interaction', 'intro', 'outro', 'preview', 'hook', 'music_offtopic', 'poi_highlight', 'filler', 'exclusive_access', 'chapter'] = None, categories: List[str] = None, action_types: List[str] = None) → List[LockReason]

Gets the lock reasons for the categories of a video.

Parameters:

  • video_id (str) – The id of the video to get the lock reasons for, can be a video url too.

  • category (str, optional) – A single category to get the lock reason for, defaults to all categories.

  • categories (List[str], optional) – The categories to get the lock reasons for, defaults to all categories.

  • action_types (List[str], optional) – The action types to get lock reasons for.

Returns:

The lock status and reason for each requested category.

Return type:

List[LockReason]

Raises:

  • 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

  • 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()
>>> client.get_lock_reason("kJQP7kiw5Fk", category="music_offtopic")
[LockReason(category=music_offtopic, locked=1, reason=..., user_id=..., user_name=...)]
get_locked_categories(video_id: str, *, action_types: List[str] = None) → LockedCategories

Gets the locked categories for a video.

Parameters:

  • video_id (str) – The id of the video to get the locked categories for, can be a video url too.

  • action_types (List[str], optional) – The action types to get locks for, defaults to ["skip", "mute"] on the server.

Returns:

The locked categories for the video, along with the most recent lock reason.

Return type:

LockedCategories

Raises:

  • 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

  • NotFoundException – The server returned a 404 error, most likely because the video has no locked categories

  • 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, 404, or 500

Examples

>>> import sponsorblock as sb
>>> client = sb.Client()
>>> client.get_locked_categories("kJQP7kiw5Fk")
LockedCategories(categories=['music_offtopic'], reason=..., action_types=['skip', 'mute'], video_id=None)
get_locked_categories_with_hash(video_id: str, video_hash: str = None) → LockedCategories

Gets the locked categories for a video using a K-Anonymity system.

Parameters:

  • video_id (str) – The id of the video to get the locked categories for, can be a video url too.

  • video_hash (str, optional) – The sha256 hash prefix of the video id, if not given it is generated from the video id using the client’s hashed_video_id_length. Must be between 4 and 32 characters.

Returns:

The locked categories for the video, along with the video id, full hash and lock reason.

Return type:

LockedCategories

Raises:

  • ValueError – The video id is invalid

  • TypeError – The video hash length is not between 4 and 32

  • InvalidJSONException – The server returned invalid JSON

  • BadRequest – The server did not return a lock for the requested video

  • NotFoundException – The server returned a 404 error, most likely because the video has no locked categories

  • 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, 404, or 500

Examples

>>> import sponsorblock as sb
>>> client = sb.Client()
>>> client.get_locked_categories_with_hash("kJQP7kiw5Fk")
LockedCategories(categories=['music_offtopic'], reason=..., action_types=None, video_id=kJQP7kiw5Fk)
get_saved_days_formatted() → float

Returns the amount of days that have been saved.

Returns:

The amount of days that have been saved

Return type:

float

Raises:

Examples

>>> import sponsorblock as sb
>>> client = sb.Client()
>>> client.get_saved_days_formatted()
132654.20
get_saved_time_for_user()

Gets the total time saved from all the current user’s segments.

Returns:

The amount of time saved by the current user’s segments, in minutes.

Return type:

float

Raises:

  • InvalidJSONException – The server returned a response that was not valid JSON.

  • NotFoundException – The server returned a 404 error, most likely because the user was not found.

  • 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.get_saved_time_for_user()
1181.974021220207
get_segment_info(segment: Segment | str = None, segments: List[Segment | str] = None) → List[SegmentInfo]

Gets detailed information about a segment.

Parameters:

  • segment (Union[Segment, str], optional) – The segment to get information about., by default None

  • segments (List[Union[Segment, str]], optional) – A list of segments to get information about, by default None

Returns:

The information about the segment(s) specified.

Return type:

List[SegmentInfo]

Raises:

  • ValueError – No segment were specified.

  • InvalidJSONException – The server returned invalid JSON.

  • ServerException – The server returned a 500 error, most likely because the server is unavailable.

  • NotFoundException – The segment(s) specified were not found.

  • BadRequest – The server returned a 400 error, most likely because your inputs are wrong/impossible or exceeds the maximum allowed size.

  • 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")
>>> segment_infos = client.get_segment_info(segments=segments)
>>> segment_infos
[
    SegmentInfo(
        video_id=kJQP7kiw5Fk,
        start_time=0,
        end_time=21.808434,
        votes=15,
        locked=0,
        uuid=728cbf1743f4b5230ee4a9c7b254e316aa90720ec35297b17aaf6d23907c1a83,
        user_id=2ad8fd8d67e5321fed0e6c1b46682c2db3c4d5734434715712f4d1292ee2781e,
        time_submitted=2020-06-16 20:00:05.037000,
        views=43655,
        category=music_offtopic,
        service=YouTube,
        video_duration=0,
        hashed_video_id=f1d9e193c3a58e59468eb88b50929d8095ccfa2476ed8db58e5907cafc890d9f,
        user_agent=""
    ),
    ... (more segments)
]
>>> segment_infos[0].time_submitted.day
16
get_skip_segments(video_id: str, *, category: Literal['sponsor', 'selfpromo', 'interaction', 'intro', 'outro', 'preview', 'hook', 'music_offtopic', 'poi_highlight', 'filler', 'exclusive_access', 'chapter'] = None, categories: List[str] = None, required_segments: List[str] = None, action_type: Literal['skip', 'mute', 'full', 'poi', 'chapter'] = None, action_types: List[str] = None, service: str = 'YouTube') → List[Segment]

Gets the skip segments for a given video.

Parameters:
Returns:

A list of segments of the video

Return type:

List[Segment]

Raises:

  • ValueError – The video id is invalid

  • ConnectionException – The connection to the server failed (e.g. no internet connection)

  • InvalidJSONException – The server returned invalid JSON

  • BadRequest – The server returned a 400 error, most likely because your inputs are wrong/impossible

  • NotFoundException – The server returned a 404 error, most likely because the video id is invalid

  • 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, 404, or 500

Note

If the client was created with silent=True, none of the request related exceptions are raised, instead a warning is logged and an empty list is returned.

Examples

>>> import sponsorblock as sb
>>> client = sb.Client()
>>> segments = client.get_skip_segments("https://www.youtube.com/watch?v=kJQP7kiw5Fk")
>>> segments
[
    Segment(category=music_offtopic, start=0, end=21.808434, uuid=728cbf1743f4b5230ee4a9c7b254e316aa90720ec35297b17aaf6d23907c1a83, duration=0:00:21.808434, action_type=skip),
    Segment(category=music_offtopic, start=249.6543, end=281.521, uuid=ae38abe70c63b093eaeb1c2c437aa3275856646c326ee23b5ff70dcb4190c92f, duration=0:00:31.866700, action_type=skip),
    Segment(category=outro, start=274.674, end=281.521, uuid=cd335e7f406df63e460b4b02db71cc57344529d381bb9fc482960f338ff4ae37, duration=0:00:06.847000, action_type=skip),
    Segment(category=poi_highlight, start=27.949, end=27.949, uuid=5e560eec60e99a8f0a5056816800c32bb8c86ff06d4b57cece8f7be5504a1077e, duration=0:00:00, action_type=skip)
]
>>> segments[0].category
'music_offtopic'
>>> segments[1].start, segments[1].end
(249.6543, 281.521)
>>> segments[2].duration.seconds
6
get_skip_segments_with_hash(video_id: str, video_hash: str = None, *, category: Literal['sponsor', 'selfpromo', 'interaction', 'intro', 'outro', 'preview', 'hook', 'music_offtopic', 'poi_highlight', 'filler', 'exclusive_access', 'chapter'] = None, categories: List[str] = None, required_segments: List[str] = None, action_type: Literal['skip', 'mute', 'full', 'poi', 'chapter'] = None, action_types: List[str] = None, service: str = 'YouTube') → List[Segment]

Gets the skip segments for a given video using a K-Anonymity system.

Parameters:
Returns:

A list of segments of the video

Return type:

List[Segment]

Raises:

  • ValueError – The video id is invalid

  • ConnectionException – The connection to the server failed (e.g. no internet connection)

  • InvalidJSONException – The server returned invalid JSON

  • BadRequest – The server returned a 400 error, most likely because your inputs are wrong/impossible

  • NotFoundException – The server returned a 404 error, most likely because the video id is invalid

  • 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, 404, or 500

Note

If the client was created with silent=True, none of the request related exceptions are raised, instead a warning is logged and an empty list is returned.

Examples

>>> import sponsorblock as sb
>>> client = sb.Client()
>>> segments = client.get_skip_segments_with_hash("f1d9e193c3a58e59468eb88b50929d80")
>>> segments
[
    Segment(category=music_offtopic, start=0, end=21.808434, uuid=728cbf1743f4b5230ee4a9c7b254e316aa90720ec35297b17aaf6d23907c1a83, duration=0:00:21.808434, action_type=skip),
    Segment(category=music_offtopic, start=249.49852, end=281.521, uuid=3d78f759477445f70f04063df12523038eff3928c6a99c11e7cdd3bd9a51311f, duration=0:00:32.022480, action_type=skip),
    Segment(category=outro, start=274.674, end=281.521, uuid=cd335e7f406df63e460b4b02db71cc57344529d381bb9fc482960f338ff4ae37, duration=0:00:06.847000, action_type=skip),
    Segment(category=poi_highlight, start=27.949, end=27.949, uuid=5e560eec60e99a8f0a5056816800c32bb8c86ff06d4b57cece8f7be5504a1077e, duration=0:00:00, action_type=skip)
]
>>> segments[0].category
'music_offtopic'
>>> segments[1].start, segments[1].end
(249.6543, 281.521)
>>> segments[2].duration.seconds
6
get_status(value: str = None) → ServerStatus | int | str | list

Gets the status of the sponsorblock server.

This includes information about the database, such as the current database version, along with uptime, load averages and more.

Parameters:

value (str, optional) – A single status field to get (e.g. uptime, db, loadavg), by default all fields are fetched and a ServerStatus is returned.

Returns:

The status of the server, or the single requested value.

Return type:

Union[ServerStatus, int, str, list]

Raises:

Examples

>>> import sponsorblock as sb
>>> client = sb.Client()
>>> client.get_status()
ServerStatus(uptime=244459.26, commit=bfca2fb0..., db=46, ...)
>>> client.get_status("db")
46
get_top_users(sort_type: SortType) → List[TopUser]

Gets the top users.

Warning

This endpoint is currently disabled on the official server and will always raise NotFoundException there. It may still work on self-hosted servers.

Parameters:

sort_type (SortType) – The sort type, can be either SortType.MINUTES_SAVED, SortType.VIEW_COUNT, or SortType.TOTAL_SUBMISSIONS

Returns:

The list of top 100 users.

Return type:

List[TopUser]

Raises:

  • InvalidJSONException – The server returned a response that was not valid JSON.

  • 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
>>> from sponsorblock import SortType
>>> client = sb.Client()
>>> top_users = client.get_top_users(sort_type=SortType.VIEW_COUNT)  # or `SortType.MINUTES_SAVED` or `SortType.TOTAL_SUBMISSIONS`
>>> top_users
[
    TopUser(user_name=cane, view_count=9663381, total_submissions=4773, minutes_saved=3061714.88099481),
    TopUser(user_name=FunkeymonkeyTTR, view_count=5061381, total_submissions=11604, minutes_saved=1312617.9428691764),
    TopUser(user_name=ltcars, view_count=4997845, total_submissions=4315, minutes_saved=1520388.8714212843),
    TopUser(user_name=GrandMaesterJ, view_count=2157448, total_submissions=3934, minutes_saved=758912.7349532802),
    TopUser(user_name=Zenomit, view_count=1588073, total_submissions=4026, minutes_saved=478283.88908721233),
    TopUser(user_name=E.Coli, view_count=1558146, total_submissions=6100, minutes_saved=412567.07062993734),
    ... # and so on (100 users)
]
>>> top_users[0].user_name
'cane'
>>> top_users[2].view_count
4997845
get_total_stats(count_contributing_users: bool = False) → TotalStats

Gets total stats for the api

Parameters:

count_contributing_users (bool) – Whether or not to count the number of users who have contributed to the api.

Returns:

The total stats for the api.

Return type:

TotalStats

Raises:

Examples

>>> import sponsorblock as sb
>>> client = sb.Client()
>>> totalstats = client.get_total_stats()
>>> totalstats
TotalStats(
    user_count=170551,
    active_users=295571,
    api_users=1323906,
    view_count=286114842,
    total_submissions=1946245,
    minutes_saved=144998543.20013103
)
>>> totalstats.user_count
170551
get_user_info(public_userid: str = None) → User

Gets the user info for the current user.

Parameters:

public_userid (str) – The public user id of the user to get information for, by default the current user id.

Returns:

The user info for the specified user.

Return type:

User

Raises:

  • InvalidJSONException – The server returned a response that was not valid JSON.

  • BadRequest – The server returned a 400 error, most likely because your inputs are wrong/impossible

  • NotFoundException – The server returned a 404 error, most likely because the user was not found.

  • 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

>>> """Example of getting the user info for the current user (a valid user id needs to be passed to the client):"""
>>> import sponsorblock as sb
>>> client = sb.Client("your local user id")
>>> client.get_user_info()
User(
    user_id=32be414f723dafb3b6903e92e1694f55f104de19c78d5f158c01c38e791fb792,
    user_name=Wasi Master,
    minutes_saved=1261.9740212202073,
    segment_count=47,
    ignored_segment_count=0,
    view_count=4367,
    ignored_view_count=0,
    warnings=0,
    reputation=0.04827586206896552,
    vip=False,
    last_segment_id=314db4f4677bbf6c8f9f614f82ba540fe1e2d596d490b5212a6d72a1b0cf266cb
)
>>> """Example of getting the user info for a specified user (a valid public user id needs to be passed to the method)"""
>>> import sponsorblock as sb
>>> client = sb.Client()
>>> user = client.get_user_info("57ddecc5b36813ddb8ea1eba73342c8a783527b884b6ebcb177bf37cafce7620")
User(
    user_id=57ddecc5b36813ddb8ea1eba73342c8a783527b884b6ebcb177bf37cafce7620,
    user_name=PureFallen,
    minutes_saved=240084.80235477304,
    segment_count=1407,
    ignored_segment_count=16,
    view_count=550885,
    ignored_view_count=3071,
    warnings=0,
    reputation=4.689655172413794,
    vip=True,
    last_segment_id=1490a3d5e4f966ecc745e21f2d23458f4952c84382e7c16e4859ca20c59daa21
)
>>> user.user_name
'PureFallen'
get_user_name() → str

Gets the user name for the current user.

Returns:

The user name for the current user.

Return type:

str

Raises:

  • InvalidJSONException – The server returned a response that was not valid JSON.

  • BadRequest – The server returned a 400 error, most likely because your inputs are wrong/impossible

  • NotFoundException – The server returned a 404 error, most likely because the user was not found.

  • 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.get_user_name()
'NoobMaster69'
get_user_stats(public_userid: str = None, *, fetch_category_stats: bool = False, fetch_action_type_stats: bool = False) → UserStats

Gets the stats for a user.

Parameters:

  • public_userid (str, optional) – The public user id of the user to get stats for, by default the current user id.

  • fetch_category_stats (bool, optional) – Whether to also fetch the number of segments per category, by default False

  • fetch_action_type_stats (bool, optional) – Whether to also fetch the number of segments per action type, by default False

Returns:

The stats for the specified user.

Return type:

UserStats

Raises:

  • InvalidJSONException – The server returned a response that was not valid JSON.

  • 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.get_user_stats(fetch_category_stats=True)
UserStats(
    user_id=32be414f723dafb3b6903e92e1694f55f104de19c78d5f158c01c38e791fb792,
    user_name=Wasi Master,
    minutes_saved=1261,
    segment_count=47,
    category_counts={'sponsor': 20, 'intro': 5, ...},
    action_type_counts=None
)
get_views_for_user()

Gets the view count for the current user.

Returns:

The amount of views for the current user.

Return type:

int

Raises:

  • InvalidJSONException – The server returned a response that was not valid JSON.

  • NotFoundException – The server returned a 404 error, most likely because the user was not found.

  • 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.get_views_for_user()
4367
is_user_vip() → bool

Checks whether the current user is a VIP.

Returns:

Whether the current user is a VIP.

Return type:

bool

Raises:

  • InvalidJSONException – The server returned invalid JSON

  • 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.is_user_vip()
False
lock_categories(video_id: str, categories: List[str], *, reason: str = '', action_types: List[str] = None) → None

Locks categories on a video, disallowing further submissions for those categories.

Note

This can only be used by VIP users.

Parameters:

  • video_id (str) – The id of the video to lock categories on, can be a video url too.

  • categories (List[str]) – The categories to lock.

  • reason (str, optional) – The reason for the lock, by default an empty string.

  • action_types (List[str], optional) – The action types the lock applies to.

Raises:

  • ValueError – The video id is invalid

  • 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 a VIP

  • 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, 403, or 500

Examples

>>> import sponsorblock as sb
>>> client = sb.Client("your local vip user id")
>>> client.lock_categories("kJQP7kiw5Fk", ["sponsor"], reason="Spam submissions")
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])
purge_all_segments(video_id: str, *, service: str = 'YouTube') → None

Hides all segments on a video without affecting the submitters’ reputations.

Note

This can only be used by VIP users.

Parameters:

  • video_id (str) – The id of the video to purge the segments of, can be a video url too.

  • service (str, optional) – The service of the video, default is ‘YouTube’.

Raises:

  • ValueError – The video id is invalid

  • 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 a VIP

  • 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

search_for_user(user_name: str, exact: bool = False) → List[SearchedUser]

Searches for a user based on their name.

Parameters:

  • user_name (str) – The name of the user to search for

  • exact (bool, optional) – Whether to only return exact matches or not, by default False

Returns:

A list of searched users, they have a name and a id attribute

Return type:

List[SearchedUser]

Raises:

  • InvalidJSONException – The server returned invalid JSON

  • ServerException – The server returned a 500 error, most likely because the server is unavailable.

  • NotFoundException – The user specified was not found.

  • BadRequest – The server returned a 400 error, most likely because your inputs are wrong/impossible or exceeds the maximum allowed size.

  • 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.search_for_user(user_name="WasiMaster", exact=True)
[
    SearchedUser(name=WasiMaster, id=a66d1147ad5ee1f4c8950767e430012e3e48451b6dd7f97377bfcafe4954e90d),
    SearchedUser(name=WasiMaster, id=44265cd70f468dab018577e74db13c38fa8e2784f6be54a3f0bb119648489d55)
]
search_segments(video_id: str, *, category: Literal['sponsor', 'selfpromo', 'interaction', 'intro', 'outro', 'preview', 'hook', 'music_offtopic', 'poi_highlight', 'filler', 'exclusive_access', 'chapter'] = None, categories: List[str] = None, action_type: Literal['skip', 'mute', 'full', 'poi', 'chapter'] = None, action_types: List[str] = None, service: str = 'YouTube', page: int = 0, min_votes: int = None, max_votes: int = None, min_views: int = None, max_views: int = None, locked: bool = True, hidden: bool = True, ignored: bool = True) → SegmentSearchResults

Searches all segments of a video based on the specified filters.

Note

This should not be used to know which segments to skip, since the vote and view thresholds that determine the best segments change over time. Use get_skip_segments() for that.

Parameters:

  • video_id (str) – The id of the video to search the segments of, can be a video url too.

  • category (str, optional) – A category to search segments for. See https://wiki.sponsor.ajay.app/w/Types

  • categories (List[str], optional) – A list of categories to search segments for.

  • action_type (str, optional) – An action type to search segments for.

  • action_types (List[str], optional) – A list of action types to search segments for.

  • service (str, optional) – The service to use, default is ‘YouTube’.

  • page (int, optional) – The page of results to get (10 segments per page), by default 0.

  • min_votes (int, optional) – Only return segments with at least this many votes.

  • max_votes (int, optional) – Only return segments with at most this many votes.

  • min_views (int, optional) – Only return segments with at least this many views.

  • max_views (int, optional) – Only return segments with at most this many views.

  • locked (bool, optional) – Whether to include locked segments, by default True.

  • hidden (bool, optional) – Whether to include hidden segments, by default True.

  • ignored (bool, optional) – Whether to include ignored segments (hidden or below the vote threshold), by default True.

Returns:

The total segment count, the page number, and up to 10 segments.

Return type:

SegmentSearchResults

Raises:

  • 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

  • NotFoundException – The server returned a 404 error, most likely because there are no matching segments

  • 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, 404, or 500

Examples

>>> import sponsorblock as sb
>>> client = sb.Client()
>>> results = client.search_segments("kJQP7kiw5Fk", min_votes=0)
>>> results.segment_count
16
>>> results.segments[0].category
'music_offtopic'
segment_shift(video_id: str, start_time: float, end_time: float) → None

Shifts all segments on a video.

Note

This can only be used by VIP users.

Parameters:

  • video_id (str) – The id of the video to shift the segments of, can be a video url too.

  • start_time (float) – The start time of the shift.

  • end_time (float) – The end time of the shift.

Raises:

  • ValueError – The video id is invalid

  • 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 a VIP

  • 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

set_user_feature(public_userid: str, feature: UserFeature | int, *, enabled: bool = True) → None

Adds or removes a feature for a user.

Note

This can only be used by VIP users.

Parameters:

  • public_userid (str) – The public user id of the user to change the features of.

  • feature (Union[UserFeature, int]) – The feature to add or remove, can be a UserFeature or the raw feature number.

  • enabled (bool, optional) – True to add the feature, False to remove it, by default True.

Raises:

  • BadRequest – The server returned a 400 error, most likely because the feature does not exist

  • Forbidden – The server returned a 403 error, most likely because you are not a VIP

  • 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

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")
shadow_ban_user(public_userid: str, *, enabled: bool = True, unhide_old_submissions: bool = None, categories: List[str] = None) → None

Shadow bans or unbans a user, hiding all their future submissions from everyone else.

Note

This can only be used by VIP users.

Parameters:

  • public_userid (str) – The public user id of the user to shadow ban.

  • enabled (bool, optional) – True to ban, False to unban, by default True.

  • unhide_old_submissions (bool, optional) – Whether all previous submissions should be (un)hidden as well.

  • categories (List[str], optional) – The categories to (un)hide, defaults to all categories on the server.

Raises:

  • 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 a VIP

  • DuplicateException – The server returned a 409 error, because the user is already shadowbanned

  • 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

unlock_categories(video_id: str, categories: List[str]) → None

Removes category locks on a video.

Note

This can only be used by VIP users.

Parameters:

  • video_id (str) – The id of the video to unlock categories on, can be a video url too.

  • categories (List[str]) – The categories to unlock.

Raises:

  • ValueError – The video id is invalid

  • 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 a VIP

  • 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, 403, or 500

Examples

>>> import sponsorblock as sb
>>> client = sb.Client("your local vip user id")
>>> client.unlock_categories("kJQP7kiw5Fk", ["sponsor"])
vote_skip_segment(uuid: Segment | str, *, vote: str | int | bool = None, category: Literal['sponsor', 'selfpromo', 'interaction', 'intro', 'outro', 'preview', 'hook', 'music_offtopic', 'poi_highlight', 'filler', 'exclusive_access', 'chapter'] = None) → None

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')
warn_user(public_userid: str, *, reason: str = '', enabled: bool = True) → None

Warns a user, temporarily banning them and showing them a warning message.

Note

This can only be used by VIP users.

Parameters:

  • public_userid (str) – The public user id of the user to warn.

  • reason (str, optional) – The reason for the warning.

  • enabled (bool, optional) – True to warn, False to remove the warning, by default True.

Raises:

  • 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 a VIP

  • DuplicateException – The server returned a 409 error, because the user is already warned

  • 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

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.LockReason(data: dict)

Bases: object

The lock status and reason of a category on a video

category

The category the lock applies to

Type:

str

locked

The status of the lock

Type:

int

reason

The reason for the lock

Type:

str

user_id

The public id of the VIP that locked the category

Type:

str

user_name

The username of the VIP that locked the category

Type:

str

Warning

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

class sponsorblock.models.LockedCategories(data: dict)

Bases: object

The locked categories of a video

categories

The categories that are locked for the video

Type:

List[str]

reason

The reason for the lock, only the most recent reason is available

Type:

str

action_types

The action types the lock applies to, not available when gotten with a hash

Type:

Optional[List[str]]

video_id

The id of the video, only available when gotten with a hash

Type:

Optional[str]

hash

The full hash of the video id, only available when gotten with a hash

Type:

Optional[str]

Warning

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

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', 'hook', 'music_offtopic', 'poi_highlight', 'filler', 'exclusive_access', 'chapter'], start: float | timedelta, end: float | timedelta, uuid: str | None = None, duration: timedelta | None = None, action_type: str | None = None, *, description: str | None = None, locked: int | None = None, votes: int | None = None, video_duration: float | 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

description

The chapter title for chapter segments, an empty string for other segments

Type:

Optional[str], optional

locked

Whether the segment is locked, only available for segments gotten from the API

Type:

Optional[int], optional

votes

The amount of votes on the segment, only available for segments gotten from the API

Type:

Optional[int], optional

video_duration

The duration of the video when the segment was submitted, only available for segments gotten from the API

Type:

Optional[float], 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, end time and optionally the action_type and description (for chapters). 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

hidden

Whether the segment is hidden (2 downvotes or downvoted by a VIP)

Type:

int

reputation

The reputation of the submitter at the time of submission

Type:

int

shadow_hidden

Whether the submitter is shadowbanned

Type:

int

hashed_video_id

The hashed video id of the video

Type:

str

user_agent

The user agent of the segment

Type:

str

description

The chapter title for chapter segments, an empty string for other segments

Type:

str

Note

Some attributes can be None when the segment info came from sponsorblock.client.Client.search_segments(), since that endpoint returns fewer fields.

Warning

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

class sponsorblock.models.SegmentSearchResults(data: dict)

Bases: object

The results of a segment search

segment_count

The total number of segments matching the query

Type:

int

page

The page number of these results

Type:

int

segments

The segments on this page, at most 10

Type:

List[SegmentInfo]

Warning

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

class sponsorblock.models.ServerStatus(data: dict)

Bases: object

The status of the sponsorblock server

uptime

The uptime of the server in seconds

Type:

float

commit

The full SHA hash of the latest git commit of the server

Type:

str

db

The current database version

Type:

int

start_time

The unix time in milliseconds that the request was received

Type:

int

process_time

The delay in milliseconds between the database request being made and the response being received

Type:

int

redis_process_time

The delay in milliseconds between the redis request being made and the response being received

Type:

Optional[int]

load_average

The 5 and 15 minute load averages of the server

Type:

List[float]

status_requests

The number of status requests made in the last minute

Type:

int

hostname

The hostname of the server that answered the request

Type:

str

data

The raw response, useful for any extra fields the server might return

Type:

dict

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

class sponsorblock.models.UserStats(data: dict)

Bases: object

Stats for a user, gotten from the userStats API

user_id

The public 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’s segments

Type:

float

segment_count

The amount of segments created by the user

Type:

int

category_counts

A mapping of category name to the number of segments the user submitted in that category. Only available if fetch_category_stats was True

Type:

Optional[dict]

action_type_counts

A mapping of action type name to the number of segments the user submitted with that action type. Only available if fetch_action_type_stats was True

Type:

Optional[dict]

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.ConnectionException(message, original=None)

Bases: Exception

Raised when a connection to the server could not be established, for example when there is no internet connection or the server timed out.

The original requests exception is available as the original attribute.

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

See also

sponsorblock.client.Client.get_top_users

Should be used with the SortType

MINUTES_SAVED = 0
TOTAL_SUBMISSIONS = 2
VIEW_COUNT = 1
class sponsorblock.utils.UserFeature(value)

Bases: Enum

Features that can be granted to a user by a VIP.

See also

sponsorblock.client.Client.set_user_feature

Should be used with the UserFeature

CHAPTERS = 0
DEARROW_TITLE_SUBMITTER = 2
sponsorblock.utils.cache(**kwargs)

Custom cache implementation taken from https://stackoverflow.com/a/67555155/13123877.

Parameters:

  • ttl (timedelta, optional) – The time to live for the cache. Defaults to max time supported by the platform.

  • max_entries (int) – The maximum number of entries to store in the cache..

sponsorblock.utils.set_env_var(key: str, value: str)

Sets an environment variable to the given value.

Parameters:

  • key (str) – The key of the environment variable to set.

  • value (str) – The value of the environment variable to set.

Warning

Most of the time this shouldn’t be used manually, but it’s here in case you need to set the SPONSORBLOCK_USER_ID environment variable.