Config

festivald reads and loads its configuration file festivald.toml on startup.

It controls various behaviors of festivald.

Exactly where this file is depends on the OS, more details in the Disk section.

Command Line flags will override any overlapping config values.

festivald.toml

This is the default configuration file festivald creates and uses.

If festivald is started with no --flags, e.g:

./festivald

Then it will be equivalent to this config file.

#================#
# festivald.toml #
#================================================================#
# This is `festivald`'s config file.                             #
# It is in the TOML (https://en.wikipedia.org/wiki/TOML) format. #
#                                                                #
# Values will be loaded from this file on startup.               #
# If overlapping `--command-flags` are provided,                 #
# they will be used instead.                                     #
#                                                                #
# For full documentation on config options, see:                 #
# <https://docs.festival.pm/daemon/config.html>                  #
#================================================================#


#----------------------------------------------------------#
#                         NETWORK                          #
#----------------------------------------------------------#
# The IPv4 address `festivald` will bind to.
#
# DEFAULT | "127.0.0.1"
# EXAMPLE | "192.168.2.10", "0.0.0.0"
# TYPE    | IPv4 string
ip = "127.0.0.1"

# The port `festivald` bind to.
#
# Using port 0 will select a random port.
#
# DEFAULT | 18425
# EXAMPLE | 15000, 8080, 9999
# TYPE    | 16-bit unsigned integer (0..65535)
port = 18425

# The max amount of connections `festivald`
# will serve at any given moment.
# `0` means unlimited.
#
# Note that 1 client doesn't necessarily mean
# 1 connection. A single web browser client for
# example can make many multiple connections
# to `festivald`.
#
# DEFAULT | 0
# EXAMPLE | 2, 4, 8, 16, 32, 64, 1000, 99999
# TYPE    | unsigned integer
max_connections = 0

# `festivald` will only serve connections coming
# from these IPs. An empty array `[]` or an array
# containing "0.0.0.0" will serve all IP ranges.
#
# DEFAULT | []
# EXAMPLE | ["127.0.0.1", "192.168.2.10", "13.248.169.48"]
# TYPE    | array of IPv4 addresses
exclusive_ips = []

# Upon a failed, potentially malicious request, instead of
# immediately responding, `festivald` will randomly sleep
# up to this many milliseconds before responding to the connection.
#
# This includes:
#   - Authentication failure
#   - IPs not in the `exclusive_ips` list
#   - IPv6 connections
#
# If 0, `festivald` will immediately respond. This may
# not be wanted due to potential DoS and timing attacks.
#
# If you're hosting locally (127.0.0.1), you can set this
# to 0 (unless you don't trust your local network?).
#
# DEFAULT | 3000
# EXAMPLE | 0, 1000, 3000, 10000, 300000
# TYPE    | unsigned integer
sleep_on_fail = 3000


#----------------------------------------------------------#
#                       COLLECTION                         #
#----------------------------------------------------------#
# Upon a `collection_new` JSON-RPC method call, if the
# `paths` parameter is empty, these PATHs will be scanned
# instead.
#
# If this is also empty, the default OS `Music`
# directory will be scanned.
#
# Windows-style PATHs will only work if `festivald`
# is running on Windows (`C:\\Users\\User\\Music`)
#
# DEFAULT | []
# EXAMPLE | ["/home/user/Music/albums", "/home/user/data/songs"]
# TYPE    | array of PATHs
collection_paths = []


#----------------------------------------------------------#
#                           TLS                            #
#----------------------------------------------------------#
# Enable/disable HTTPS.
#
# You must also provide a PEM-formatted X509 certificate and key
# in the below options for this to work.
#
# DEFAULT | false
# VALUES  | true, false
# TYPE    | boolean
tls = false

# The PEM-formatted X509 certificate used for TLS.
#
# DEFAULT | ""
# EXAMPLE | "/my/path/to/cert.pem"
# TYPE    | PATH string
certificate = ""

# The PEM-formatted key for the above X509 certificate.
#
# DEFAULT | ""
# EXAMPLE | "/my/path/to/key.pem"
# TYPE    | PATH string
key = ""


#----------------------------------------------------------#
#                           API                            #
#----------------------------------------------------------#
# Enable/disable the REST API.
# This is responsible for the `/rest` API that
# serves image, audio, and other heavy resource data.
#
# Setting this to `false` will disable this part
# of the system, and will only leave the JSON-RPC
# API available.
#
# DEFAULT | true
# VALUES  | true, false
# TYPE    | boolean
rest = true

