Skip to content

Latest commit

 

History

History
103 lines (76 loc) · 2.74 KB

README.md

File metadata and controls

103 lines (76 loc) · 2.74 KB
Raw

beets-webm3u

A beets plugin to serve M3U playlists via HTTP.

Features

  • Allows to access M3U playlists (generated by the smartplaylist plugin) 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

python3 -m pip install beets-webm3u

Configuration

Enable the plugin and add a webm3u section to your beets config.yaml as follows:

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:

beet webm3u

You can browse the server at http://localhost:8339.

To serve multiple beets web APIs using a single process, you can use the webrouter plugin.

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:

{
	"directories": [{"name":"some-dir"}],
	"files": [{"name":"afrobeat", "path":"afrobeat.m3u"}],
}

Development

The following assumes you have docker installed.

Run the unit tests (containerized):

make test

Run the e2e tests (containerized):

make test-e2e

To test your plugin changes manually, you can run a shell within a beets docker container as follows:

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:

make beets-webm3u