mirror of https://github.com/owntone/owntone-server.git synced 2024-12-25 14:45:55 -05:00

ejurgensen 7da811e3b3 [docs] Brush up the documentation

* Try to organize after expected user need
* Update mkdocs stuff and fix a broken link
* Move web building info to building.md
* Add info about Roku Soundbridge
* Add note about Google Nest not working

2024-10-11 19:29:49 +02:00

31 KiB

Raw Permalink Blame History

Configuration

The configuration of OwnTone - usually located in /etc/owntone.conf - is split into multiple sections:

general - Main settings of OwnTone.
library - Settings of local library.
audio - Settings for the local audio.
alsa - Settings for ALSA devices.
fifo - Settings for named pipe.
airplay_shared - Settings shared across AirPlay devices.
airplay - Settings for a specific AirPlay device.
chromecast - Settings for a specific Chromecast device.
spotify - Settings for the Spotify playback.
rcp - Settings for RCP / Roku Soundbridge devices.
mpd - Settings for MPD clients.
sqlite - Settings for SQLite operation.
streaming - Settings for the streaming.

Format

Each section consists of a name enclosing settings within parentheses.

Each setting consists of a name and a value. There are different types of settings: string, integer, boolean, and list.

Comments are preceded by a hash sign.

The format is as follow:

# Section
section {
    # String value
    setting = "<string-value>"
    # Integer value
    setting = <integer-value>
    # Boolean
    setting = <true|false>
    # List
    setting = { "value a", "value b", "value n"}
}

Note: For a regular use, the most important settings are:

the directories (see library section), which should be the location of your media, and
the uid (see general section), which must have read access to those directories.

General Settings

general {
  …
}

The general section accepts the settings below.

uid

Identifier of the user running OwnTone.

Notes:

Make sure that this user has read access to the directories (library section) section and write access to the database (db_path), log file (logfile) and local audio (audio section).
This setting is mandatory.

Default: "nobody"

uid = "<user-identifier>"

db_path

Full path to the database file.

Note: This setting is mandatory.

Default: "/var/cache/owntone/songs3.db"

db_path = "<path-to-database-file>"

db_backup_path

Full path to the database file backup.

Note: Backups are triggered from an API endpoint.

Default: unset

db_backup_path = "<path-to-database-backup-file>"

logfile

Full path to the log file.

Default: "/var/log/owntone.log"

logfile = "<path-to-log-file>"

loglevel

Level of verbosity of the logging.

Note: There are 6 levels of verbosity (hereunder from the less verbose to the most verbose). The level log is recommended for regular usage.

Valid values: fatal, log, warning, info, debug, spam

Default: "log"

loglevel = "<fatal|log|warning|info|debug|spam>"

admin_password

Password for the web interface.

Note: If a user is accessing the web interface from a device located in one of the trusted_networks, no password is required.

Default: unset

admin_password = "<password>"

websocket_port

Port number used to answer requests from the web interface.

Default: 3688

websocket_port = <port-number>

websocket_interface

Network interface on which the web socket is listening: e.g., eth0, en0.

Note: When this setting is unset, it means that the web socket listens on all available interfaces.

Default: unset

websocket_interface = "<interface>"

trusted_networks

List of networks considered safe to access OwnTone without authorisation (see also admin_password).

Note: This applies to these client types: remotes, DAAP clients (e.g., Apple Music, iTunes) and the web interface.

Valid values: any, localhost, or the prefix to one or more IP networks.

Default: { "localhost", "192.168", "fd" }

trusted_networks = { <"any"|"localhost"|"ip-range-prefix">, <...> }

ipv6

Flag to indicate whether or not IPv6 must used.

Default: true

ipv6 = <true|false>

bind_address

Specific IP address to which the server is bound.

Note: It can be an IPv4 or IPv6 address and by default the server listens on all IP addresses.

Default: unset

bind_address = "<ip-address>"

cache_path

Full path to the cache database file.

Default: unset

cache_path = "<path-to-database-cache-file>"

cache_daap_threshold

Threshold in milliseconds for DAAP requests.

Note: Set to 0 to disable caching.

Default: 1000

cache_daap_threshold = <threshold>

speaker_autoselect

Flag to automatically select the speaker when starting the playback if none of the previously selected speakers / outputs are available.

Default: false

speaker_autoselect = <true|false>

high_resolution_clock

Flag to indicate whether or not the high-resolution clock must be set.

Note: Most modern operating systems have a high-resolution clock, but if OwnTone is running on an unusual platform and drop-outs are experienced, this setting set to true.

Default: false on FreeBSD-based operating systems, true otherwise

high_resolution_clock = <true|false>

Library Settings

library {
  …
}

The library section accepts the settings below.

name

Name of the library as displayed by the clients.

Notes:

If you change the name after pairing with Remote you may have to redo the pairing.
The place holder %h can be used to display the hostname.

Default: "My Music on %h"

name = "<library-name>"

port

TCP port to listen on.

Default: 3689

port = 3689

password

Password for the library.

Default: unset

password = "<password>"

directories

Path to the directories containing the media to index.

Default: unset

directories = { "<path-to-media>", "<...>" }

follow_symlinks

Flag to indicate whether or not symbolic links must be followed.

Default: true.

follow_symlinks = <true|false>

podcasts

List of directories containing podcasts.

Note: For each directory that is indexed, the path is matched against these names. If there is a match, all items in the directory are marked as podcasts. If you index /srv/music, and your podcasts are in /srv/music/Podcasts, then you can set this to { "/Podcasts" }. Changing this setting only takes effect after a rescan.

Default: unset

podcasts = { "<podcast-directory>", "<...>" }

audiobooks

List of directories containing audiobooks.

Note: For each directory that is indexed, the path is matched against these names. If there is a match, all items in the directory are marked as audiobooks. If you index /srv/music, and your podcasts are in /srv/music/Audiobooks, then you can set this to { "/Audiobooks" }.Changing this setting only takes effect after a rescan.

Default: unset

audiobooks = { "/Audiobooks" }

compilations

List of directories containing compilations: e.g., greatest hits, best of, soundtracks.

Note: For each directory that is indexed, the path is matched against these names. If there is a match, all items in the directory are marked as compilations.Changing this setting only takes effect after a rescan.

Default: unset

compilations = { "/Compilations" }

compilation_artist

Artist name of compilation albums.

Note: Compilations usually have multiple artists, and sometimes may have no album artist. If you don't want every artist to be listed, you can set a single name which will be used for all compilation tracks without an album artist, and for all tracks in the compilation directories. Changing this setting only takes effect after a rescan.

Default: unset

compilation_artist = "<various-artists>"

hide_singles

Flag to indicate whether or not single albums must be hidden.

Note: If your album and artist lists are cluttered, you can choose to hide albums and artists with only one track. The tracks will still be visible in other lists, e.g., tracks and playlists. This setting currently only works with some remotes.

Default: false

hide_singles = <true|false>

radio_playlists

Flag to show internet streams in normal playlists.

Note: By default the internet streams are shown in the "Radio" library, like iTunes does. However, some clients (like TunesRemote+) won't show the "Radio" library.

Default: false

radio_playlists = <true|false>