Advanced configuration recommendations

Navidrome: Group albums together regardless of release date

Navidrome 0.64.2 also groups albums by release date by default. If date tags in different file formats are interpreted as recording or release year, the same album may appear more than once.

To ignore release dates when grouping albums, set the following rule in Navidrome. Replace an existing rule rather than adding a duplicate TOML key. If adding a new rule, place it at the top level before table sections.

PID.Album = "musicbrainz_albumid|albumartistid,album,albumversion"

MusicBrainz album ID, album artist, album name and album version still determine grouping. The rule applies to the whole library. Releases differing only by date may be combined. No changes to media-file tags are required.

Navidrome then restart. The changed album rule triggers a full scan. Then reload the album view in the clients. An environment variable ND_PID_ALBUM takes precedence over the configuration file and may need to be adjusted accordingly.

Source: Navidrome: configurable album and track identifiers.

Navidrome: prefer embedded artwork

When tracks from different albums share a folder, a common Folder.jpg can otherwise override all their album covers. This priority prefers available embedded artwork; if none is embedded, the other sources remain as fallbacks.

In navidrome.toml, replace the existing value or add the setting at the top level before table sections. Do not duplicate the key.

CoverArtPriority = "embedded, cover.*, folder.*, front.*, external"

Then restart Navidrome. Restarting alone does not recalculate stored artwork. In Navidrome 0.64.2, affected albums can be resolved again individually with the official artwork command:

navidrome -c /pfad/navidrome.toml artwork refresh al ALBUM_ID_1 ALBUM_ID_2

Replace the example path and album IDs. Run the command as the same service user, in the same working directory, and with the same configuration, environment and database as Navidrome. No changes to media files or tags, or database deletion, are needed.

Then synchronize the client library again, for example in Amperfy, to obtain the new artwork identifiers. Reinstalling the app or clearing the entire artwork cache is not required.

Ampache and LMS: Login with API key

Ampache 7, Ampache 8 and LMS require an API key for login. Create a key for your own account on the server and use it when connecting in MusicServer Connect. Keep it confidential.

Ampache 7.10.2: Import titles without title artists

Symptom and cause

Files without a track artist may be omitted during catalogue import. The database correction below enables their import. Ampache login requires an API key; see Log in with an API key.

Scope

This correction applies to Ampache 7.10.2 with MariaDB and the column definition shown below. For other versions, first check whether the same cause applies.

What is changed

Only song.artist in the selected Ampache database is changed to allow NULL. Its data type, default value 0 and existing indexes are retained. Ampache source code and music files are unchanged. No artist names are invented and no file tags are replaced. Other databases and global MariaDB settings are unaffected.

General database fix

Requirements

Run these commands on the MariaDB server, inside its container where applicable. The database account needs read access for the check and ALTER permission on song. The example uses local root login. For another database account, use your existing secure client configuration; do not put a password in the command.

First identify the actual database name, listed as database_name in the Ampache configuration. Use your own database name in every command.

AMPACHE_DB='DEIN_AMPACHE_DATENBANKNAME'
mariadb --database="$AMPACHE_DB" -e \
  "SHOW COLUMNS FROM song LIKE 'artist';"

For the confirmed issue, the output shows Type=int(11) unsigned, Null=NO and Default=0. If Null=YES, the correction is already applied. Do not change a different definition without checking it.

Recommended: the enclosed script Download ampache7-null-artist.sh on the database server. It checks the column, accepts only the expected unsigned INT type and makes no further change if NULL is already allowed. An unexpected schema makes it stop without changes.

sh /pfad/zum/ampache7-null-artist.sh "$AMPACHE_DB"

The concrete SQL core of the fix for the definition confirmed above is:

ALTER TABLE song
  MODIFY COLUMN artist INT(11) UNSIGNED NULL DEFAULT 0;

Import missing files and check the result

After changing the schema, import the missing files. Use your own installation’s application path, catalogue name and service account. The PHP version must match the Ampache version.

AMPACHE_APP='/pfad/zur/ampache-installation'
AMPACHE_CATALOG='DEIN_KATALOGNAME'
runuser -u www-data -- php "$AMPACHE_APP/bin/cli" \
  run:updateCatalog "$AMPACHE_CATALOG" -a

mariadb --database="$AMPACHE_DB" -e \
  "SELECT COUNT(*) AS Titel FROM song;
   SELECT id, title, artist, enabled FROM song
   WHERE artist IS NULL;"

-a adds new media files. It does not request catalogue cleanup, playlist import or a rescan of existing file tags. Ampache may then update internal mappings and counters.

Then update the plugin, open all titles and check the previously missing titles. Then the titles above All titles → mark all → search DB → add to database into the VirtualDJ search database. See Search within tree nodes.

Operation and later updates

This is a local database-schema adjustment, not an officially confirmed general Ampache migration. After an Ampache database update, check song.artist and the import of files without track artists again: a migration may change the definition. The script can be checked repeatedly.

To restore NOT NULL, existing NULL entries would first need deliberate handling; blindly resetting the column is not an appropriate rollback. The checked correction preserves missing track artists as missing information.

Gonic 0.22.0: one album per music folder

Symptom and cause

Gonic requires a separate folder for each album. Keep an album’s files together; do not mix different albums in one folder. A shared folder for unrelated singles does not meet this requirement. Gonic may then apply the first file’s album metadata, including album artist, to every other file in that folder.

Recommended folder structure

For single tracks, also create one subfolder per album, for example «Einzeltitel/Alter Ego - Betty Ford (Bonus Remixes Version)» / «Einzeltitel/Homie Isback - Cherrymoon». Both Cherrymoon versions can share a folder if they belong to the same album. Keep different releases separate. Place music files in subfolders of the configured music path: Gonic 0.22.0 skips files directly in its root folder.

If several servers share a library, you can create a separate folder view for Gonic using symbolic links. Give each album its own folder there too. Configure music paths so each track is indexed only once. The Gonic service account needs access to both the links and their targets.

Check after the change

Fully rescan Gonic, then refresh the plugin track list. Check totals, album grouping, artist nodes and playback. Changes to import paths may create new server IDs, so check existing favourites, playlists and VirtualDJ settings afterwards. Register tracks again if needed. Add to the VirtualDJ search database. Newly added individual tracks must also be provided in the appropriate album folder structure.

Provide file-based playlists for the user

Gonic reads playlists from its configured playlists-path and a subfolder named after the numeric user ID. Put M3U/M3U8 files with media paths resolved for Gonic there. A normal music scan does not automatically import playlists from other library folders. Our setup creates derived views without changing the shared originals. Refresh these views after changing the sources.

Gonic project documentation

Gerbera 3.3.0-77: BPM, Key, UTF-8 and Inotify

Add the following mappings for BPM and key. Music files must contain corresponding BPM and KEY or INITIALKEY tags. Keep existing mappings such as PERFORMER.

For an XML-based installation, add the entries under import → library-options → id3 → metadata and ffmpeg → metadata. Gerbera labels the XML group id3 as taglib Library Options in its web interface. Set charset to UTF-8 in both libraries; keep or set filesystem-charset, metadata-charset and playlist-charset to UTF-8 too. Save and restart Gerbera. Additional tag mappings take effect when files are imported again; a normal rescan may skip unchanged files. For a new installation, configure these options before importing music.

MP4, M4A and M4V: prefer more precise BPM tag

Available from Git build 3.3.0-77: The BPM extension Gerbera-PR #3993 has been merged and is included in the official image. Higher precision is optional and must be enabled with prefer_highest_bpm_accuracy="yes" be switched on. Without this attribute remains no the default.

The MP4 attribute tmpo contains an integer. In addition, an additional iTunes BPM tag can contain a more precise value. In the existing XML element import → library-options → id3 can its preference be switched on; keep the existing tag mappings:

<id3 prefer_highest_bpm_accuracy="yes" prefer_ambigous_bpm_value="bpm_tag">
  <metadata>
    <add-data tag="BPM" key="upnp:beatsPerMinute" />
  </metadata>
</id3>

If missing prefer_highest_bpm_accuracy or if it is set to no, previous behaviour is retained. For yes Gerbera reads tmpo and the additional BPM tag separately. If the distance is less than 1 BPM, the tag value is adopted, for example 123,5 instead 123. If values differ by at least 1 BPM, selection is determined by prefer_ambigous_bpm_value: tmpo prefers the whole number, bpm_tag the additional tag. If the second attribute is absent, bpm_tag. The attribute notation is explicit prefer_ambigous_bpm_value.

