Quick Start

A quick start to using festivald and its JSON-RPC & REST APIs.

More JSON-RPC specific examples here, and more REST specific examples here.

Important things to know:

1. The main music library/database in festivald is called the Collection
2. The Collection is created by scanning the filesystem festivald is running on
3. Everything revolves around the Collection, you should create one before doing anything
4. In festivald, there are "objects" that appear often, see Common Objects for more info

Launch festivald

Start festivald with no options:

./festivald

festivald will use a default configuration and open up on http://localhost:18425.

To view this documentation locally after starting festivald, you can open it in a web browser:

http://localhost:18425

Or you can open the files locally with:

./festivald --docs

Create a Collection with the JSON-RPC method collection_new

This scans the default Music directory on festivald's filesystem and creates a Collection from it.

festival-cli collection_new

OR

curl http://localhost:18425 -d '{"jsonrpc":"2.0","id":0,"method":"collection_new","params":{"paths":null}}'

Download a random Artist with the REST endpoint /rand/artist

Opening this link in a web browser will cause festivald to collect, organize, and archive all the Album's of a random Artist, and send it over.

http://localhost:18425/rand/artist

View metadata about a specific Album with the JSON-RPC method map_album

This will retrieve the Album "Cigarette & Alcohol" by the Artist "LUCKY TAPES".

festival-cli map_album --artist "LUCKY TAPES" --album "Cigarette & Alcohol"

OR

curl http://localhost:18425 -d '{"jsonrpc":"2.0","id":0,"method":"map_album","params":{"artist":"LUCKY TAPES","album":"Cigarette & Alcohol"}}'

The response looks like:

{
  "jsonrpc": "2.0",
  "result": {
    "title": "Cigarette & Alcohol",
    "key": 752,
    "artist": 169,
    "release": "2016-07-06",
    "runtime": 2593,
    "song_count": 10,
    "songs": [
      7611,
      7616,
      7618,
      7619,
      7620,
      7621,
      7622,
      7623,
      7624,
      7626
    ],
    "discs": 0,
    "art": 1947006,
    "genre": null
  },
  "id": 0
}

Search for an Artist with the JSON-RPC method search_artist

This will look up all Artist's in the Collection, and return the one that is the most similar (lexicographically) to the input "lUcKee TaPeZ":

festival-cli search_artist --input "lUcKee TaPeZ" --kind top1

OR

curl http://localhost:18425 -d '{"jsonrpc":"2.0","id":0,"method":"search_artist","params":{"input":"lUcKee TaPeZ","kind":"top1"}}'

We found "LUCKY TAPES":

{
  "jsonrpc": "2.0",
  "result": {
    "artists": [
      {
        "name": "LUCKY TAPES",
        "key": 169,
        "runtime": 2593,
        "albums": [
          752
        ],
        "songs": [
          7611,
          7616,
          7618,
          7619,
          7620,
          7621,
          7622,
          7623,
          7624,
          7626
        ]
      }
    ]
  },
  "id": 0
}