Soulsolid

A work in progress, feature rich music organization app built for the music hoarder. Heavily under development, focused on ease of usage and start up. Feel free to check the docs or demo

See the deepwiki

Screenshots

Features

• Music Library Management: Organize and browse albums, artists, and tracks
• Downloading: Download tracks and albums.
• Importing: Import music from directories with automatic fingerprinting
• Metadata Tagging: Auto-tag using MusicBrainz and Discogs APIs
• Telegram Integration: Control via Telegram bot
• Web UI: Mobile-friendly interface for all operations
• Job Management: Background processing for downloads, imports, and synced lyrics and more.

Documentation: https://soulsolid.contre.io Demo: https://soulsolid-demo.contre.io

Quick Start

🦭 Container Usage

The application can run without copying config.yaml into the container. If no config file exists, it will automatically create one with sensible defaults.

Environment Variable Support

Soulsolid supports environment variables in configuration files using the !env_var tag:

telegram:
  token: !env_var TELEGRAM_BOT_TOKEN
metadata:
  providers:
    discogs:
      secret: !env_var DISCOGS_API_KEY

The application will fail to start if a referenced environment variable is not set.

Build and/or run it

# Build the image
podman build -t soulsolid .
# Create folders
mkdir downloads logs data confg
# Run with docker/podman
podman run -d --name soulsolid -p 3535:3535 \
  -v ./music:/app/library \
  -v ./downloads:/app/downloads \
  -v ./logs:/app/logs \
  -v ./data:/data/ \
  -v ./config:/config contre95/soulsolid:v0.22.1

The web interface will be available at http://localhost:3535.

Development

To set up the development environment:

Option 1: Manual Setup

cp config.example.yaml config.yaml
npm run dev
go run ./src/main.go

Option 2: Using devenv (recommended)

If you have devenv installed, it sets up every dependency (Go, Node.js, TailwindCSS, chromaprint, flac, id3v2, ...) and builds the frontend assets for you:

# Enter the dev shell (installs deps, creates config.yaml, builds assets)
devenv shell
# Then run the app:
go run ./src/main.go

Or start everything (asset build + server) in one command:

devenv up

To activate the environment automatically when you cd into the project, install direnv and run direnv allow once (uses the included .envrc).

The web interface will be available at http://localhost:3535.