# Enable/disable serving documentation.
#
# By default, `festivald` serves a markdown book
# of it's own documentation, accessible at the
# root `/` endpoint, e.g:
# ```
# http://localhost:18425/
# ```
#
# Setting this to `false` will disable that.
#
# DEFAULT | true
# VALUES  | true, false
# TYPE    | boolean
docs = true

# Enable/disable inlined resources for the REST API.
#
# By default, accessing the REST API via a
# browser will open the resource inlined within
# the browser, if possible.
#
# Setting this to true will make browsers download
# the file directly, instead of opening it.
#
# Currently this only supports art, although in
# the future it will most likely support song files
# opening up as inline mini-players in the browser.
#
# DEFAULT | false
# VALUES  | true, false
# TYPE    | boolean
direct_download = false

# When files are downloaded via the REST API, and the
# file is a nested object referencing multiple things
# (e.g, an _album_ owned by an _artist_), we must include
# that information, but what string should separate them?
#
# The default separator is " - ", e.g:
# ```
# Artist Name - Album Title.zip
# ```
# it can be changed to any string, like "/":
# ```
# Artist Name/Album Title.zip
# ```
# or left empty "" for no separator at all.
#
# This cannot include a slash: `/`
# as that is the legal PATH separator in ZIP files.
#
# DEFAULT | " - "
# EXAMPLE | " --- ", "_", ""
# TYPE    | string
filename_separator = " - "


#----------------------------------------------------------#
#                         LOGGING                          #
#----------------------------------------------------------#
# The logging level `festivald` will use.
#
# "error" will only show critical error messages,
# "warn" will in addition show warnings,
# "info" will in addition show info, etc, etc.
#
# DEFAULT | "error"
# VALUES  | "off", "error", "warn", "info", "debug", "trace"
# TYPE    | string, one of the above
log_level = "error"


#----------------------------------------------------------#
#                       FILESYSTEM                         #
#----------------------------------------------------------#
# Enable/disable watching the filesystem for signals
#
# Other than RPC calls, `festivald` can send signals
# to another local `festivald`, e.g:
# `./festivald --play`
#
# The way this is done is by creating a file
# in Festival's `signal` directory.
#
# `./festivald --FLAG` just creates a file in that directory,
# which an existing Festival will notice and do the appropriate task.
#
# Setting this to `false` will disable that part of the system so that
# filesystem signals won't work, e.g, `./festivald --play` will not work.
#
# DEFAULT | true
# VALUES  | true, false
# TYPE    | boolean
watch = true

# Enable/disable cleaning up cache
#
# When serving `ZIP` files via the REST API, `festivald`
# will first write them to disk, then serve those files
# instead of directly storing everything in memory,
# as to not get OOM-killed on more than a few requests.
#
# Setting this to `false` will make `festivald`
# never clean those files up, ever.
#
# This will make `cache_time` not do anything and will
# also prevent `festivald` from the usual startup/shutdown
# cache cleaning that it does.
#
# DEFAULT | true
# VALUES  | true, false
# TYPE    | boolean
cache_clean = true

# Set the REST API cache time limit
#
# This option sets the time limit on how many seconds
# `festivald` will hold onto this cache for.
#
# Once the time limit is up, `festivald` will remove the
# file. This cache is also reset on startup and shutdown.
#
# This does nothing if `cache_clean` is `false`.
#
# DEFAULT | 3600 (1 hour)
# EXAMPLE | 60 (1 minute), 600 (10 minutes), 1800 (30 minutes), 14400 (4 hours)
# TYPE    | unsigned integer
cache_time = 3600


#----------------------------------------------------------#
#                           AUDIO                          #
#----------------------------------------------------------#
# Enable/disable audio state restoration
#
# Upon startup, `festivald` will recover audio state
# (volume, exact position in song, queue, etc) if this
# setting is `true`.
#
# DEFAULT | true
# VALUES  | true, false
# TYPE    | boolean
restore_audio_state = true

