Skip to content

Scanning your library

This page is for the person who runs the server. It explains how the server keeps its library in step with your music folder, when you need to start a scan yourself, and what the console’s lists (missing files, duplicates, no cover) mean.

What you need

  • A server with a music folder set (MUSONIC_MUSIC_DIR; with Docker, the folder mounted on /music).
  • An administrator account, to use the console.

The server scans the library when it starts, then:

  • a few seconds after a change in the music folder (a file added, changed, moved or deleted): it watches the folder and waits until changes have stopped for 5 seconds, so copying a whole album gives one scan, not one per file;
  • on a schedule, every 60 minutes by default, to catch what watching missed;
  • when you ask, from the console or a Subsonic client.

Scans never overlap: a request made during a scan starts another one right after it.

Each scan then walks the folders (skipping those that did not change), reads only the changed files (every file in a full scan), and updates the songs, albums, artists, covers and lyrics in the server’s database (musonic.db).

Diagram: four triggers (server start, a change in the music folder after 5 seconds of quiet, the automatic scan schedule, a button in the console) lead to one scan queue; the scan walks the folders, reads only the changed files, then updates songs, albums, artists, covers and lyrics in the database.
  1. Open your server’s address in a browser and sign in with an administrator account.

    The administration console opens on the dashboard.

  2. Click “Library” in the “Music” section of the menu.

    The top of the page shows the number of songs and when the last scan ran (for example “35 songs · last scan 8 minutes ago”), with the Quick scan and Full scan buttons at the top right.

    The console's Library page: title Library, the line 'songs · last scan', the Quick scan and Full scan buttons at the top right, the summary of the last scan, and the tabs Songs, Missing files, Duplicates, No cover, Online.
  3. Click “Quick scan” (or “Full scan”, see below which one you need).

    The line under the title shows “Scanning…” and both buttons are greyed out until it ends.

  4. Read the summary of the scan.

    It sits under the title line, for example “35 files · 0 songs added · 0 missing · 0 errors · 0 s”: the number of files, songs added, files missing, errors and the time it took.

Quick scan Full scan
What it reads Only the folders whose content changed (names, sizes, modification dates), and in them only the audio files that changed Every audio file again
When it runs At start-up, after changes, on the schedule, from the button Only when you ask
Time Seconds on an unchanged library About as long as the first scan
Use it Almost always After adding or replacing a cover image or a lyrics file next to songs that did not change; after editing tags with a tool that keeps the file’s modification date; when something looks wrong

From the command line or a Subsonic client

Section titled “From the command line or a Subsonic client”
Terminal window
docker compose exec musonic-server musonic-server scan # quick
docker compose exec musonic-server musonic-server scan --full # full

musonic-server scan scans once, prints a summary and exits. It is meant for scripts and for the first scan before a Navidrome import; while the server runs, prefer the console’s buttons, which go through the server’s own scan queue.

Subsonic clients with a “scan library” button use startScan (fullScan=true for a full scan); only administrator accounts may start one.

  1. In the console, open “Library”.

  2. Choose how often in “Automatic scan”, at the bottom of the page, under the list of songs.

    It is a drop-down list on the right of the block, under the note “Changes to the folder are seen at once; a regular scan catches the rest.”

    The choices are “On changes only”, “And every hour” (the default), “And every 6 hours” and “And once a day”.

    The bottom of the console's Library page: the end of the song list, then the Automatic scan block with its explanation and the drop-down list set to And every hour.
  3. Click “Restart now” in the banner that appears.

    The new value applies once the server has restarted. Music stops for a few seconds, then the apps reconnect on their own.

The same setting is scan_interval_minutes in the configuration file, or MUSONIC_SCAN_INTERVAL_MINUTES (minutes, 0 = only on changes; from 0 to 10080 in the console). A value saved in the console wins over the configuration file and the environment.

If the server cannot watch the folder, it writes this line in its logs at start-up and relies on the scheduled scans only:

cannot watch /music: …; relying on scheduled scans

Watching relies on the operating system’s notifications. They do not arrive for every kind of folder: changes made from another machine on a network share are often not reported. On Linux, a very large library can also exceed the number of folders a user may watch; raising fs.inotify.max_user_watches with sysctl fixes that.

In those cases, keep a schedule (every hour, or more often with MUSONIC_SCAN_INTERVAL_MINUTES), or start a quick scan by hand after adding music.

Every song has one id that does not change: it is given once, and kept across rescans, moves and imports. Likes, playlists, play counts and the apps’ downloads point at that id. When a file changes, the scanner looks for the song it belongs to in this order:

  1. The same path: a file retagged in place stays the same song, with its new tags.
  2. The same identity: a file moved or renamed is recognised by its MusicBrainz recording id, or else by album artist + album + disc + track number + title. It keeps its song, likes and playlists.
  3. A song first seen online with no file yet, with the same ISRC, or the same title, artists and length (within 3 seconds): an imported file joins the song that was already liked or in a playlist.
  4. Otherwise, a new song.
What you do What happens
Edit the tags of a file, in place Same song, new tags.
Move or rename a file or a folder Same song (found by its identity).
Move the whole music folder (another disk, another Docker mount) Nothing to redo: paths are kept relative to the music folder.
Move a file and change its title, album or track number at the same time A new song: the old one is shown as a missing file and keeps its likes. Do one, scan, then the other; or give your files MusicBrainz ids, which survive any change.
Delete a file Its song is marked as a missing file: hidden from the apps (unless it is also known in the online catalogue), kept with its likes and playlists. If the file comes back, the song comes back as it was.

Songs with a missing file are never deleted by the server on their own.

The Library page has tabs to check your library, under the summary of the last scan. Each tab shows how many songs it holds (for example “Missing files 0”):

Tab What it lists
Songs Every song, with its file, format, bit rate and size. Search by title, artist, album or file path.
Missing files Songs whose file is no longer in the music folder (moved without being recognised, or deleted).
Duplicates The same song twice: two files for one song (two copies with the same tags), or two songs with the same title and artists.
No cover Songs with no picture at all: none in the file, no image in their folder, none online.
Online Online songs liked or added to a playlist that have no file yet (not imported).

Click a song to open its page: tags, files (with Listen to check, to hear the file in the browser), online catalogues that know it, ISRC, genres, plays and likes. At the top: the title, then artist · album · year · track number · length, and Listen to check on the right. The Files block gives each file’s path in the music folder, format, bit rate, sample rate, channels and size, with a Listen button. ‹ Library, at the top left, goes back to the list.

The console's page for one song, Isobar: artist, album, year, track and length under the title, the Listen to check button, the Files block with the path, MP3 · 192 kbit/s · 44.1 kHz · mono · 4.5 MB and a Listen button, then Likes (in accounts), Plays, Genres, Added and Id.
  • The scanner reads the tags of several files at once, one per processor thread.
  • A folder whose content did not change (same names, sizes and dates) is not opened again: a quick scan of an unchanged library only walks the folders.
  • Changes are written in batches of 200 files, so the apps keep working during a long first scan.
  • On a large library, setting up the watching takes a while: the server answers requests meanwhile.
Setting (file) Environment Default What it does
music_dir MUSONIC_MUSIC_DIR none (/music in the Docker image) The music folder. Without it, the server starts with an empty library.
scan_interval_minutes MUSONIC_SCAN_INTERVAL_MINUTES 60 Minutes between scheduled scans; 0 = only at start-up, on changes and on request. Also in the console.