Apps send a file to juuzUploadSong. juuz writes the tags, saves the file in the music folder and indexes it right away, so it shows up in every client without a rescan.

POST /rest/juuzUploadSong
Content-Type: multipart/form-data

curl -F file=@track.flac \
  "http://localhost:4533/rest/juuzUploadSong?f=json&apiKey=$KEY&title=Song&artist=Artist&album=Album&track=1&year=2020"

The user needs the upload role, and uploads must not be disabled. Authenticate with an API key or with u plus p or t and s. Parameters can go in the query string or as text fields before the file part.

ParametersCopy Anchor Link

Missing tags are filled from the file's own tags, then from OpenMusicMetadata (unless JUUZ_OMM is off), and finally guessed from relativePath or the original file name. Tags you pass always win. preferOmm only lets OpenMusicMetadata replace tags that are already in the file.

A form can have at most 64 text fields of 8 KiB each. Send them before the file part, fields after it are ignored.

Where files goCopy Anchor Link

music/
└── Artist/
    └── 2020 - Album/
        └── 01 - Song.flac

Supported formats are FLAC, MP3, M4A, AAC, Opus, Ogg Vorbis, WAV, AIFF and WavPack. The format is detected from the content, not the file name.

Covers and lyricsCopy Anchor Link

curl -F file=@cover.jpg \
  "http://localhost:4533/rest/juuzUploadSong?f=json&apiKey=$KEY&kind=cover&albumId=$ALBUM"

curl -F file=@song.lrc \
  "http://localhost:4533/rest/juuzUploadSong?f=json&apiKey=$KEY&kind=lyrics&songId=$SONG"

• Cover: a JPEG, PNG or WebP of up to 10 MiB, saved as cover.<ext> in the album folder. It replaces the old cover.
• Lyrics: UTF-8 text of up to 1 MiB, saved next to the song. Text with [mm:ss] timestamps becomes a .lrc file, anything else a .txt file.

ResponseCopy Anchor Link

{
  "subsonic-response": {
    "status": "ok",
    "juuzUploadResult": {
      "status": "created",
      "song": { "id": "...", "title": "Song" }
    }
  }
}

status is created, or duplicate if the same song is already in the library. song is a regular OpenSubsonic song object. Cover uploads return {"status": "created", "kind": "cover", "albumId": "..."} and lyrics uploads {"status": "created", "kind": "lyrics", "songId": "..."}.

ErrorsCopy Anchor Link