Only finite positive numbers are valid for this selection; use a decimal point in the file tag. If only one source is valid, it is used. Half-time or double-time values are not corrected automatically. Other tags, genres, key and covers are read as before. Restart Gerbera after changing configuration and reimport affected files; a normal rescan may skip unchanged files.

AIFF: BPM, key and read multiple genres

If AIFF files are missing BPM or key despite existing ID3 tags, in Gerberas Config → Expert → Import → Mappings → Mimetype-Contenttype the mapping of the recognized MIME type to the content type aiff supplement. For audio/x-aiff and audio/aiff each aiff enter. This allows Gerbera to use the matching TagLib reader; the BPM/key mappings from the table above are still required.

In the XML configuration, the following lines in the existing section import → mappings → mimetype-contenttype with the following additions, retaining existing mappings:

<treat mimetype="audio/x-aiff" as="aiff" />
<treat mimetype="audio/aiff" as="aiff" />

Restart Gerbera or its container and import the affected files again. A normal rescan may skip unchanged files; no renaming or timestamp changes are required.

OGV: Adopt tags from the audio and video tracks

With OGV, the title, artist, album, genre, BPM and key can be in the individual audio and video tracks. Activate in Gerberas Config → Expert → Library Options → ffmpeg Library Options the option streams-enabled. This is available in the XML configuration import → library-options → ffmpegelement, the attribute streams-enabled="yes" put; Preserve existing attributes and tag assignments.

Restart Gerbera or its container, then reimport existing OGV files. The BPM/key mappings in the table above are still required. Without stream metadata analysis enabled, these values may be absent despite correctly saved file tags.

WebM and WMV: adopt multiple genres with the right reader

Since Git build 3.3.0-62 and also in the current one 3.3.0-77 can read multiple genre tags from WebM and WMV. Updates retain the existing configuration, so reader mappings added in the new build may still be missing. In Config → Expert → Import → Mappings → Mimetype-Contenttype Add the following mappings or in the existing XML section import → mappings → mimetype-contenttype enter:

<treat mimetype="video/webm" as="mkv" />
<treat mimetype="video/x-ms-wmv" as="asf" />

Keep existing mappings and BPM/key settings, restart Gerbera and reimport the affected files. This changes which metadata reader is used, not the returned video MIME type. Files need no conversion or renaming. The basis is the Default mappings of this Gerbera source version.

Automatically detect file and attribute changes

Inotify detects filesystem events. inotify-attrib="yes" additionally monitors attribute changes, including timestamps changed by touch. For a Linux installation, extend the existing autoscan section in /etc/gerbera/config.xml while preserving the music path:

<autoscan use-inotify="yes" inotify-attrib="yes">
  <directory location="/srv/music" mode="inotify" recursive="yes" hidden-files="no" />
</autoscan>

Then use the Linux service systemctl restart gerbera restart.

Inotify in the official Gerbera container

The official image already enables Inotify for the mounted music folder, but additional attribute monitoring is initially disabled. Use Inotify and Monitor Inotify Attribute Changes appear under Gerbera Config → Expert → Import, but cannot be edited through that view in the checked image. The settings are stored in /var/run/gerbera/autoscan.xml.

1. On QNAP, open gerbera-qnap in Container Station and start its terminal or console. On Synology, select gerbera-synology in Container Manager, open its terminal and start /bin/sh. Run the following command inside the container.
2. Insert the following block. It completes the attribute and shows the scan file; Music path and existing settings are retained.

test -f /var/run/gerbera/autoscan.xml &&
sed -i -e 's/inotify-attrib="no"/inotify-attrib="yes"/g' \
  -e '/<autoscan/ { /inotify-attrib=/! s/<autoscan/<autoscan inotify-attrib="yes"/; }' \
  /var/run/gerbera/autoscan.xml &&
cat /var/run/gerbera/autoscan.xml

The output must show autoscan with inotify-attrib="yes". Restart the container, then check that Monitor Inotify Attribute Changes is selected in Gerbera Config. If autoscan.xml is missing, first identify the configuration file actually in use. This command applies to the official build specified in the NAS guides.

Separate genre tags need no additional setting. MusicServer Connect uses all genre fields supplied by UPnP. Since version 1.5, combined genres separated by semicolons or slashes are also assigned to their individual genre views. Server and file tags remain unchanged.

Sources: Gerbera autoscan and attribute monitoring, Initial configuration of the official container image.

Gerbera 3.3.0-77: pure title names in search results

Gerbera combines M_ARTIST and M_TITLE for track titles in UPnP search responses by default. MusicServer Connect imports through that interface, so “Speedy J - Electric Deluxe” appears in the title column even though the TITLE file tag contains only “Electric Deluxe”.

Under server → upnp, configure search-item-result to use only M_TITLE. extend="no" replaces the default list instead of appending entries:

<search-item-result extend="no">
  <add-data tag="M_TITLE" />
</search-item-result>

The Configuration script gerbera-suchtitel.py sets this option in an existing XML configuration. The default path is /etc/gerbera/config.xml; another path can be supplied as an argument. Existing namespaces, comments and other settings are preserved. If the server structure is ambiguous, the script stops before writing.

Alternatively in Gerbera's web interface at Config → Server → UPnP → Search item result the entry M_ARTIST remove and only M_TITLE to retain it. Check settings already saved in the web interface, as these may override XML values. This setting also applies to Gerbera 3.3. The artist remains available as a separate metadata field.

Restart Gerbera and reload the plugin connection. This setting changes track titles in search results; no plugin or music-file changes are needed. Check the display of tracks already stored in VirtualDJ too. Optional FRITZ!Box artist detection is independent of this setting.

Gerbera: Playlist views and import

Why the same playlist appears multiple times

Gerbera may show the same playlist under both Playlists → All Playlists and Playlists → Directories. This does not mean the playlist file exists more than once.

MusicServer Connect combines identical playlist views. If their contents differ or a query is incomplete, multiple views may remain visible.

Check incomplete playlist imports

1. Check the playlist entries. Relative paths refer to their folder.
2. Verify that all referenced music files exist and are readable by Gerbera's service account.
3. Read the playlist again after changes. If the import is incomplete, restart the Gerbera service and wait for the scan.
4. Then update the view in the plugin and check the playlist.

To detect changes to file timestamps automatically, use Inotify attribute monitoring activate.

Deprecated playlist references and M3U character set

Check playlist contents again after changes to referenced media files. A normal rescan may leave existing playlist views unchanged. Then refresh the library in MusicServer Connect. Catalog identifiers may change in the process.

To share the same playlist files with MinimServer, we save M3U as Windows-1252 and M3U8 as UTF-8. In tested build 3.3.0-77, Gerbera’s standard importer did not correctly resolve the path containing an umlaut in the Windows-1252 M3U file. The Download verified M3U import extension and save it in the configured custom-script directory. It detects valid UTF-8 in M3U lines and otherwise uses Windows-1252. M3U8, PLS and XML playlists continue to use the standard importer. Preserve existing custom scripts.

In the existing Gerbera configuration under import/scripting/import-function the playlist function name from importPlaylist on mscImportPlaylist to change. Under import/scripting/script-folder/custom The configured directory must contain the downloaded file and be stored permanently for container installations. In the test bench it is inferior /var/run/gerbera/custom-js. Then restart Gerbera and import the playlist records again. The extension requires the JavaScript importer.

MiniDLNA / ReadyMedia 1.3.3: Playlist file extensions

MiniDLNA 1.3.3 recognizes playlists with .m3u and .pls. Files with .m3u8 are not read.

Recommendation: rename M3U if possible

If no other application or server configuration depends on the current M3U8 file name, change the extension from .m3u8 to .m3u. This is the simplest solution for MiniDLNA. Keep the contents, UTF-8 encoding and location unchanged so relative music paths continue to work. Update any references to the playlist file name. Then have MiniDLNA import the playlist again and refresh the plugin.

Alternative: preserve a shared M3U8 source

If other servers need the M3U8 file, create an additional M3U file for MiniDLNA. If it is in a different folder, adjust relative music paths or use absolute paths.

The Setup script minidlna-playlist-view.py checks source and destination, creates the derived M3U and adds media_dir=A,/media3 to MiniDLNA’s existing configuration. It does not change the M3U8 source or existing media_dir entries. On a destination conflict, it stops. Reload MiniDLNA and refresh the plugin. After changing the source playlist, run the script and restart MiniDLNA again to keep the derived view current. No change watcher is installed.

Cache permissions when rebuilding

If MiniDLNA cannot clean up its cover cache when rebuilding, check the write permissions on the cache and its subdirectories.

