REST
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 Title.zip
Resource
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 resource | File Format Type | Description | Example Endpoint | Filename Formatting |
|---|---|---|---|---|
collection | zip | The whole Collection | /collection | Collection - ${CREATION_UNIX_TIMESTAMP}.zip |
playlist | zip | Individual Playlist's | /playlist | Playlist - ${PLAYLIST_NAME}.zip |
artist | zip | Individual Artist's | /map/artist | ${ARTIST_NAME}.zip |
album | zip | Individual Album's | /current/album | ${ARTIST_NAME} - ${ALBUM_TITLE}.zip |
song | Original audio format (flac, mp3, etc) | Individual Song's | /rand/song | ${ARTIST_NAME} - ${ALBUM_TITLE} - ${SONG_TITLE}.${AUDIO_FORMAT} |
art | Original 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:
http://localhost:18425/map/Artist
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.