103 lines
3.9 KiB
Markdown
103 lines
3.9 KiB
Markdown
# Python Sponsorblock
|
|
|
|
[](https://ci.elara.ws/repos/61)
|
|
|
|
<img src="https://gitea.elara.ws/music-kraken/python-sponsorblock/raw/branch/main/assets/logo.svg" width=300 alt="python-sponsorblock logo"/>
|
|
|
|
This is a wrapper for the sponsorblock api, enabling you to get the timestamps of sponsor segments from Youtube videos.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# using this gitea repository (recommended)
|
|
pip install --index-url https://gitea.elara.ws/api/packages/music-kraken/pypi/simple/ python-sponsorblock
|
|
```
|
|
|
|
```bash
|
|
# using pip
|
|
pip install python-sponsorblock
|
|
```
|
|
|
|
## Why does this exist?
|
|
|
|
I decided against using the already existing [sponsorblock.py](https://github.com/wasi-master/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](https://github.com/wasi-master/sponsorblock.py) project, it is just a different approach.** My other "_issue_" with the [sponsorblock.py](https://github.com/wasi-master/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.
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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:
|
|
|
|
- [x] 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](https://wiki.sponsor.ajay.app/w/API_Docs).
|
|
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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.
|
|
|
|
```python
|
|
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](https://wiki.sponsor.ajay.app/w/Types).
|