Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mgoltzsche/beets-webm3u
A Beets plugin to serve M3U playlists via HTTP
https://github.com/mgoltzsche/beets-webm3u
beets beets-plugin m3u m3u-playlist m3u8 m3u8-playlist python web webm3u
Last synced: about 2 months ago
JSON representation
A Beets plugin to serve M3U playlists via HTTP
- Host: GitHub
- URL: https://github.com/mgoltzsche/beets-webm3u
- Owner: mgoltzsche
- License: mit
- Created: 2024-02-19T02:06:39.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2024-05-18T16:59:43.000Z (8 months ago)
- Last Synced: 2024-09-19T17:17:52.821Z (4 months ago)
- Topics: beets, beets-plugin, m3u, m3u-playlist, m3u8, m3u8-playlist, python, web, webm3u
- Language: Python
- Homepage:
- Size: 68.4 KB
- Stars: 1
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# beets-webm3u
A [beets](https://github.com/beetbox/beets) plugin to serve M3U playlists via HTTP.
## Features
* Allows to access M3U playlists (generated by the [smartplaylist plugin](https://beets.readthedocs.io/en/stable/plugins/smartplaylist.html)) via HTTP.
* Rewrites playlist item URIs to be accessible via HTTP, allowing to maintain a single set of playlists with local paths instead of having to generate each playlist with multiple URI formats (one per client/integration) upfront.
## Installation
```sh
python3 -m pip install beets-webm3u
```
## Configuration
Enable the plugin and add a `webm3u` section to your beets `config.yaml` as follows:
```yaml
plugins:
- webm3u
webm3u:
host: '127.0.0.1'
port: 8339
cors: ''
cors_supports_credentials: false
reverse_proxy: false
include_paths: false
# Can be omitted when smartplaylist plugin is configured:
playlist_dir: /data/playlists
```
## Usage
Once the `webm3u` plugin is enabled within your beets configuration, you can run it as follows:
```sh
beet webm3u
```
You can browse the server at [`http://localhost:8339`](http://localhost:8339).
To serve multiple beets web APIs using a single process, you can use the [webrouter plugin](https://github.com/mgoltzsche/beets-webrouter).
### CLI
```
Usage: beet webm3u [options]
Options:
-h, --help show this help message and exit
-d, --debug debug mode
```
## Web API
The following endpoints allow listing and downloading playlist as well as audio files:
* `GET /playlists/index.m3u[?uri-format=$url]`: Returns the playlist of playlists.
* `GET /playlists/`: List available playlists.
* `GET /playlists/*.m3u[?uri-format=$url]`: Get/download a playlist.
* `GET /audio/`: List available audio files.
* `GET /audio/*.opus`: Download/stream an audio file.
The `uri-format` parameter allows specifying a playlist item URI template.
Item field names prefixed with a `$` can be used as placeholders, e.g. `beets:library:track;$id` or `subidy:song:3$id`.
`$url` is a built-in placeholder and the default value.
The list endpoints return either a JSON or HTML response, supporting content type negotiation.
A JSON response body looks as follows:
```json
{
"directories": [{"name":"some-dir"}],
"files": [{"name":"afrobeat", "path":"afrobeat.m3u"}],
}
```
## Development
The following assumes you have [docker](https://docs.docker.com/engine/install/) installed.
Run the unit tests (containerized):
```sh
make test
```
Run the e2e tests (containerized):
```sh
make test-e2e
```
To test your plugin changes manually, you can run a shell within a beets docker container as follows:
```sh
make beets-sh
```
A temporary beets library is written to `./data`.
It can be removed by calling `make clean-data`.
To just start the server, run:
```sh
make beets-webm3u
```