festivald (by default) exposes REST endpoints for accessing the underlying resources associated with the Collection via HTTP GET requests.

A simple way to access these files is via a browser, e.g, opening this link:

http://localhost:18425/art/Artist Name/Album Title

This will make the art of the album Album Title, owned by the artist Artist Name open directly in the browser (or make it download the image, if the direct_download configuration setting is enabled).

Opening something like:

http://localhost:18425/map/Artist Name/Album Title/Song Title

will download that song directly. In the future, the behavior of showing an inline player in browsers may be added to the direct_download config option.

If a file downloaded has a nested filename, the filename_separator config option will control what the separator will be. By default, this is -, so the filename of an archive of an Artist will look like:

Artist Name - Album


The REST endpoint resources are in loosely grouped based on what type of data they are and what format they are outputted as.

These "groups" are referenced in authorization & API Stability.

REST resourceFile Format TypeDescriptionExample EndpointFilename Formatting
collectionzipThe whole Collection/collectionCollection - ${CREATION_UNIX_TIMESTAMP}.zip
playlistzipIndividual Playlist's/playlistPlaylist - ${PLAYLIST_NAME}.zip
artistzipIndividual Artist's/map/artist${ARTIST_NAME}.zip
albumzipIndividual Album's/current/album${ARTIST_NAME} - ${ALBUM_TITLE}.zip
songOriginal audio format (flac, mp3, etc)Individual Song's/rand/song${ARTIST_NAME} - ${ALBUM_TITLE} - ${SONG_TITLE}.${AUDIO_FORMAT}
artOriginal image format (png, jpg, etc)Individual Album art/current/art${ARTIST_NAME} - ${ALBUM_TITLE}.${IMAGE_FORMAT}

Missing Resource

If the underlying file for a resource is missing from the filesystem, festivald will respond to REST requests with an HTTP error.

For example, if an Artist is requested:


And any underlying PATH is missing/moved/renamed from when the Collection was created:

mv "Song Title" "Song_Title"

festivald will now have a reference to a non-existent PATH and will not be able to find the file(s), so it will respond with something along the lines of:

Song file error: ${ARTIST_NAME} - ${ALBUM_TITLE} - Song Title.flac

You can re-create the Collection with collection_new to re-link these PATHs.

Disk Cache

festivald exclusively uses the Disk when operating with potentially heavy data.

All heavy files are streamed from disk, so none of them take up full space in physical memory.

Practically, what this means is that when serving files, festivald can get by with very little memory, although the Cache folder may get quite heavy.

The cache behavior can be configured in the config or via command-line options.