For other installations, first identify the actual service account and configured cache path. After rebuilding the library, refresh the plugin. If necessary, register the full track list again using “DB search → Add to database”.

Share audio and video

A share with media_dir=A,/srv/music is limited to audio. For both media types, open this existing line media_dir=AV,/srv/music change, get further approvals and restart the service. The codec and metadata limits remain independent of this.

Serviio 2.5: release required views

To have album artists and the original album order available, display the required categories in the Serviio console.

Track order

For the original track order, open a single album. A selected column sorting in VirtualDJ can change the visible order.

In the Serviio console under Presentation → Audio, set Music, Albums, Titles and Playlists to “Display category”. Other audio categories can use “Display content only”. The album view must be available for the supplementary query. No music-file changes are needed.

Different saved album artists

If Serviio’s album or artist metadata differs from file tags, reread metadata on the server, then refresh the plugin.

If there are multiple genre tags, only the first one is adopted.

If a file has multiple genre tags, only the first is used. The remaining genres are missing from the returned metadata and genre tree. This compatibility limitation is not specific to one file format.

Also read videos

Under Library → Shared folders edit the existing library folder and in addition to Audio also Video to enable it. Save the share and Force refresh execute. Mixed file playlists are delivered by Serviio in separate audio and video views.

Twonky Server 8.5.2: full track and album retrieval

When it detects the Twonky structure, MusicServer Connect uses the complete native track and album views. In our checks, global server search omitted seven accessible tracks under W and Y. The automatic fallback also retrieves these tracks and preserves album order. No additional plugin setting is needed. Incomplete or inconsistent native pages are still rejected.

The follow-up check covered 149 media files (139 audio, ten video) and all offered views without retrieval errors. Missing ASX/XSPF support, formats and metadata remain server limitations. Twonky may require a new vendor login after restarting; a login notice is not a music catalogue.

Universal Media Server 15.8.2: Linux service and album display

For a Linux service, set the environment to UTF-8 so that music paths containing umlauts and other Unicode characters can be processed.

With systemctl edit DIENSTNAME.service Set up the following addition for your own UMS service. After that systemctl daemon-reload Run, restart this service and wait for the library scan.

[Service]
Environment=LANG=C.UTF-8
Environment=LC_ALL=C.UTF-8

The C.UTF-8 locale must be available on the system. Setting Java file.encoding alone does not replace the locale used for file names. A Java command launched from an interactive shell may use different settings from the running service.

Direct access to the music folder on Linux avoids Windows-share restrictions on file names, such as names containing a question mark.

Album artists and database search

For complete album artist information in UMS.conf, activate the built-in database search and restart UMS:

search_lucene_use_engine = false

The setting replaces the Lucene full-text search with the built-in database search.

Original album order

For the original track order, open a single album. A selected column sorting in VirtualDJ can change the visible order.

UMS combines multiple genre tags into one text separated by “ / ”. MusicServer Connect creates individual genre nodes from it; the track appears under every listed genre. Dealing with multiple genres.

ASX files and incomplete catalog search

UMS 15.8.2 may count ASX playlist files as video folders without returning corresponding objects. Audio search may also announce more matches than it returns, and may omit OGG from audio-class searches. MusicServer Connect detects these inconsistencies and supplements the catalogue using real file folders. The checked collection of 141 audio and ten video files appears in full, with existing audio IDs and metadata retained. No additional setting is needed.

The plugin discovers real subfolders independently of the incomplete SQL search. Previously checked search pages are used only to map aliases. It compares two complete file inventories before accepting them and checks again for changes to search state. It does not traverse virtual filter combinations. If a future UMS version supplies complete search results with correct media classes, the plugin automatically uses that direct search again. Library source files remain unchanged.

This fallback does not repair missing server metadata or playlist entries: ASX, WPL and XSPF are still absent as playlist views. UMS omitted the first track from the older M3U/PLS lists checked here. The three mixed-format lists, however, contain all six positions, including repeated audio and video entries.

Audio conversion and streaming WAV

UMS may transcode audio to 16-bit WAV depending on the client profile. Four samples contained complete audio in the follow-up check, although unbounded WAV lengths failed strict file validation. Normal decoding and comparison after normalization to 16-bit succeeded. This does not prove preservation of an original 24-bit resolution. Very small range requests could return empty during conversion; normal downloads and 64 KiB requests worked.

Hide the extra transcoding folder

show_transcode_folder = false hides the virtual folder for alternative transcoding settings. Transcoding itself and the saved media tags are retained. This display option alone does not fix inconsistent UPnP page counts.

MinimServer: BPM/Key and library update

Read BPM and key from music files

To supply additional tags, you need a full or trial MinimServer licence. Music files must contain BPM and KEY or INITIALKEY tags.

1. On the MinimServer configuration page, open Properties.
2. Under itemTags the names BPM,KEY,INITIALKEY supplement. Keep existing entries; the tags must match your own music files. KEY and INITIALKEY consider: The MP3 field TKEY is treated by MinimServer as INITIALKEY is read.
3. Save the changes and perform the requested server restart.
4. Run a rescan under Status. Then update the library in MusicServer Connect.

Further information: MinimServer: additional metadata and License scope. WiiM's Advanced Mode is a feature of the WiiM app; the full license requirement here concerns the additional server metadata.

Values already stored in VirtualDJ may remain after a change. To reread embedded BPM/key tags, select affected tracks and choose “Read BPM and key from music file” in the context menu. For fresh audio analysis, use “Analyse BPM and tags”; with multiple tracks selected, this action is under “Batch”.

Reread after changes

Rescan MinimServer after changing music files, tags or modification times. Open its configuration page, choose the Status tab and click Rescan. Refresh status until it reports “Running”, then refresh MusicServer Connect. Restarting MinimServer alone does not generally trigger a rescan.

An outdated server index may return “Modified or deleted item” placeholders without track metadata or audio files. These placeholders may still be included in the reported total. The plugin then shows fewer usable tracks, although album artists and albums remain known from existing server containers.

See MinimServer configuration page and rescan as well as official web API for automated rescans.

Combine one album from multiple folders

If tracks from the same album are in multiple folders, MinimServer can deliver multiple albums with the same name. The setting under Properties mergeFolderAlbums on true to the indicated value, save and restart MinimServer. Album name and album artist must match. This setting applies to the whole library and may also combine other matching albums from multiple folders. Media files are unchanged.

In our check, this combined “MSC Format Tests 1.3” from Audio and Video subfolders into one album with 13 tracks recognized by MinimServer. Previously, the two groups contained eleven and two tracks. Then open the server in WiiM Home and … → Rescan music server to update the app’s own index. The label may differ with the app language. Afterwards, WiiM Home displayed only one copy of the example album in our check.

See MinimServer: albums and folders and WiiM Home: Read media library again.

M3U/M3U8: Character set and missing entries

MinimServer expects .m3u with Windows-1252 or ISO-8859-1 and .m3u8 with UTF-8 encoding. A UTF-8 file with the extension .m3u may therefore omit tracks whose paths contain accented characters. Use M3U8 for Unicode paths. If M3U is also needed, save a separate copy in the appropriate encoding. Do not replace characters that this encoding cannot represent.

In the checked collection, a rescan repaired the stale “Betty Ford” reference previously returned as “Modified or deleted item” without usable audio. Correct Windows-1252 encoding of the additional Sven Väth M3U also restored the accented-path reference to “W.I.R.” Both lists then supplied all four tracks in source order, without a full catalogue rebuild. Mixed-format lists supplied five of six positions, including repeats; MKV remained excluded because the format is unsupported.

After the rescan, update the library in the plugin. Source: MinimServer: Playlist formats and character sets.

JRiver: Import playlists and allow read access

Import playlists into the JRiver library. If automatic music import skips a playlist, import it separately, then refresh the plugin view.

Writing through JRiver’s web-service interface requires authentication to be enabled. Anonymous read access must remain allowed: MusicServer Connect uses it to distinguish regular and smart playlists. Read access does not grant playlist-editing permission.

You can show or hide smart playlists in the plugin. Hidden smart-playlist contents are not requested while building the tree; they are loaded when you show them. Empty lists and lists with no audio tracks do not appear as music playlists.

Synology: Set up default media server

Synology’s standard server supports WiiM Home Advanced Mode. It is also sufficient for MusicServer Connect if VirtualDJ calculates BPM and key itself. For stored BPM/key values, you can use Gerbera in the container . Both servers can read the same music files.

