⚠️ Unmaintained

Starting from 2024-02-15, festivald is no longer maintained.

See #89 for more info.

festivald

Festival daemon.

festivald is a music server that plays on the device it is running on, and is remotely controlled by clients.

It can also serve music resources such as song files, album art, and organized archives of whole artists.

The 3 main APIs festivald exposes:

• JSON-RPC 2.0 for state retrieval & control
• REST endpoints for serving large resources (audio, art, etc)
• Docs - festivald serves the very docs you are reading right now

The transport used is HTTP(s).

A public instance of festivald with Creative Commons licensed music is available at:

https://daemon.festival.pm

For full documentation, see: https://docs.festival.pm/daemon.

Clients

To interact with festivald, you need a client.

The reference JSON-RPC client is festival-cli.

General purpose HTTP clients like curl, wget or a web browser will also do.

The documentation will use festival-cli & curl on the default http://localhost:18425 for examples.

JSON-RPC

For the JSON-RPC API, anything that can transmit JSON over HTTP(s) can be a client, like curl:

# Toggle playback.
curl http://localhost:18425 -d '{"jsonrpc":"2.0","id":0,"method":"toggle"}'

The equivalent wget command:

wget -qO- http://localhost:18425 --post-data '{"jsonrpc":"2.0","id":0,"method":"toggle"}'

The equivalent festival-cli command:

festival-cli toggle

For a quick start on the JSON-RPC API, see JSON-RPC/Quick Start.

REST

For the REST API, you can use anything that can handle HTTP(s), like a web browser:

# Download this exact song.
http://localhost:18425/map/Artist Name/Artist Title/Song Title

The equivalent curl command:

curl -JO http://localhost:18425/map/Artist%20Name/Artist%20Title/Song%20Title

The equivalent wget command:

wget --content-disposition "http://localhost:18425/map/Artist Name/Artist Title/Song Title"

For a quick start on the REST API, see REST/Quick Start.

To disable the REST API, set the config option rest to false OR pass --disable-rest via command line on start up.

Documentation

festivald will also serve its own documentation.

To access it, start festivald and open the root link in a web browser:

http://localhost:18425

Or you can open the files locally with:

festivald --docs

To disable serving documentation, set the config option docs to false OR pass --disable-docs via command line on start up.