python-sponsorblock/README.md
Elara6331 7d14fef3f5
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
ci/woodpecker/pr/woodpecker Pipeline was successful
ci/woodpecker/pull_request_closed/woodpecker Pipeline was successful
docs: add ci badge
2024-04-25 19:56:55 -07:00

103 lines
3.9 KiB
Markdown

# Python Sponsorblock
[![status-badge](https://ci.elara.ws/api/badges/61/status.svg)](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).