Install Media Server in Package Center and copy your music library into the shared music folder. A storage pool and volume must already exist.

• General settings: DMA menu language as desired, DMA menu style Simple style; Leave SSDP reporting interval at default value.
• Search settings: set Music Display Format to “Title only”; allow extra cover files with “Cover image for audio/video files” and retain the default file names.
• DMA Compatibility: Leave audio transcoding and custom MIME types turned off. Allow access to the desired devices.
• After copying, safely eject the USB memory. The albums, individual tracks and playlists folders are located directly under music.

The Synology media server combines multiple genre tags into one value separated by “;”. MusicServer Connect creates individual genre nodes, so each track appears under every listed genre. Dealing with multiple genres.

Save playlists with the .m3u extension. In File Station, rename a .m3u8 file under music/Playlists to .m3u, keeping UTF-8 content and relative paths. If other servers need M3U8, create a separate M3U copy.

FRITZ!Box: audio formats and track artists

Set up the media server

Connect the USB storage containing the music library. In the FRITZ!Box interface, enable Media Server under Home Network → Media Server, select the USB storage as a media source and apply. Build or update its file index under Home Network → USB/Storage or Storage (NAS), and wait for indexing. Then select the FRITZ!Box media server in MusicServer Connect.

Audio formats and metadata

FRITZ!Box can stream many audio formats but reads only some of their tags. Without tag support, album artist, album and genre are missing from the library tree. With track-artist detection enabled, MusicServer Connect can derive an artist from names in the “Artist - Track name” pattern. Files remain accessible through All Tracks, folders and supported playlists.

For MP3/WMA, the vendor documentation lists title, artist, album, genre and track number and ID3 v2.3 or older. Album artist, BPM and key are therefore not confirmed as supported fields. VirtualDJ or the player must support the audio format for playback.

Recommendation: use track artists

For libraries with FLAC or other formats without tag evaluation, even when mixed with MP3, the view Track artist if file names follow the pattern “Artist - Title Name” correspond. To do this in the context menu of the source MusicServer Connect first “Determine title artist from file names” turn on. Then select “Show artists” and “Switch to title artists” if this view is not already active.

This detection is disabled by default for new server connections and is saved per connection. To turn it off, choose “Disable track artist detection from file names” in the same menu. Leave it disabled if your file names do not follow “Artist - Track name”: the plugin cannot determine whether text before a hyphen is an artist or part of the title.

When detection is enabled, the artist is missing and the name matches the pattern, MusicServer Connect splits at the first “ - ”. For example, “1st Bass - Slam Me Down” becomes artist “1st Bass” and title “Slam Me Down”. Further hyphens stay in the title; existing artist metadata takes priority. When disabled, this split is not performed and the server-supplied title remains unchanged for this purpose. Remix detection is a separate setting.

When switching, MusicServer Connect also updates saved title displays if title and artist still match one of the two plugin-generated variants. Other manual edits are preserved. This switch does not change BPM, key, remix or analysis values.

This detection fills the artist field and track-artist view. It does not replace album, album-artist or genre tags. If your library contains only MP3, WMA or ASF, the server-supplied tags can be used and the track-artist view is not needed as a fallback. The album-artist view is useful only if the server actually supplies the required information.

For formats whose tags are not read, FRITZ!Box also cannot supply stored BPM/key values. VirtualDJ can calculate these itself. For complete tag-based library navigation, use a music server that supports metadata for your formats.

Playlists

Use M3U or PLS. WPL is recognized but can omit tracks, so choose M3U or PLS for reliable complete lists. M3U8, ASX and XSPF are not recognized as playlists. Keep UTF-8 content and valid relative music paths. MusicServer Connect removes the file extension and appended folder name from the displayed playlist name.

Manufacturer documentation: Audio formats, tag reading and playlist formats, Sorting and tag versions as well as Set up media server and create file index.

QNAP: Run standard media server and Gerbera in parallel

QNAP’s standard Media Streaming Add-on supports WiiM Home Advanced Mode. It is also sufficient for MusicServer Connect if VirtualDJ calculates BPM and key and incorrect playlist order is acceptable. For stored BPM/key values, separate genres and correct playlist order, you can use Gerbera with container station be supplemented.

Install Multimedia Console and Media Streaming Add-on in App Center. Place music folders under Public/music. In Multimedia Console → Content Management, select Media Streaming Add-on and add Public/music as a content source.

• Indexing: Enable Multimedia Info; Normal priority. For the UTF-8 library, select UTF-8 if offered, otherwise leave the default.
• Open the Media Streaming Add-on settings separately. Select your own NAS user account and the appropriate network interface; use the default port 8200.
• Under DLNA Media Renderer, allow the desired PC or client to access.
• Under Browsing Settings, set Default Menu Style to All Categories. Under DLNA Media Renderer, also select All Categories and your own user profile for the client. Apply both changes.
• Stop and start the Media Streaming Add-on in the App Center. Then check the device release again and set it again if necessary.
• Playlists are available as M3U, PLS or WPL; M3U8 is unsupported. Use UTF-8 and valid relative paths. Track order remains incorrect in all three formats.

File names containing a question mark can cause problems when copied through Windows/SMB. Copy affected files directly from USB storage into the appropriate music folder using QNAP File Station.

For album order, keep each album’s music in one folder. For multiple discs, use subfolders such as CD 1 and CD 2, with positive, unique track numbers. QNAP uses only the first genre. Playlist order remains incorrect with M3U, PLS and WPL; switching between them does not solve this.

Add Gerbera for MusicServer Connect

Continue to use the existing library under Public/music and Gerbera after the following step-by-step instructions . Then connect to Gerbera’s device URL in the plugin and check tracks, tags and order. Keep Media Streaming Add-on running for WiiM Home Advanced Mode or other devices, selecting QNAP’s standard server there. Use Gerbera in MusicServer Connect for BPM/key and correct playlist order. If WiiM Home also needs reliable playlists from the same server, MinimServer is a suitable shared solution. Both services read the same music files.

Vendor notes: M3U format, UTF-8 and relative paths as well as Manual device sharing in the media streaming add-on.

QNAP: Set up Gerbera with WavPack correction step by step

Gerbera is additional media-server software for your QNAP. Its key benefit for MusicServer Connect is access to values already stored in your music files: BPM and musical key metadata: QNAP’s built-in UPnP media server does not provide this information. The following steps set up the required metadata mappings.

The playlist support can also speak for Gerbera: The QNAP standard UPnP server described here does not display M3U8 playlists. For recognized M3U, PLS, ASX and WPL formats it does not preserve track order. Renaming M3U8 to M3U therefore does not fix ordering. Gerbera is an alternative if you need M3U8 or exact playback order.

When do you not need Gerbera? If your files have no stored BPM/key values and playlist order is unimportant, you do not need Gerbera for these purposes. VirtualDJ can calculate BPM and musical key by analysing files without a music server. You can keep QNAP’s built-in media server and let VirtualDJ calculate them.

QNAP’s own media server can continue running alongside Gerbera, for example for WiiM Home Advanced Mode. Gerbera does not support this WiiM mode. Your music stays in its existing folder; Gerbera gets read-only access. This guide also enables automatic detection of new and changed files.

Recommended version: This guide uses the official Gerbera Git build 3.3.0-77 from source revision 245e723. The Docker image is set with tag and SHA-256 checksum; it contains the corrections already applied for WavPack and repeated playlist titles as well as multiple genres in WebM/WMV and higher BPM precision. In the case of an update with an existing configuration, this too Add reader mappings. It is a development status according to 3.3.0, not a new stable release version.

Gerbera 3.3.0 is incorrect during WavPack import: The unchanged 3.3.0 image can be read when reading from .wvfiles. In the build used here, the affected memory is allocated on the heap. WavPack remains fully usable; no additional patch script is required. Use the complete image reference shown above.

1. Prepare folders, users and files

1. Sign in to QTS with an active administrator account whose password you know. The built-in account admin does not have to be activated for this; another authorized administrator account is sufficient.
2. Install in App Center the application Container station. Open it and complete the initial setup. Multimedia Console and Media Streaming Add-on are not required for Gerbera.
3. Create under Control Panel → Permission → Users → Create the user gerbera . This user does not need administrator rights. Grant it read access to the music share, including its folders and files. Continue using your administrator account for SSH.
4. The examples use the music folder Public/music, on the NAS /share/Public/music. For another share, use your actual path. Your existing music can stay there. Remove Windows illegal characters like ? from file names and adjust playlist references if necessary; the title tags may still contain these characters.
5. Create in File Station under Public the folder gerbera-qnap and its empty subfolder empty .
6. Download the Compose file as compose.yaml . Upload it directly through File Station to Public/gerbera-qnap next to the folder empty. The file name must compose.yaml without an additional .txt.

