Aether

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installation#

Every release ships:

Download	For
`aether_<version>_linux_amd64_v1.deb`, `…_amd64_v3.deb`, `…_linux_arm64.deb`	Debian, Ubuntu and derivatives
`ghcr.io/andresbott/aether`	Docker / Podman, amd64 and arm64
`aether_Linux_.zip`, `aether_Windows_.zip`, `aether_Darwin_*.zip`	the plain binary, any other system
`aether-spa.zip`	the web UI on its own (rarely needed, see below)

v1 or v3? The amd64 builds come in two flavours. v3 is a little faster and needs a CPU from 2013 (Intel Haswell) or 2017 (AMD Zen) onwards; v1 runs on any 64-bit x86 CPU. A v3 build on an older CPU exits immediately with an “illegal instruction” error — pick v1 when unsure.

Libraries

Mon, 01 Jan 0001 00:00:00 +0000

Libraries#

A library is what you browse: a named, saved filter over everything that was scanned — not a directory. The same album can sit in several libraries, and deleting a library never deletes music. Subsonic apps see each library as a music folder.

Create one under Settings → Libraries → Add library. Besides a name and an icon, a library sets:

which views it offers — Discover, Artists, Albums — and the one it opens on;
whether the sidebar gives it one entry or one per view;
whether its artists are hidden from the main Artists page;
up to 20 filters.

The library dialog: views, sidebar entries and filters, with the live match count

Filters#

Filter	Matches tracks…
Scan folder	indexed under one of the chosen scan folders
Folder path	stored under one of the chosen directories
File format	with one of the chosen extensions (`flac`, `mp3`, …)
Release type	on an album of one of the chosen types; “(none)” means untyped albums
Compilation	on a compilation album (Yes) or on any other album (No)
Genre	tagged with one of the chosen genres

A track must pass every filter; within one filter, any of its values is enough. A library without filters is the whole catalog. While you edit, the dialog shows how many tracks and albums the filters match.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

Aether reads one YAML file. Every option is annotated in the packaged config; this page covers the ones you will touch.

Where the config comes from#

aether start -c /path/to/config.yaml uses that file. The path must exist — a typo is an error, not a silent fallback.
Without -c, Aether tries ./config.yaml, then /etc/aether/config.yaml, and uses the first one that exists. With neither, built-in defaults apply.
Environment variables override the file: AETHER_ plus the key path in capitals, e.g. AETHER_SERVER_PORT=8080 or AETHER_AUTH_METHOD=native. Lists such as ScanFolders can only be set in the file.
Secrets can live in their own file: a value starting with @ is read from that path, e.g. FanartApiKey: "@/etc/aether/fanart.api.key".

Restart the server after changing the config.

Connecting apps

Mon, 01 Jan 0001 00:00:00 +0000

Connecting apps#

Aether speaks the OpenSubsonic API, so any Subsonic or OpenSubsonic app can use it — Symfonium, DSub, play:Sub and many more. In the app, enter your server’s address, e.g. https://music.example.com or http://192.168.1.10:8075, and the credentials below.

Credentials#

With authentication off (Auth.Method: none), the API asks for nothing: any username and password work.

With authentication on, your own password never works in an app. Each app gets its own credentials instead, so you can revoke one without touching the others. Open User settings → Connected apps from your account menu:

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Authentication#

Auth.Method in the config picks one of three modes:

Method	Who signs you in
`none`	nobody — no users, no login. Trusted networks only. The default.
`native`	Aether: users live in its database and it shows its own login page
`proxy-header`	your reverse proxy (Authelia, Authentik, oauth2-proxy), which passes the user on in headers

In both authenticated modes, users are either admins or regular users. Admins get Settings — libraries, tasks, users — and the metadata editor; everyone gets their own playlists, stars, play queue and history. Apps never use the login password, see Connecting apps.

Pre-release status

Mon, 01 Jan 0001 00:00:00 +0000

Pre-release status#

Aether has no stable release yet. Until it does, any new version may change the configuration file or the database, with no migration from what an older version left behind:

Configuration. Options can be renamed, moved or removed. After an upgrade, compare your config with the packaged config of the new version.
Database. A new version may not work with an older version’s database. The way out is an empty data directory and a fresh scan.

Your files are the source of truth#

Aether is built so that losing its database costs you a rescan, not your collection. What it knows about your music comes from the files — tags, embedded and folder covers — and the metadata editor writes its changes back into them. A scan reads all of it again.