The Download Engine

Overview

This page explains what happens between pressing request and the file appearing in your library. You do not need to read it to use Synthseek, but it is what you want when something did not work and you need to know why.

The engine is source-agnostic. It owns the phases and their timing, and each download source is an adapter it drives. Adding a source does not change the pipeline.

The phases

A request moves through a fixed sequence. The status you see on the requests screen is the phase it is currently in. The code is what assistants and the logs use.

Step 1, search

For each track, the engine tries the enabled download sources in priority order, or in the order chosen for that request, until one delivers.

Search is not a single query. Files on other people’s machines are rarely named the way a catalog names them, so each track is searched several ways rather than once. How many variations it tries is a setting.

Concurrency is bounded, and how many searches run at once is a setting too.

Step 2, scoring

Every candidate returned is scored and ranked. The best one is taken, not the first one that looks acceptable.

Much of what feeds that ranking is yours to set. That is the format and bitrate you asked for, how strictly you meant them, a minimum upload speed, and whether a peer needs a free slot. Sources and peers you have quarantined or banned are excluded outright.

When a candidate is discarded, the engine records why, so you can see what was rejected and on what grounds.

Step 3, download

The chosen candidate is downloaded through the source adapter.

Several timeouts guard this phase, all configurable:

• A ceiling on the download itself.
• A window after which a peer that has not started transferring is considered unresponsive.
• Separate queue-wait budgets depending on whether the peer is actively transferring to someone else or simply idle.
• A short window after which a transfer that never materialises fails fast rather than holding a slot.

A Usenet or torrent album is fetched before this phase, under that source’s own limits, and other downloads carry on while it is.

If a source cannot deliver, the engine moves to the next source in the chain. A failure caused by your own machine rather than the source short-circuits this, because another peer cannot fix a full disk.

Step 4, verification

Before anything reaches your library, Synthseek checks that what arrived is what you asked for. Some checks read the file’s own tags and compare them against your request. One listens to the audio itself.

Not every failure means the same thing. Some simply stop the import. Others are treated as evidence that the source sent the wrong thing. Those put the file in the review queue and set that source and file pairing aside, so a retry looks elsewhere.

What you control

Metadata confidence threshold. How closely a file’s tags must match your request before it is accepted. Raise it to reject more, lower it to accept more. A retry of a previously rejected import is judged more leniently, on the reasoning that you asked for the retry deliberately.

AcoustID identity gate. Whether the audio is fingerprinted and identified before import. This is what catches a file whose tags look right but whose audio is by a different artist. It needs a free AcoustID key, and without one it does not run and only the tag checks apply. It is the single most valuable optional key you can configure.

What identification can and cannot tell you

Fingerprinting guards against a recording by a different artist arriving. It is not a guarantee that the track is the right one by that artist, nor that every detail is the exact version you had in mind.

An inconclusive identification does not block the import. AcoustID’s database is far from complete: obscure tracks, live recordings, regional music, and anything never released commercially routinely come back with nothing at all. Treating silence as guilt would fill the review queue with legitimate files and make it useless. The file still has to satisfy the tag checks.

What reaches the review queue

A file lands there when something positively contradicted your request. That means tags that do not match, audio that identifies as another artist, or tags that cannot be read at all. A file that merely could not be identified does not.

For each held file you can see why it was rejected, listen to it, and then approve or discard it.

Step 5, tagging and import

Synthseek tags each verified file and files it into your library. It identifies the track by its audio where it can, falls back to the metadata the catalog gave it where it cannot, so a file is never left untagged. A file whose own tags the writer would damage keeps them as they are.

A track Synthseek still knows the whereabouts of is reported as a duplicate, and only a quality upgrade replaces it. A file Synthseek never filed, or has since lost track of, is not recognised and a second copy is filed.

Cover art from the catalog is embedded into the file, and each track is written with its correct position within its album. That last detail matters more than it sounds: it is what stops a media server’s own metadata agent from rebinding a single downloaded file to the wrong song.

Identifying a track against MusicBrainz happens during the import when the audio can be fingerprinted, and in the background for tracks that carry an ISRC. When it succeeds, Synthseek writes the recording id into the file where it safely can, so the identity travels with your music. A file that already names a recording is left alone.

Imports are strictly serialised. One import runs at a time.

Step 6, media servers

After a successful import, Plex is asked to rescan the affected part of the library. Navidrome and Jellyfin are not asked, so the new file appears there after their own next scan.

If the track belongs to a playlist, that playlist is reconciled on every media server with playlist sync on. Reconciliation is incremental: as more tracks of a playlist finish over time, they are added to the remote playlist as they arrive rather than waiting for the whole set.

Reconciliation only adds. Synthseek takes a track off the server’s copy only when a playlist kept in sync with its source loses it there.

When a track fails

Every failure carries a typed reason.

wrong_file being both quarantined and retryable is deliberate and is a single mechanism: the quarantine excludes the specific bad candidate, and the retry is what searches again without it.

An environment failure is only ever assigned from unambiguous evidence. That means specific filesystem error codes, a direct write test on the downloads folder, or a library path that cannot take the file. A disk error never overrides a verdict about what a peer actually sent. A track that had already downloaded is filed from that file on its retry, while the file is still there.

When tracks are waiting on a storage problem, the requests page says so at the top. It counts them and names the downloads folder, or the library paths those tracks would be filed in, when they cannot be used yet. While one is still missing or unwritable, the retry stays disabled, because retrying before you have fixed the storage only fails the same way. Once they all work the retry becomes available and covers the waiting tracks in one action, in batches if there are many, so running it again picks up the rest.

Rate and concurrency limits