2. Enable SSH and obtain root access

1. Open in QTS Control Panel → Network and File Services → Telnet/SSH.
2. Enable Allow SSH connection, leave the port at 22 and click on Apply. If Edit access permissions is offered, allow your administrator account access there. If the NAS firewall is active, the SSH port for your computer must be allowed in the local network.
3. Open Terminal on the Windows-PC or PowerShell on the Mac Terminal. Replace in the following command DEIN_QTS_KONTO through your administrator account and NAS_IP with the QNAP IP address.

ssh DEIN_QTS_KONTO@NAS_IP

When establishing the connection for the first time, check the destination address displayed and confirm the query with yes. Enter your QTS account password. No characters or asterisks appear when typing. Use if a different SSH port is used ssh -p PORTNUMMER DEIN_QTS_KONTO@NAS_IP.

Then switch to root rights:

sudo -i
id

If you ask for your password again, use the same password from your registered QTS account. A special root password is not necessary. The output of id must uid=0 included; on QNAP the associated user name can be found admin . If a management menu appears, exit it using its Shell or Quit option. Leave the terminal open during setup: all following terminal commands run on the QNAP.

Determine the IDs of the user created for music access:

id gerbera

If the output shows uid=1001(gerbera) gid=100(everyone) is UID 1001 and GID 100. Write down your own numbers for the compose file.

3. Customize compose file

Open the downloaded one compose.yaml using a text editor, replace the example values for UID and GID through the numbers from step 2 and reload the saved file Public/gerbera-qnap high. The music mapping initially points to the empty folder. Existing music is only imported after metadata configuration.

services:
  gerbera:
    image: gerbera/gerbera:sha-245e723@sha256:b4463e92ee6cc0c6338b91d822904cb894dd66480e4eed60930fad1b69378e09
    container_name: gerbera-qnap
    network_mode: host
    restart: unless-stopped
    environment:
      # Beispielwerte: durch UID und GID aus "id gerbera" ersetzen.
      UID: "1001"
      GID: "100"
    command:
      - gerbera
      - --interface
      - eth0
      - --port
      - "49494"
      - --config
      - /var/run/gerbera/config.xml
    volumes:
      - gerbera-data:/var/run/gerbera
      # Zuerst den leeren Ordner verwenden; in Schritt 7 auf /share/Public/music aendern.
      - /share/Public/gerbera-qnap/empty:/mnt/content:ro

volumes:
  gerbera-data:

The official image selects the appropriate ARM64 or AMD64 variant for supported NAS models. The template does not contain a fixed NAS IP address. --interface eth0 uses the address of this network interface. For devices with multiple ports, virtual switches, or port bundling, replace eth0 through the interface actually used for the home network. network_mode: host enables UPnP detection in the NAS network.

/mnt/content:ro remains unchanged as a container path and only allows reading the music. The volume gerbera-data saves settings and database permanently. restart: unless-stopped starts the container again after a NAS restart if it was not stopped manually beforehand.

4. Start application with empty library

1. Open Container Station → Applications → Create. Use the name gerbera-qnap.
2. Add the full content of your customized compose.yaml into the YAML field. Keep the indentations with spaces and click Validate.
3. Create and launch the application. The first download of the image may take some time. Wait until gerbera-qnap is shown as active.
4. Open http://NAS_IP:49494/ in your browser. A missing web URL in Container Station does not prevent direct access. At this stage, the Gerbera library is intentionally empty.

5. Configure BPM, key and title display

Open in Gerbera Config and choose at List fashion the view Expert. Under Library Options → taglib Library Options → metadata and under ffmpeg Library Options → Metadata the following mappings. Preserve other existing lines.

1. Under Server → Name the name Gerbera QNAP a. This way the server can later be distinguished from the other music servers.
2. For AIFF below Import → Mappings → Mimetype-ContentType the two assignments audio/x-aiff → aiff and audio/aiff → aiff supplement. Without these assignments, BPM, key and other genres may be missing despite existing tags. AIFF configuration.
3. For OGV below ffmpeg Library Options the option streams-enabled Activate so that tags are read from the audio and video tracks. OGV configuration.
4. Set the field for taglib and ffmpeg charset on UTF-8. Also filesystem-charset, metadata-charset and playlist-charset should UTF-8 use.
5. Under UPnP → Title Result Item empty the field with M_ARTIST and receive M_TITLE. This supplies the plain track title.
6. Under WavPack Library Options remains Enabled switched on.
7. Click on Save Config, restart the empty container in Container Station and after reopening the configuration check that the values are saved.

BPM and Key must already be saved in the music files; Gerbera does not calculate these values. For MP4/M4A/M4V in the existing one id3element prefer_highest_bpm_accuracy="yes" and prefer_ambigous_bpm_value="bpm_tag" according to Configure BPM precision to the indicated values. Without the first option, the previous behaviour is retained. A normal rescan may skip files that have already been imported and have not changed. Configure these options before importing music for the first time. Separate genre tags need no additional setting.

6. Enable automatic updates

Gerbera already monitors new and changed files automatically. Add detection of file attribute changes with this complete block in the open root terminal:

docker exec -i -u 0 gerbera-qnap /bin/sh <<'GERBERA'
set -eu
file=/var/run/gerbera/autoscan.xml
test -f "$file"
sed -i -e 's/inotify-attrib="no"/inotify-attrib="yes"/g' \
  -e '/<autoscan/ { /inotify-attrib=/! s/<autoscan/<autoscan inotify-attrib="yes"/; }' \
  "$file"
cat "$file"
GERBERA

At the beginning of the output autoscan section must inotify-attrib="yes" stand. The setting is in the persistent data volume and will be loaded on the following startup.

7. Mount the music folder and start Gerbera

1. Stop the project or application gerbera-qnap in Container Station.
2. Open Public/gerbera-qnap/compose.yaml in File Station. Only replace the empty folder mapping with your actual music folder, for example:

- /share/Public/music:/mnt/content:ro

Save the file on the NAS, then copy the entire following block into the open root terminal. It applies the changed Compose file, reuses the existing data volume and starts Gerbera. If your project path differs, adjust the first line cd … on. The process also applies to WavPack files.

cd /share/Public/gerbera-qnap &&
PROJECT=$(docker inspect --format '{{index .Config.Labels "com.docker.compose.project"}}' gerbera-qnap) &&
case "$PROJECT" in ''|'<no value>') printf 'Compose-Projekt nicht gefunden.\n' >&2; false ;; *) true ;; esac &&
if docker compose version >/dev/null 2>&1; then
  docker compose -p "$PROJECT" -f compose.yaml create --force-recreate gerbera
elif command -v docker-compose >/dev/null 2>&1; then
  docker-compose -p "$PROJECT" -f compose.yaml create --force-recreate gerbera
