An OpenSubsonic server written in Rust with song uploads and OpenMusicMetadata tagging. docs.vleer.app/juuz
Files
README.md
Juuz

juuz

An OpenSubsonic server written in Rust with song uploads and OpenMusicMetadata tagging.


Screenshot 2026-10-17 at 04-10-52 Juuz

Features #

  • Song upload: apps can save downloaded music straight to the server instead of the device, with covers, lyrics and tag fixing included
  • OpenSubsonic API 1.16.1, JSON and XML, tested with Feishin and Arpeggi
  • Every login style works for every user: password, token (can be switched off), API key
  • Song, album and artist matching through OpenMusicMetadata exposed as ommId, missing years, genres and artwork filled in without touching the files, wrong matches fixable by hand
  • Songs identified by audio, so renaming or moving files keeps stars, playlists and history
  • Last.fm scrobbling and now playing, linked per user
  • Embedded lyrics and .lrc files first, then synced lyrics from LRCLIB
  • Albums and compilations grouped correctly without an album artist tag
  • Multiple libraries with per-user access and permission roles
  • Live SQLite library that watches the music folders
  • Opus, MP3 and AAC transcoding (format=opus, mp3, aac) in pure Rust, no ffmpeg
  • Shares, internet radio, play queue, bookmarks
  • Jukebox: the server plays to DLNA, AirPlay or Snapcast speakers, alone or as a synced group; any jukeboxControl app (Feishin) acts as the remote
  • Web UI: a keyboard-driven terminal-style interface with a library browser and player, playlists, stats, users and server settings

Installation #

Save this as docker-compose.yml, point /music at the music folder and run docker compose up -d.

services:
  juuz:
    image: ghcr.io/vleerapp/juuz:latest
    restart: unless-stopped
    ports:
      - "4533:4533"
      - "1704:1704" # snapcast speakers
    environment:
      JUUZ_ADMIN_PASSWORD: replace-with-a-long-random-password # first start only, random and logged if unset
      JUUZ_PUBLIC_URL: "https://juuz.example.com" # base url for share links, default from request
      JUUZ_TRUST_PROXY: false # set true only behind a reverse proxy that is the sole way to reach the port, then X-Forwarded-For is used as the client ip
      JUUZ_TOKEN_AUTH: true # false turns off md5 token auth (t+s) and deletes the stored password secrets, apps must use an api key or a plain password
      JUUZ_RATE_LIMIT: 1800 # requests per minute per ip, 0 turns it off
      JUUZ_OMM: "true" # false stops sending track names to OpenMusicMetadata
      JUUZ_LASTFM_API_KEY: "" # scrobbling is off without it
      JUUZ_LASTFM_SECRET: ""
    volumes:
      - data:/data
      - /path/to/your/music:/music # first library
      - /mnt/family-nas/music:/libraries/family # more libraries go outside /music, add the path on the server page. admins can add any folder, other users with the library role only folders under /libraries

volumes:
  data:

The server runs on port 4533. The music folder must be writable by uid 1000, since uploads are saved there.

For Last.fm, create an API account at last.fm/api, set both variables and restart. Each user then links their account on the account page.

Jukebox outputs #

Play to DLNA, AirPlay and Snapcast speakers or to another browser you have open, from the web UI or any jukeboxControl app. Combine outputs into synced groups with a delay per member, and the queue, volume and output stay in sync across every open device.

Docker needs host networking to discover DLNA and AirPlay receivers. For Snapcast, publish port 1704, or set JUUZ_SNAPCAST=false to turn it off.

Apps can find these extensions with getOpenSubsonicExtensions, everything else is the standard jukeboxControl:

  • juuzJukeboxOutput lists and selects outputs and builds groups (juuzGetJukeboxOutputs, juuzSetJukeboxOutput, juuzSetJukeboxGroup)
  • juuzJukeboxEvents is a live stream of the playback state
  • juuzJukeboxQueue reorders the queue (juuzJukeboxMove)

Song upload Extension #

An app sends a file to juuzUploadSong with an API key (juuzCreateApiKey). The server writes the tags, saves the file and indexes it right away.

curl -F file=@track.flac \
  "http://localhost:4533/rest/juuzUploadSong?f=json&apiKey=$KEY&title=Song&artist=Artist&album=Album&track=1&year=2020"
music/
└── Artist/
    └── 2020 - Album/
        └── 01 - Song.flac
  • Tags: title, artist, albumArtist, album, track, disc, year, genre
  • Missing tags are filled from relativePath or ommId
  • Cover: kind=cover&albumId=…
  • Lyrics: kind=lyrics&songId=…
  • Delete: juuzDeleteSong?id=…
  • Library: musicFolderId=<id>
  • Same song twice returns "status": "duplicate"
  • Needs the upload role