# Reset threshold for the `previous` JSON-RPC method
#
# The `previous` method comes with an optional
# `threshold` parameter that specifies:
#
# ```
# If the current `Song` runtime (seconds) has passed this number,
# this method will reset the current `Song` instead of skipping backwards.
# Setting this to `0` will make this method always go to the previous `Song`.
# ```
#
# But if that parameter is `null`, this option
# will be used instead. The default if not
# specified here is 3 seconds.
#
# For example:
#   - A song is 3+ seconds in
#   - A `previous` method was received
#   - It will reset the current song instead of going back
#
# Setting this to `0` will make `previous`
# always go back if `threshold` is not specified.
#
# DEFAULT | 3
# VALUES  | 0, 3, 5, 100
# TYPE    | unsigned integer
previous_threshold = 3

# Enable/disable OS media controls
#
# `festivald` plugs into the native OS's media controls so that signals
# like `play/pause/stop` and/or keyboard controls can be processed.
#
# Setting this to `false` will disable media controls.
#
# DEFAULT | true
# VALUES  | true, false
# TYPE    | boolean
media_controls = true


#----------------------------------------------------------#
#                      AUTHORIZATION                       #
#----------------------------------------------------------#
# Only process connections to `festivald` that have a
# "authorization" HTTP header with this username and password.
#
# If either the `no_auth_rpc` or `no_auth_rest` options are
# used, then every RPC call/REST endpoint _NOT_ in those lists
# will require this authorization.
#
# TLS must be enabled for this feature to work
# or `festivald` will refuse to start.
#
# To set authorization EVEN IF TLS IS DISABLED,
# See `--confirm-no-tls-auth`.
#
# This value must be:
#   1. The "username"
#   2. Followed by a single colon ":"
#   3. Then the "password", e.g:
# ```
# curl -u my_user:my_pass https://127.0.0.1:18425
# ```
# or the equivalent wget command:
# ```
# wget --user my_user --password my_pass https://localhost:18425
# ```
#
# An empty string disables this feature.
#
# Alternatively, you can input an absolute PATH to a file
# `festivald` can access, containing the string, e.g:
# ```
# authorization = "/path/to/user_and_pass.txt"
# ```
# In this case, `festivald` will read the file and attempt
# to parse it with the same syntax, i.e, the file should contain:
# ```
# my_user:my_pass
# ```
#
# DEFAULT | "" (disabled)
# EXAMPLE | "my_username:my_password", "my_username:aoig2A%^$AWS^%", "/path/to/file"
# TYPE    | string or PATH to file
authorization = ""

# Allow authorization even without TLS
#
# This will let you set the authorization
# setting even if TLS is disabled.
#
# This means your `user:pass` will be sent in clear-text HTTP,
# unless you are wrapping HTTP in something else, like SSH
# port forwarding, or Tor.
#
# DEFAULT | false
# VALUES  | true, false
# TYPE    | boolean
confirm_no_tls_auth = false

# Allow specified JSON-RPC calls without authorization,
# while still requiring authorization for everything else.
#
# If a JSON-RPC method is listed in this array,
# `festivald` will allow any client to use it,
# regardless of authorization.
#
# This allows you to have `authorization` enabled
# across the board, but allow specific JSON-RPC
# calls for public usage.
#
# For example, if only `toggle` is listed, then
# clients WITHOUT authorization will only be
# allowed to use the `toggle` method, for every
# other method, they must authenticate.
#
# The method names listed here must match the
# exact names when using them, or shown in the
# documentation, see here:
#
# <https://docs.festival.pm/daemon/json-rpc/json-rpc.html>
#
# OR WITH
#
# ```
# festivald data --docs
# ```
# DEFAULT | [] (disabled)
# EXAMPLE | ["toggle", "state_audio", "volume"]
# TYPE    | string, must be a method name
no_auth_rpc = []

# Allow specified REST resources without authorization,
# while still requiring authorization for everything else.
#
# REST resources:
#   - `collection`
#   - `playlist`
#   - `artist`
#   - `album`
#   - `song`
#   - `art`
#
# If a REST resource is listed in this array,
# `festivald` will allow any client to use it,
# regardless of authorization.
#
# For example, if only `art` is listed, then
# clients WITHOUT authorization will only be
# allowed to use the `art` related endpoints
# (/rand/art, /current/art, etc). For every
# other endpoint (/rand/song, /collection, etc),
# they must authenticate.
#
# DEFAULT | [] (disabled)
# EXAMPLE | ["art", "song", "album"]
# TYPE    | string, must be a REST resource
no_auth_rest = []

# Allow documentation to be served without authorization,
# while still requiring authorization for everything else.
#
# DEFAULT | false
# VALUES  | true, false
# TYPE    | boolean
no_auth_docs = false