These methods are the same as the key_* methods, but instead of key's, you can directly use:

strings to lookup Common Objects.

So instead of:

festival-cli key_artist --key 100

you can use:

festival-cli map_artist --artist 'カネコアヤノ'

If the input is invalid, a JSON-RPC error will be returned.


Inputs are case-sensitive and must be exactly correct.

If you have an Album called Hello World, none of these inputs will work:

  • Hello world
  • hello World
  • HELlo World
  • HelloWorld
  • H3ll0 W0rld

The input must be exactly Hello World.


When using map_album you must specify:

  • Artist name
  • Album title

and when using map_song you must specify:

  • Artist name
  • Album title
  • Song title

The reason these have to be specified is to prevent collisions.

If there's 2 Song's in your Collection called: Hello World, festivald cannot know which one you want.

Since Artist names are unique, and Album titles within Artist's are unique, they serve as an identifier.

Duplicate Song Names

An uncommon "bug" you may encounter when using:

  • Artist names
  • Album titles
  • Song titles

as the key for searching objects is that:

  1. if multiple Song's with the same name exist
  2. in the same Album
  3. by the same Artist

it is impossible to specify which one you want.

This may occur in Album's that have "interlude" tracks, which may be different, but have the same name, e.g:

Artist Name/
  ├─ Album Name/
      ├─ Song 1
      ├─ Interlude # <------------- same name
      ├─ Song 3.flac
      ├─ Interlude # <------------- same name
      ├─ Song 5.flac

The workaround is by using Song key's to retrieve these instead, as they are unique per file, regardless of metadata.