crossonic

README

Crossonic Server

OpenSubsonic compatible music server with additional extensions for Crossonic.

Status

This project is in development. Expect bugs and missing features.

Not all OpenSubsonic endpoints have been implemented yet (status). This server implements all endpoints needed for the Crossonic app but may not yet work without issues with other Subsonic media players.

Features

• media library scan
  • on startup
  • startScan endpoint
  • incremental scan
  • file watching
• ListenBrainz integration
  • scrobbling
  • sync favorites
• Multiple users
  • per-user internet radio stations
• Transcoding and caching
  • configurable with format= and maxBitRate= parameters
  • raw, mp3, opus, vorbis
• Fetch artist images and artist/album info from last.fm
• Multiple artists, album artists, genres
• Stores a unique ID in the metadata of all media files to preserve IDs when moving/renaming files on disk
• Scrobbling including playback duration
• Browse by tags
  • browsing by folders not supported (getIndexes, getMusicDirectory etc. simulate behavior based on tags)
• Favorites/rating
• Lyrics
  • unsynced
  • synced
• Multiple music directories
• Playlists
  • including user-changable playlist covers (not natively supported by OpenSubsonic)
• Jukebox
  • device selection
  • SONOS casting
• Serve Crossonic Web
• Admin CLI
• Admin web interface
• End-of-year recap
  • total listening duration
  • distinct song, album, artist count
  • ranked songs, albums, artists by listening duration

Deploy with Docker

Create docker-compose.yml:

services:
  crossonic:
    image: ghcr.io/juho05/crossonic-server
    restart: unless-stopped
    environment:
      DB_USER: crossonic
      DB_PASSWORD: crossonic
      DB_HOST: db
      DB_PORT: 5432
      DB_NAME: crossonic
      # Base64 encoded string representing exactly 32 bytes.
      # Generate with: docker run --rm -it --entrypoint crossonic-admin ghcr.io/juho05/crossonic-server gen-encryption-key
      ENCRYPTION_KEY: <key>
      # URL where crossonic-server is reachable
      BASE_URL: "https://crossonic.example.com"
    volumes:
      - "./cache:/cache"   # cache files
      - "./data:/data"     # cover art etc.
      - "./library:/music" # your music files
    ports:
      - "8080:8080"
    depends_on:
      - db
  db:
    image: postgres:16
    restart: unless-stopped
    volumes:
      - ./postgres:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: crossonic
      POSTGRES_USER: crossonic
    healthcheck:
      test: ["CMD", "pg_isready -U crossonic"]
      interval: 30s
      timeout: 20s
      retries: 3

Run docker compose up -d in the same directory as the docker-compose.yml file.

Create user

To create a user use the following command from the directory of your docker-compose.yml file:

docker compose exec -it crossonic crossonic-admin users create <name>

License

Copyright (c) 2024-2025 Julian Hofmann

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Documentation

Index

• Variables
• func GenIDAlbum() string
• func GenIDArtist() string
• func GenIDInternetRadioStation() string
• func GenIDPlaylist() string
• func GenIDSong() string
• func IsIDType(id string, idType IDType) bool
• type IDType
  • func GetIDType(id string) (IDType, bool)

Variables

var (
	ServerName = "crossonic-server"
	Version    = "dev"
)

var GenID func() string

var IDAlphabet = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-~"

var IDRegex = regexp.MustCompile(fmt.Sprintf("^(tr)|(al)|(ar)|(pl)|(irs)_[%s]{12}$", strings.ReplaceAll(IDAlphabet, "-", "\\-")))

var MigrationsFS fs.FS

Functions

func GenIDAlbum

func GenIDAlbum() string

func GenIDArtist

func GenIDArtist() string

func GenIDInternetRadioStation

func GenIDInternetRadioStation() string

func GenIDPlaylist

func GenIDPlaylist() string

func GenIDSong

func GenIDSong() string

func IsIDType

func IsIDType(id string, idType IDType) bool

Types

type IDType

type IDType string

const (
	IDTypeSong                 IDType = "tr"
	IDTypeAlbum                IDType = "al"
	IDTypeArtist               IDType = "ar"
	IDTypePlaylist             IDType = "pl"
	IDTypeInternetRadioStation IDType = "irs"
)

func GetIDType

func GetIDType(id string) (IDType, bool)