Operations

Background jobs

Two kinds of job run in the background.

Jobs you can trigger

Listed under Settings, then System, then Jobs, with what each does, when it runs next, and a run-now button. A job you start shows as in progress until it finishes. A run that ended badly is flagged on its row until the next one succeeds. Some jobs can be stopped part-way, and keep what they had already done. Only jobs relevant to your setup are shown.

Running the discovery sweep by hand checks every feed, including those not due yet. The other jobs do a normal pass, which still honours their own per-item cadence. Neither permanently shifts the schedule.

Maintenance jobs

These run on a fixed schedule and are not user-triggerable.

What the library scan shows you

The library scan is not a row in the table. It has its own page, under Settings, then Library, then Scan. It lists each library path with its audio files on disk and the ones Synthseek recognises. It also counts those it is still searching for, could not recognise, or stopped finding. A line below counts the files you ignored. Each row can scan its path on its own. A path that is turned off or cannot be reached is skipped, and the others are still scanned. The run button turns into a spinner while work is underway, and you can cancel a running scan. It ticks every 30 minutes and walks every library path twice a day. On the ticks in between, it identifies a batch of unrecognised files. A scan that could not read part of the disk says so and leaves everything under those paths as it was. A permissions problem on one folder never looks like a library that lost files. A file that merely moved is followed to its new location, not counted as one loss and one arrival.

Review files opens what Synthseek could not recognise, grouped by folder and album. You can match a group to an album or a file to a song, search again, or ignore a file. Synthseek also searches again later on its own, so an album the catalog publishes after you got the files can still be found. Fixing a file’s tags makes it search again at the next scan. An ignored file stays on your disk and out of your library, and Synthseek stops searching for it until you choose Stop ignoring.

Duplicates have their own page under Settings, then Maintenance. It lists them a track at a time, ordered by what settling each one would give back. Copies it can prove are the same recording are settled without anyone pressing anything. It keeps the best file, preferring lossless and then the larger one, points your library at it, and sends the rest to the recycle bin. Proof means the copies agree on both their title and their length. A remix, a live take, a radio edit or a truncated download can carry the title of the track it was filed against while being a different recording. Copies within a couple of seconds of each other count as one length, because that is encoder rounding rather than a different take. What it cannot prove waits under Needs review. Each track there says how many clearly different lengths its copies come in. You can play any copy, then choose Keep this copy on the one you want, which recycles the others. Nothing is deleted outright. A call you disagree with is listed under Settings, then Maintenance, then Recycle bin. Its Restore puts the file back where it came from, for as long as the retention window keeps it.

The same page can also find the lyrics, artwork and metadata files left beside a track that is no longer there. It counts them and moves them to the recycle bin. It only judges a folder that still holds music, so a folder of booklet scans and a folder it could not read are both left alone.

How files are organised

Settings, then Library, then Paths & rules, administrators only.

Each library path has its own template, which decides the folders and filename every track in it gets. You edit it in that path’s settings. Its default is on the Configuration page.

Anything between < and > disappears when what it needs is missing. That is how the disc folder appears only for a release that has more than one. For example, {album}< ({year})> gives OK Computer (1997) where the year is known and OK Computer where it is not.

A token on its own is required. A track already on disk that cannot fill one is left alone. A download that cannot fill one fails to import, so every token you add is one that future downloads have to carry.

As you type, the page counts what that library path would do. The preview shows every change before you confirm. Confirming saves the format and moves the files in one go.

Reorganising what is already on disk

A library that predates a setting, or that another tool wrote into, can hold files whose place on disk no longer matches how Synthseek would file them. This page counts those and offers to move them. Nothing moves until you press.

The preview splits the work in three. Files that only change folder, files spelled differently, and files that land in a folder they are not in today. That last list is the one to read: it can be a move to another album or artist, or a folder the track never had.

Lyrics and artwork travel with the music they belong to. Where that would mean guessing, they stay, and the page says which case each one hit.

If your library changed between the preview and the press, nothing moves and the preview is worked out again. Anything that could not be moved is listed with its reason. On a read-only library path, every move fails. A file whose new place the index will not accept is put back where it was, or named as one a library scan has to reconcile if it cannot be.

Check what else manages the same folder before you start. Another library manager that scans it on its own schedule can read the moved files as deleted, and some of them then clean up what is left. Lidarr deletes permanently while its Recycle Bin setting is empty, in its own media management settings, which it may keep behind an advanced toggle. Give it a path first and anything it removes becomes something you can get back. That is worth doing whether or not you reorganise, since Synthseek moves a file out of your library in several other cases too.

Logs

Settings, then System, then Logs, administrators only.

• Live viewer with auto-refresh.
• Filter by level.
• Export to a file.
• Change the log level from the interface. It applies immediately, with no restart.

Logs are written to /data/logs, so they survive a container recreate and can be read from the host.

The credentials you enter in Settings are kept out of the logs, and a test asserts it on the paths that handle them.

Health

Two endpoints, both unauthenticated and safe to point a monitor at.

The compose health check uses the first one against the internal API port.

Inside the application, each integration shows a live status on its settings card, so you can tell a bad credential from a service that is simply down.

Startup

Boot aborts for genuine prerequisites, such as the database and its migration, a missing AUTH_SECRET, and the one-shot 1.x migration seed. A folder that is not usable, an unreachable music catalog and every integration let Synthseek start. It logs a warning, and admins see the problem and its fix under Settings, Maintenance, System status, which clears on its own once the problem is fixed.

When the downloads or music folder is not usable, the container log names the offending path and the ownership fix, and downloads wait until it is fixed.

A music library that is readable but not writable holds nothing back. Synthseek starts and says so, in the log and under System status. Browsing works, and imports into the library fail until it is writable.

Updates

Synthseek checks the public container registry for newer releases and shows a banner when one is available. The patch notes for it are in Settings, then Changelog, as a timeline you can read without leaving the application.

To update, pull the new image and recreate the container:

docker compose pull
docker compose up -d

What happens on an upgrade

Where there is room, the container proves the migration on a copy before touching your live database.

1. Pending schema changes are detected.
2. A snapshot of your database is written to /data/backups.
3. If there is room and the database sits in its default location, the migration is applied to a copy, not to your database.
4. The migrated copy is validated.
5. Only if validation passes is the copy swapped into place.
6. If anything fails during a copy-validated upgrade, your live database is untouched, the snapshot is kept, and the failed copy is kept for inspection.

The last ten snapshots are retained. Every migration run is logged to /data/logs/migrate.log.

If there is not enough free space for a copy, or your database lives outside its default location, Synthseek migrates in place. It tells you so, and the snapshot is already taken.

Backups

Everything Synthseek knows lives under /data. Back up that volume and you can restore the instance completely.

Your music files live in your library paths, /music and any you added, and are not Synthseek’s to back up. Synthseek removes a file from them only in these cases, and never by deleting it:

• Replacing a copy with a better one after a quality upgrade.
• Keeping one copy you picked on the duplicates page.
• Resolving one track with Keep best copy.
• Resolving every track under Safe to resolve at once.
• The scan settling the copies it proved are the same recording.
• Clearing the leftover files described above.
• Delete files on the Library page.

Each one moves the file to the recycle bin under /data, where it stays until the retention sweep clears it.

Take your own backup before a major version upgrade. The automatic snapshot covers schema migration failure; it is not a substitute for a backup you control.

Architecture support

Images are published for both amd64 and arm64. Each one is built natively and smoke tested on its own architecture before it is published.