Nghe

An implementation of OpenSubsonic API in Rust

• Nghe
  • Features
  • Getting started
  • Client
  • Configuration
    • Server
    • Database
    • Artist
    • Parsing
      • Song
      • Album
      • Id3v2
      • Number and total
    • Scan
    • Transcoding
    • Art
    • S3
  • Scan process
    • How a song is uniquely identified ?
    • Scan mode
      • Quick
      • Full
      • Force
    • How an artist is uniquely identified ?
    • How an album is uniquely identified ?
  • Permission model
    • Access to a song-level resource
    • Access to an artist or album level resource
  • Compilation album
  • Roadmap

Features

• Written in Rust with performance in-mind.
• All tags are multiple by default (artists, album artists, languages, etc).
• Well-tested and highly customizable.
• Well-defined permission model with music folders.
• Multi-platform, runs on Linux, FreeBSD, MacOS and Windows. Docker images with two variants GNU or MUSL are also provided.
• Bridging with ffmpeg c api for in-memory transcoding and smooth stream experience. Most common formats (opus, mp3, acc, wav, etc) are supported. Does not required any manual configuration beforehand, just maxBitRate and format in the request parameters are enough.
• Synchoronized lyrics from external lrc files.
• AWS S3 compatible storage support. Tested with Minio for every commit.

Getting started

The easiest way for getting started is using docker. Below is a docker-compose.yaml example. A random hex key can be generated using openssl rand -hex 16.

services:
  nghe:
    image: ghcr.io/vnghia/nghe-musl:0.3.0
    ports:
      - "3000:3000"
    restart: unless-stopped
    environment:
      NGHE_DATABASE__URL: postgres://postgres:postgres@db:5432/postgres
      NGHE_DATABASE__KEY: a20eb15ac92cabfd96b81fb154b16357
    volumes:
      - /your-music-folder/:/data/music/:ro
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

The minimum required postgres version is 16. Alternatively, you can also download corresponding binary with your OS and the frontend package in the release section.

Once the server is running, go to [your-server-url]/setup to setup a first admin account. After that, login and go to the folders menu on the right side of the screen. You can add a new music folder from there, hit the scan button, choose one scan mode (more detail in scan process) and start using the server while your media files are being scanned.

Client

This server works best with Symfonium and Airsonic since they support multiple values well enough.

Configuration

All configurations can be set by environment variable with a NGHE_ prefix and a __ between each level of inheritance. For example, the config database.url is correspondent to NGHE_DATABASE__URL.

Server

Database

Artist

Parsing

Parsing config allows you to tells the server exactly where to read your songs metadata. Currently, belows tags are supported.

Song

Some fields in this table are not official and usually used to distinguish between date-related information of albums and songs. If you have don't have that information, just leave it as default.

Album

Id3v2

Id3v2 key is treated as two different ways depending on its length:

• If you supply a 3 or 4 characters string, it will be treated as a frame id. For example TIT2.
• Otherwise, it will be treated as an user text key in the frame TXXX. For example "MusicBrainz Release Track Id".

In additional to those configurations above, id3v2 also has below configuration.

Number and total

You can set track/disc number and total by three ways below:

• Setting fields track_number, track_total, etc normally. Unfortunately this does not work on id3v2.
• Using only track_number and set it to {track_number}/{track_total}. This sets track_number and track_total to the corresponding numbers after spliting and works with all formats. The same thing holds for disc_number.
• Using only track_number and set it to {character}{track_number} like A1, B10. This sets the disc_number to the order of that character in the alphabet and track_number to the following number. track_total and disc_total will be none. This format is encountered while parsing vinyl records.

Scan

Scan process has two main threads, one thread (the walking thread) will be responsible for walking directories in the filesystem and send back the result to the second thread (the parsing thread), who is responsible for parsing each file and updating information in the database. More in scan process.

You should tweak this carefully to find the optimized value for your system. Sometimes, running concurrently is not the fastest option.

Transcoding

Art

Lastfm

Spotify

S3

Credentials, region and endpoint configurations should be set by standard AWS environment variables. Authentication by profile and imds are also supported.

Scan process

How a song is uniquely identified ?

A song is uniquely identified either by:

• Its music folder and relative path (to its music folder).
• Its music folder, hash and size. It means that you can not have duplicated songs in the same music folder. If a duplicated songs is detected, the path will be updated to the latest encountered path. It allows you to move freely your songs in the same music folder, only its path will be updated in the database.

Duplication on two different music folders are is allowed and will be treated as two seperate songs.

Scan mode

Quick

The song will be first checked by its last modified time and then process the same as full if its updated at time is sooner or it hasn't been added into the database. Otherwise mark it as scanned and move to the next song. This mode is particularly useful for cloud storage service.

Full

As describe above, if an already identified song is scanned (by checking relative path, hash and size), the scanning process will just mark the file as scanned and skip that file. In the end of the scanning process, all old songs and related informations (artists/albums/genres/etc) inside that music folder that are not scanned will be deleted.

Force

Same as full but will try parsing the file regardless if it is identified or not. This mode is useful if there are new metadata that added into the scanning process.

How an artist is uniquely identified ?

An artist is uniquely identified either by:

• Their musicbrainz id
• Their name if their musicbrainz id is empty.

If you have duplicated artists shown in your client, you should check for the corresponding musicbrainz id field.

How an album is uniquely identified ?

An album is uniquely identified either by:

• Their musicbrainz id
• Their name, date, release date, original release date if their musicbrainz id is empty.

If you have duplicated albums shown in your client, you should check for the corresponding musicbrainz id and date fields.

Permission model

As describe in scan process, songs are tied to a specific music folder but artists and albums are globally identified. There will be two scenarios.

Access to a song-level resource

In this case, user is either allowed or denied depending on their allowed music folders. Song-level resource is the song itself, the lyrics, the cover art.

Access to an artist or album level resource

In this case, user will only see a combination of allowed song-level resources, not the whole thing.

For example, if an artist has 10 songs in folder1 and 20 songs in folder2:

• User with permission on both folders will see that artist has 30 songs.
• User with permission on folder1 will only see first 10 songs.
• User with permission on folder2 will only see last 20 songs.
• User with no permission on both folder will not see the artist in the first place and get a not found error if they are trying to access it by manully specifying the id.

The same thing holds true for albums. For example, if an album has 2 songs in 2 folders with different cover arts:

• User with permission on both folders will see the first cover art sorted by the smallest disc number and track number (track 1 disc 1 of the album).
• User with permission on folder1 will only see the first cover art.
• User with permission on folder2 will only see the second cover art.

Nested music folder

Nested music folders are allowed and each folder will be treated as a separate unrelated folder.

Configuration

Permission configuration can be found in the folders menu of the frontend.

Compilation album

If a song has compilation tag, its album will be added to the list of albums of each artist in its artists tag (not to be confused with album artists). For example, if a song has album named "album", compilation enabled, 2 artists "artist1", "artist2" and 1 album aritst "various artists", all of these 3 artists will have album "album" in their information. However, when accessing by album id, only album artists ("various artists" in this case) will be shown in the aritst fields.

Roadmap

• More compatible with Opensubsonic API.
• Fully-feature frontend.
• SQL playlist builder.
• Possibly integrating local machine learning model (like how Immich is doing with image/videos).