Import lists

An import list is a source Wondarr reads again and again: a playlist, a CSV file, a scrobble history. Each item is resolved to a recording and added as a song. Set them up under Settings → Import lists; Add list starts the form, and each list has Sync now, Edit and Delete.

How an item is resolved

For each item Wondarr tries, in order: a MusicBrainz recording id, then an ISRC (MusicBrainz, then Deezer), then a text search on artist and title that also uses the item’s length. An item that matches a song already in the library is linked to it (“already in the library”). Anything Wondarr is not sure about goes to the Unresolved page, where you pick a candidate or skip it. See Adding songs.

A line of plain text with no artist and title (just Hallelujah) is never added on its own: it waits on the Unresolved page for you to pick. A line such as Jeff Buckley Hallelujah is added only when the best match is close to what was typed in both artist and title; a typo or two is fine, a different artist is not. An unresolved item whose text changes at the source (an ISRC added, a title corrected) is looked up again at the next sync.

Providers

Type	What it reads	Settings
CSV file (Exportify or any mapped CSV)	An uploaded file	Column names for a generic file
Deezer playlist	A public Deezer playlist	A playlist link or id
Artist top tracks (Deezer)	An artist’s top tracks	An artist name, link or id; how many (1 to 100, default 10)
YouTube Music playlist	A public or unlisted playlist	A YouTube Music or YouTube playlist link, or its id
Last.fm loved tracks	A user’s loved tracks	User name; API key (optional when Settings → General has one)
Last.fm top tracks	A user’s most played tracks	User name; API key (optional when Settings → General has one); period; how many (1 to 500, default 50)
ListenBrainz loved tracks	A user’s loved recordings	User name
ListenBrainz playlist	A public playlist	A listenbrainz.org playlist link, or its MBID
Reference library	The identified files of a reference library, in folder order	The reference library

CSV and Exportify

Choose CSV file and pick a file. Wondarr reads it in your browser and sends only its text, then shows a preview: the format, the number of rows and the first few rows.

• An Exportify export (a Spotify playlist exported with Exportify) is recognised by the spotify:track: URIs in its first column. Exportify writes its header row in your language, so Wondarr reads the base columns by position instead: a German or Japanese export imports as well as an English one. The title, artist, album, length and ISRC come from fixed columns.
• Any other CSV is Mapped CSV: name the columns by their header. Title column is required (or an ISRC or MusicBrainz id column). Artist column, Album column, Length column (milliseconds, seconds or m:ss) and ISRC column are optional, and MusicBrainz recording id column is under Advanced. An ISRC column is the most reliable way to match.

Choosing a new file on an existing list replaces the stored one.

Last.fm

You need a Last.fm API key, from last.fm/api/account/create. Put it in Settings → General → Metadata services (lastfm.api_key) and every Last.fm list uses it; a list with a key of its own uses that one instead. With neither, the list reports that it needs an API key. The top-tracks Period is one of overall, 7day, 1month, 3month, 6month or 12month (default 12month).

Sync interval

Sync every (hours) is 24 by default. It can be 0 to 720; 0 means only when I ask (Sync now). A scheduled Import List Sync task runs hourly and syncs the lists that are due. A failed read still counts as a sync for the schedule, so a source that is down is not hammered. A list is never synced twice at once: Sync now waits for a sync that is already running, and the scheduled task leaves a list that is being synced alone.

Policy

The Policy says what happens when an item leaves the source:

Policy	Label in the form	Effect
addOnly (default)	Add only	New items are added. Nothing is undone.
addAndUnmonitor	Add, and unmonitor songs that leave the list	Songs added by this list that leave it are unmonitored.
mirror	Mirror: also delete songs that leave the list and have no file	As above, but a song with no file (and nothing downloading) is deleted. A song that has a file is unmonitored instead.

A list never deletes a file. A song you added by hand, or one that another list still holds, is never touched.

A read that looks wrong

For addAndUnmonitor and mirror, Wondarr does not act on a read that cannot be trusted to be the whole list. The sync still adds new items, but marks nothing as gone and unmonitors and deletes nothing, when:

• the source answered with an error or something Wondarr could not read;
• the read stopped at a limit (10 000 items for Deezer, Last.fm and ListenBrainz; 100 pages for YouTube Music), or the source is longer than the 10 000 items Wondarr reads (removals are then never applied);
• a page came back empty before the end the source announced (for a Deezer playlist, a read that returns more than 5 tracks and 10 % fewer than Deezer’s own count; Deezer counts tracks it no longer serves, so a smaller gap is fine). This “short read” can be trusted with Trust the next read; a read cut at a limit cannot;
• it returned nothing for a list that had items;
• or it returned fewer than half the items of the last complete read, for a list of 20 items or more.

The list’s status says so (for example “Read returned 0 of 300 items; removals skipped”), and Health shows a warning naming the list. The warning goes away at the next complete read.

If you change the source of a list (its playlist, its user, its file) the “fewer than half” rule is switched off for the next read, because a smaller playlist is expected; an empty read of a list that still holds items stays suspect. If a source really was emptied, or really shrank, press Trust the next read next to the warning in Settings → Import lists (or POST /api/v1/importlist/{id}/trustnextread). The next read that is not cut at a limit then removes everything missing from it, whatever its size, and the button resets. Changing only an API key, or the order of the settings, does not count as changing the source.

Items that come back

When an item that left the source returns, Wondarr undoes what the list did. A song that mirror deleted is added again. A song that the policy unmonitored is monitored again, unless somebody monitored and unmonitored it since. A song you unmonitored stays unmonitored. A song you deleted yourself is added again too, if its item leaves the list and returns.

Songs wait for the reference scan

While a reference library still has files it has not identified, songs that a list adds are added but not searched for: you may already own them in files the scan has not reached. Health says “Import list songs wait for the reference scan of … to finish”. When the scan is done, the next hourly sync run starts a search for each of those songs, once. A file that was deferred (for example because AcoustID was unavailable) does not hold anything back. No song waits more than 24 hours: after that it is searched anyway and Health warns, naming the library. The regular missing-song search leaves these songs alone for the same wait. Nothing is searched from here while search_on_add is off; the regular missing-song search finds the songs. Songs you add by hand, or from a pasted list, are searched at once.

Quality profile and library

Each list has its own Quality profile and Library. Left empty, they are the defaults.

Plex playlists and .m3u8

• Keep as a Plex playlist: Wondarr keeps one Plex playlist with the list’s name, adding, removing and reordering items in place, so its poster and play history survive each sync. See Plex.
• Write an .m3u8: writes <list name>.m3u8 into the Playlists folder under the library’s root, with paths relative to it.