else
  COMPOSE_BIN=
  for candidate in /share/*/.qpkg/container-station/bin/docker-compose; do
    if [ -x "$candidate" ]; then COMPOSE_BIN=$candidate; break; fi
  done
  if [ -n "$COMPOSE_BIN" ]; then
    "$COMPOSE_BIN" -p "$PROJECT" -f compose.yaml create --force-recreate gerbera
  else
    printf 'Docker Compose wurde nicht gefunden. Container Station pruefen.\n' >&2
    false
  fi
fi &&
docker start gerbera-qnap

Then open it http://NAS_IP:49494/ and wait for the library to load. You can see the progress below Container Station → Container → gerbera-qnap → Protocol. Continue to copy only fully prepared files into the music folder. Playlists require valid relative file paths and UTF-8 encoding.

8. Connect MusicServer Connect

In MusicServer Connect, select the server Gerbera QNAP. Use for a manual connection http://NAS_IP:49494/description.xml. Check track inventory, saved BPM/key values ​​and the order of your playlists.

If you have connection issues, check container status, NAS IP, network interface, and possible port conflicts. For UPnP detection must UDP 1900, for the web interface and media access TCP 49494 be accessible in the local network. At Permission denied control UID, GID and the read permissions of the Gerbera user. The path /content in the Gerbera protocol is normal for the official image.

Exit the terminal with exit; after sudo -i this is usually required twice. If you don't otherwise need SSH, remove in QTS Control Panel → Network and File Services → Telnet/SSH the checkbox for Allow SSH connection and click on Apply.

9. Restarts and newer Gerbera versions

For a normal reboot select Container Station → Container → gerbera-qnap → Restart. Settings and database remain in the named data volume gerbera-data received. When rebuilding the container, the unchanged executable from the official image is used.

Switching from an existing 3.3.0 installation

Use the full image reference from this guide and preserve music settings, user IDs, project names and data volumes. Recreate the container as shown below. A simple restart does not install a different image. Replacing the container removes any previous local binary patch.

Upgrade to a stable release later

1. Choose on the official Gerbera release page a stable version that includes the WavPack fix PR #3981 . Read the configuration and database notes. Until such a release is available, the Git version explicitly specified here is a fixed interim build. Do not use a moving latest- or edgetag.
2. Open Public/gerbera-qnap/compose.yaml. Replace that the complete value after image: through gerbera/gerbera:NEUE_VERSION. This also includes removing the previous ones @sha256:…reference, since it belongs to the old image. Replace NEUE_VERSION with the selected version number. Alternatively, use the complete image reference from the updated guide. Keep all other settings unchanged.
3. If necessary, enable SSH as described above and log in to the root terminal. Download the selected image:

docker pull gerbera/gerbera:NEUE_VERSION

4. Stop the existing project or application in Container Station. Run the full command block Step 7 out. The existing data volume must not be deleted.
5. Wait for startup and any database upgrade to finish. Check the version, server name and protocol, and saved BPM/key settings. Connect MusicServer Connect and check several tracks, WavPack files and playlists.

Vendor guides: QNAP Container Station and YAML changes, Enable SSH on QNAP, Create QTS user, official Gerbera Docker image.

Synology: Set up Gerbera with WavPack correction step by step

Gerbera is additional media-server software for your Synology. Its key benefit for MusicServer Connect is access to values already stored in your music files: BPM and musical key metadata: Synology’s built-in UPnP media server does not provide this information. The following steps set up the required metadata mappings.

When do you not need Gerbera? If your music files contain no stored BPM/key values, you do not need Gerbera for this purpose. VirtualDJ can calculate BPM and musical key by analysing the files without a music server. You can keep using Synology’s built-in media server and let VirtualDJ calculate them.

Synology’s own media server can continue running alongside Gerbera, for example for WiiM Home Advanced Mode. Gerbera does not support this WiiM mode. Your music stays in its existing folder; Gerbera gets read-only access. This guide also enables automatic detection of new and changed files.

Recommended version: This guide uses the official Gerbera Git build 3.3.0-77 from source revision 245e723. The Docker image is set with tag and SHA-256 checksum; it contains the corrections already applied for WavPack and repeated playlist titles as well as multiple genres in WebM/WMV and higher BPM precision. In the case of an update with an existing configuration, this too Add reader mappings. It is a development status according to 3.3.0, not a new stable release version.

Gerbera 3.3.0 is incorrect during WavPack import: The unchanged 3.3.0 image can be read when reading from .wvfiles. In the build used here, the affected memory is allocated on the heap. WavPack remains fully usable; no additional patch script is required. Use the complete image reference shown above.

1. NAS and prepare users

1. Sign in to the Synology DSM interface with an account that belongs to the group administrator heard. This is an account that is allowed to manage packages and users. The account name does not have to admin read. If your account does not have these rights, you will need the person who manages the NAS.
2. Open this Parcel Center and install Container Manager. If this package is unavailable for your model, this guide does not apply to it. To edit the YAML file, you can additionally install Synology’s package Text editor install.
3. Open Control Panel → Users and Group → Users → Create. Create the user gerbera on. It does not require administrator rights. Assign your own password; You will continue to use your DSM administrator account for the following terminal commands.
4. Open Control Panel → Shared Folder, select your music folder, for example music, and choose Edit → Permissions. Give to the user gerbera permission Read only. Access must also apply to the included music folders and files.

The examples use /volume1/music as the music folder and /volume1/docker for container files. If these folders are on another volume, use their actual NAS paths where indicated. The container paths /mnt/content and /var/run/gerbera stay the same.

2. Create folders and copy files

1. Open File Station. In the shared folder, create docker the subfolder gerbera-synology . If the shared folder docker is missing, create it under Control Panel → Shared Folder → Create .
2. Create another subfolder named empty on. This folder remains empty. It serves as a temporary music folder so that the import only begins after the metadata has been set.
3. Download the Compose file as compose.yaml to your computer.
4. Upload the file using File Station → Upload directly in docker/gerbera-synology next to the folder empty. The file name must be exactly compose.yaml with no additional .txt be attached.

The project folder contains these two entries:

gerbera-synology/
├── compose.yaml
└── empty/

3. Activate SSH, log in to NAS and determine your IDs

You need terminal access to the NAS to find user IDs and run the following Docker commands. You can copy the commands shown here; programming knowledge is not required.

Check DSM account and password

1. Open in DSM Control Panel → User & Group → User. Highlight the account you want to use to later log in via SSH and click Edit.
2. The account must be activated: If necessary, remove the selection Deactivate this user account. After saving, the user list must show the status Normal instead Disabled are shown.
3. Under User groups the account must belong to administrator group. You need this account’s password to log in and later switch to root. If you do not know it, set and confirm a new password in the account settings. Save the changes.

You can use your existing DSM administrator account to do this. Do you specifically want the built-in account admin To use it, activate this account as described and assign a known password. The built-in account admin does not need to be activated if you have another active account from the group administrators use. The user created in step 1 gerbera is used exclusively for music access and does not require these administrator rights.

Turn on the SSH service on the NAS

1. In DSM, open the Control Panel and there Terminal & SNMP. Select the tab Terminal.
2. Select the checkbox for Enable SSH service. For this guide, leave the port at 22 are shown.
3. Click on Apply. Only then will the NAS accept SSH connections. If the DSM firewall is active, it must allow the SSH port set for your computer in the local network.

Log in from your computer and switch to root

1. You can find the NAS IP address at Control Panel → Network → Network Interface. Open on the Windows PC Terminal or PowerShell; on a Mac, the application Terminal.
2. Enter this command. Replace DEIN_DSM_KONTO with your DSM administrator account and NAS_IP with your NAS IP address. Do not use the newly created user gerbera.

ssh DEIN_DSM_KONTO@NAS_IP

When the connection is established for the first time, a query regarding the identity of the NAS may appear. Check the destination address displayed and confirm the connection with yes. Then enter the password for your DSM account. No characters or asterisks appear as you type the password; this is normal. If you use a different SSH port, add it when connecting. -p PORTNUMMER.

Then switch to the rights required for Docker with this command:

sudo -i

If asked for a password again, use the same password of your DSM account. A special root password is not required. The prompt usually ends with #. Keep this terminal window open during setup. All following terminal commands are executed there on the NAS.

For Connection refused First check whether you are using the SSH service Apply turned on and are using the correct IP address and port number. If password is rejected, check account name, password, status Normal and membership in administrator. Synology's guide to SSH login with root privileges also describes this process.

View Gerbera user IDs:

id gerbera

Output such as uid=1030(gerbera) gid=100(users) means: UID is 1030, GID is 100. Note the numbers from your own output: they identify the user and group.

4. Customize compose file

In File Station, open the file docker/gerbera-synology/compose.yaml with Text editor. Alternatively, edit it on your computer and upload it again. For UID and GID enter the numbers you just wrote down; you have to replace the example values ​​below. If necessary, adjust the NAS path to the empty project folder. Save the file.

services:
  gerbera:
    image: gerbera/gerbera:sha-245e723@sha256:b4463e92ee6cc0c6338b91d822904cb894dd66480e4eed60930fad1b69378e09
    container_name: gerbera-synology
    network_mode: host
    restart: unless-stopped
    environment:
      # Beispielwerte: durch UID und GID aus "id gerbera" ersetzen.
      UID: "1026"
      GID: "100"
    command:
      - gerbera
      - --port
      - "49494"
      - --config
      - /var/run/gerbera/config.xml
    volumes:
      - gerbera-synology-data:/var/run/gerbera
      # Zuerst den leeren Ordner verwenden; in Schritt 8 auf /volume1/music aendern.
      - /volume1/docker/gerbera-synology/empty:/mnt/content:ro

volumes:
  gerbera-synology-data:

network_mode: host enables detection in the home network without a fixed IP address in the YAML. The end :ro Gerbera only allows reading the music folder. In volume gerbera-synology-data Settings and database are saved permanently. restart: unless-stopped lets the NAS container start again after a NAS restart, provided you have not stopped it manually beforehand.

5. Start the project with an empty library

1. Open Container Manager → Project → Create. Use exactly this project name: gerbera-synology and the prepared folder as the path docker/gerbera-synology.
2. Choose the prepared one compose.yaml as an existing Compose file. If the dialog offers a YAML editor, you can insert the content there.
3. For Web portal settings remains Set up web portal via Web Station switched off. Click on Next and create and start the project. The first download of the image may take some time.
4. Under Container → gerbera-synology must be the status Running or Running appear.
5. Open in browser http://NAS_IP:49494/, for example http://192.168.1.10:49494/. Replace the example address with your NAS IP. You see Gerbera's surface; the music library is intentionally empty at this point.

6. Configure BPM, key and title display

Open in Gerbera Config and select the view Expert. Under Library Options → taglib Library Options → metadata as well as under ffmpeg Library Options → Metadata add the following lines, retaining other existing mappings.

1. Under Server → Name the name Gerbera Synology a. This way the server can later be distinguished from the other music servers.
2. For AIFF below Import → Mappings → Mimetype-ContentType the two assignments audio/x-aiff → aiff and audio/aiff → aiff supplement. Without these assignments, BPM, key and other genres may be missing despite existing tags. AIFF configuration.
3. For OGV below ffmpeg Library Options the option streams-enabled Activate so that tags are read from the audio and video tracks. OGV configuration.
4. Set the field charset for taglib and ffmpeg to UTF-8. Also filesystem-charset, metadata-charset and playlist-charset should UTF-8 use.
5. Under UPnP → Title Result Item empty the field with M_ARTIST and receive M_TITLE. The pure title name is transferred as the title instead of “Artist – Title”.
6. Under WavPack Library Options remains Enabled switched on.
7. Click on Save Config, restart the container in Container Manager and check that the values are saved after reopening the Gerbera configuration.

BPM and Key must already be saved in the music files; these settings do not calculate the values. For MP4/M4A/M4V in the existing one id3element prefer_highest_bpm_accuracy="yes" and prefer_ambigous_bpm_value="bpm_tag" according to Configure BPM precision to the indicated values. Without the first option, the previous behaviour is retained. Then import the affected files again.

7. Enable automatic updates

Gerbera already monitors new and changed files automatically. With the following block you can add the detection of changes to file attributes. Copy the entire block into the still open NAS terminal:

docker exec -i -u 0 gerbera-synology /bin/sh <<'GERBERA'
set -eu
file=/var/run/gerbera/autoscan.xml
test -f "$file"
sed -i -e 's/inotify-attrib="no"/inotify-attrib="yes"/g' \
  -e '/<autoscan/ { /inotify-attrib=/! s/<autoscan/<autoscan inotify-attrib="yes"/; }' \
  "$file"
cat "$file"
GERBERA

In the output must be at the beginning of the autoscan section inotify-attrib="yes" stand. The file is in the permanent data volume. The setting will be loaded with the music folder when you start it afterwards.

8. Mount the music folder and start Gerbera

1. Stop the project or application gerbera-synology in Container Manager.
2. Open docker/gerbera-synology/compose.yaml in File Station. Only replace the empty folder mapping with your actual music folder, for example:

- /volume1/music:/mnt/content:ro

Save the file on the NAS, then copy the entire following block into the open root terminal. It applies the changed Compose file, reuses the existing data volume and starts Gerbera. If your project path differs, adjust the first line cd … on. The process also applies to WavPack files.

cd /volume1/docker/gerbera-synology &&
if docker compose version >/dev/null 2>&1; then
  docker compose -p gerbera-synology -f compose.yaml create --force-recreate gerbera
elif command -v docker-compose >/dev/null 2>&1; then
  docker-compose -p gerbera-synology -f compose.yaml create --force-recreate gerbera
elif [ -x /var/packages/ContainerManager/target/usr/bin/docker-compose ]; then
  /var/packages/ContainerManager/target/usr/bin/docker-compose \
    -p gerbera-synology -f compose.yaml create --force-recreate gerbera
else
  printf 'Docker Compose wurde nicht gefunden. Container Manager pruefen.\n' >&2
  false
fi &&
docker start gerbera-synology

Then open it http://NAS_IP:49494/ and wait for the library to load. You can see the progress below Container Manager → Container → gerbera-synology → Protocol. Continue to copy only fully prepared files into the music folder. Playlists require valid relative file paths and UTF-8 encoding.

9. Connect with MusicServer Connect

In MusicServer Connect, select the server Gerbera Synology. If a device URL is needed, use http://NAS_IP:49494/description.xml. Check your songs, albums and playlists and open some songs with saved BPM and key values.

If the interface is not accessible or the server is not found, first check the container status and the NAS IP. If the DSM firewall is activated TCP 49494 and for UPnP detection UDP 1900 from your local network. If the log reports Permission denied for the music folder, check the user's read permission gerbera and the UID and GID from step 3. The path /content in the protocol is normal for the official image; it refers to the integrated music folder.

Afterwards, exit the terminal with exit leave; after sudo -i is usually twice exit necessary. If you don't otherwise need SSH, open in DSM Control Panel → Terminal & SNMP → Terminal, clear the checkbox for Enable SSH service and click on Apply.

10. Restarts and newer Gerbera versions

For a normal reboot select Container Manager → Container → gerbera-synology → Restart. Settings and database remain in the named data volume gerbera-synology-data received. When rebuilding the container, the unchanged executable from the official image is used.

Switching from an existing 3.3.0 installation

Use the full image reference from this guide and preserve music settings, user IDs, project names and data volumes. Recreate the container as shown below. A simple restart does not install a different image. Replacing the container removes any previous local binary patch.

Upgrade to a stable release later

1. Choose on the official Gerbera release page a stable version that includes the WavPack fix PR #3981 . Read the configuration and database notes. Until such a release is available, the Git version explicitly specified here is a fixed interim build. Do not use a moving latest- or edgetag.
2. Open docker/gerbera-synology/compose.yaml. Replace that the complete value after image: through gerbera/gerbera:NEUE_VERSION. This also includes removing the previous ones @sha256:…reference, since it belongs to the old image. Replace NEUE_VERSION with the selected version number. Alternatively, use the complete image reference from the updated guide. Keep all other settings unchanged.
3. If necessary, enable SSH as described above and log in to the root terminal. Download the selected image:

docker pull gerbera/gerbera:NEUE_VERSION

4. Stop the existing project or application in Container Manager. Run the full command block Step 8 out. The existing data volume must not be deleted.
5. Wait for startup and any database upgrade to finish. Check the version, server name and protocol, and saved BPM/key settings. Connect MusicServer Connect and check several tracks, WavPack files and playlists.

Vendor guides: Container Manager Projects, Available NAS models for Container Manager, SSH login with administrator rights, Official Gerbera image.

WiiM Home: expanded media library

WiiM Home Advanced Mode provides its own library view with album, artist and track categories. Supported servers include MinimServer, Synology’s standard server, QNAP’s standard server and Serviio. Gerbera currently provides the folder view in WiiM Home.

In Advanced Mode, WiiM imports server metadata into its own index, then builds uniform album, artist, track, playlist and genre views and its own search. In Legacy Mode, it displays the server’s navigation instead. These terms describe WiiM Home operating modes.

Recommendation for sharing

The standard Synology and QNAP servers support WiiM Home Advanced Mode, which does not need BPM or key metadata. QNAP’s incorrect playlist order remains a limitation in WiiM Home too.

If VirtualDJ calculates BPM and key itself, Synology’s standard media server is sufficient for MusicServer Connect. The same applies to QNAP if its incorrect playlist order is acceptable. An additional Gerbera installation is unnecessary in these cases.

To use stored BPM/key values or preserve QNAP playlist order in MusicServer Connect, you can add Gerbera with the WavPack correction in Docker. Select Gerbera in the plugin and the standard server in WiiM Home Advanced Mode. Both can read the same music library. MinimServer remains a single-server solution covering these requirements and WiiM Home Advanced Mode; it still needs the extra BPM/key tag configuration. Running Gerbera on Synology requires an available Container Manager.

Further information: WiiM Home: Media library and supported servers.

Ampache 7/8: Read videos and file playlists

A music catalog does not import videos into Ampache. For the video library, an additional local catalog with the media type Video and scan it. Catalogue paths must not overlap. Our setup therefore uses an additional read-only Linux directory view pointing to the same video files; the shared library files remain unchanged.

Import file-based playlists explicitly. The official CLI command is php bin/cli run:updateCatalog -i "Katalogname"; use the PHP version and service account appropriate to your installation. A metadata rescan alone is insufficient. Both versions supplied audio entries with repetitions in our comparison; video entries were absent from mixed file playlists.

Deliver MP3 unchanged

If automatic MP3 conversion is allowed but no converter is configured, Ampache 8 may return HTTP 500 when streaming. For unchanged delivery in the existing configuration, transcode_mp3 = "false" to the indicated value. Alternatively, configure a working transcoder. With MP3 conversion disabled, both streaming and downloading were verified byte-for-byte in our checks.

LMS: Playlists with tracks from the same album

In the LMS settings under Miscellaneous the option Skip playlists that contain tracks from the same album if you want these playlists to appear. Then reload the library. The comparison confirmed that repeated audio tracks were supplied in their original order.

Asset UPnP: media and playlist folders

In the asset web interface at Folders → Media Folders add the library folder. Under Playlist Folders specify each folder with playlist files individually; Subordinate playlist folders are not automatically included there. These are under test /srv/music/Playlists and /srv/music/Format-Test-1.3/Playlists.

Under Options → Display Settings Disable prefixes for track numbers, artists before compilation tracks and artists after playlist titles if you want plain track names. These settings change the display, not music files. The Asset provider uses the built-in branch Playlists for file playlists. This query does not recursively traverse dynamic filter combinations or Internet radio. The checked default navigation, including Dynamic Browsing, can be retained. Catalogue, artist, album and genre views were verified without retrieval errors after this adjustment. Asset supplies M3U, M3U8 and PLS; PLS track titles returned by the server may contain an artist prefix.

Asset Guide

Jellyfin 12.2.0: DLNA and client profile

Jellyfin requires the official one for MusicServer Connect DLNA plugin. Install it from the official plugin catalogue in server administration and restart Jellyfin. DLNA 14.0.0.0 was checked. In its settings, choose the account whose libraries should be exposed through DLNA. MusicServer Connect uses UPnP/DLNA, independently of login to Jellyfin’s own web interface.

Libraries and metadata

Audio files as a library type Music, videos as Music videos as libraries. Make the relevant media and playlist folders readable, then scan both libraries. To use only file tags, disable external metadata and image providers; also check the global artist and album settings. Keep embedded titles and local images enabled. Our setup accesses the shared music library read-only.

Client profile for MusicServer Connect

The Download a verified DLNA client profile and as MusicServer Connect.xml Save in the DLNA plugin user profile folder. This is lower for the native Debian installation /var/lib/jellyfin/plugins/configurations/dlna/user/; for other installations, use the actual Jellyfin data directory. The Jellyfin service must be able to read the file. Restart Jellyfin, then refresh the plugin library.

The profile identifies MusicServer Connect by its User-Agent. It provides stable resource URLs and correct media types for M4A audio and OGV video, keeping album views accessible and these formats visible in the catalogue. It is stored separately from the supplied system profiles.

Remaining restrictions

All audio and video sources and 195 plugin views were retrieved without errors in the check with 125 files. Over DLNA, Jellyfin supplies no BPM/key and incorrectly scales bitrates. ASX/XSPF are absent; M3U, M3U8, PLS and WPL lose repeated tracks. Some older M3U/M3U8 lists are also incomplete. Some album artists are misassigned and flat music folders may lack a native album view. WMA lacks its second genre; videos lack artist, album and genre. The client profile does not fix these limitations.

Official Linux installation · Official DLNA documentation

WiiM Home, Mezzmo and Windows Media Player

With these Windows servers, MusicServer Connect automatically uses the verified track or file folders to avoid incorrect or very slow global search responses. No additional plugin setting is needed. Plugin searches then run against the imported catalogue.

UPnP responses may take up to 30 seconds, or 60 seconds for Windows Media Player. Requests remain cancellable. Invalid or changing pages are still rejected; waiting longer cannot supply missing files or metadata.

WiiM Home Media Server 0.2.10.5

Music servers and VirtualDJ can run on the same Windows PC, including several servers at once. The server list combines normal UPnP discovery with an additional check for supported local servers. It identifies their actual open ports and verifies UPnP device descriptions. Different device IDs stay separate; multiple endpoints for one server do not create duplicate entries. Administrator rights are not required.

Normal Windows UPnP discovery did not find WiiM Home on the same PC in our check, although its device description was accessible. The plugin’s supplementary discovery finds it as WiiM Home: LaptopAcer — on another PC, use its name instead. In the connection dialog, click Search again and select the WiiM server. This UPnP connection needs no username or password. WiiM Home, Mezzmo and Windows Media Player were checked running simultaneously.

For an older plugin version, the full description address can temporarily be saved in Server URL here. For example, the checked local path is http://127.0.0.1:22346/upnp/DeviceDescription.xml. The port and path must belong to the running server; the plugin does not assume a fixed port. On this computer, port 22345 also exposed the same WiiM server. The written host name localhost returned HTTP 404 in a direct check and was not accepted as an equivalent replacement. The discovery failure cannot be conclusively attributed to either WiiM Home or Windows.

Add the music folder to the local media library and turn on DLNA sharing. The original source was used in the test \\smbserver\music . This interface supplies neither file-based playlists nor videos; AAC ADTS, Opus and WavPack are also absent. Playlists saved in the WiiM app do not demonstrate support for importing external playlist files.

Mezzmo 6.0.6.0

Add the Library folder including subfolders. External file playlists separated via Create playlist → Connected playlist . “Add files from an external playlist” imports referenced media and is a different operation. To preserve original file tags, leave automatic Internet metadata retrieval and writing disabled.

Folder properties offer Check folders for new files every. Already linked lists have separate results. Folder monitoring alone did not create linked lists from playlist files, even with extra playlist extensions configured. Updating an existing link and discovering new playlist files are different features. The separately checked lists lose repetitions with M3U/PLS/WPL; M3U8/XSPF remain empty and both ASX samples report inconsistent page counts. Smart playlists cannot replace a fixed external order with repetitions.

The default filter includes .aif but not .aiff. Adding *.aiff indexed the sample only as an unknown file type without a stream, so this change was reverted. WavPack was also not exposed as playable to the checked client. A database entry alone does not prove playability.

Windows Media Player Legacy / Sharing 12.0

Under Control Panel → Network and Sharing Center → Media Streaming Options on Allow all click and with OK save. This gives the devices in the local network including WiiM and the cell phone with WiiM Home access to the media library. At Access denied Check this device approval: Functioning plugin access on the same PC does not mean that external devices are permitted.

Enable media streaming for the local network and add local music and video folders to their Windows libraries. You can disable automatic Internet metadata retrieval and writing to preserve source files. The full local comparison returned 146 real media files and fully decoded all 20 offered format samples. OGG, Opus, WavPack, WebM and OGV were absent; BPM and key were not supplied. After rebuilding the WMP catalogue, six nonempty playlists were returned. Some names differ from the imported lists; two older M3U lists lose one track because of character encoding. Their WPL equivalents contain all four tracks.

Use playlist names without dots, for example MSC Mixed 1-3 instead MSC Mixed 1.3. In the targeted WPL, M3U and M3U8 comparison, WMP truncated saved import-copy names at the first dot; the shortened name also appeared over UPnP. A hyphen preserved the complete name.

For WMP, the plugin requests structure-only listings with a small metadata filter. Full track metadata, resources and playlist contents are still read, with pagination and consistency checks retained. For this library, cleanup and plugin optimization reduced the measured first catalogue request from about 22 seconds to 4.3–4.6 seconds. This is a provider measurement for the checked library, not a general promise for VirtualDJ’s interface or larger libraries.

If your collection also contains playlist files, add only the actual audio subfolders to the Windows music library and add video folders separately. Import playlists explicitly into WMP. Adding the whole parent folder caused WMP to expose some playlist files as audio tracks or empty lists. Repeated imports created additional WPL copies in the Windows folder Music → Playlists. Before rebuilding, back up the WMP catalogue and archive old, clearly identified import copies outside monitored folders; rebuilding the database alone would index them again. Original media and playlists are retained.

Media files on the SMB share did not work as a WMP DLNA library in our test, even via the network drive Y:. The service could read an original file and Samba already allowed reading and writing, but the shared media catalogue remained empty. This finding applies to the network source checked here, not every SMB configuration. Local files are covered by the separate local check.

Windows Offline Files were not used, since they create a synchronized local copy. After restarting the service, WMP’s device description and UPnP root were accessible again in about three seconds in our check. A server entry missing initially does not automatically require rebuilding its library.

Manufacturer documentation

Gerbera configuration

Gonic: music folders

MinimServer: Configuration

MariaDB: alter database columns