skaldi

README

Skaldi

Self-hosting network jukebox. Single Go binary, web UI, auto-provisions dependencies.

Install

# macOS
brew install mpv ffmpeg

# Arch
sudo pacman -S mpv ffmpeg avahi

# Debian/Ubuntu
sudo apt install mpv ffmpeg avahi-utils

Build & Run

Requires Go 1.26 or later.

go build -o skaldi ./cmd/skaldi
./skaldi

First run auto-installs uv, bun, yt-dlp to ~/.cache/skaldi/.

Features

• Queue: YouTube URLs, direct file uploads (drag-drop or paste)
• Search: YouTube + YouTube Music with autocomplete
• External Library: OpenSubsonic personal library integration
• Sync: Real-time SSE state updates
• Discovery: Auto-registers as skaldi.local via mDNS
• Audio: Dynamic range compression via dynaudnorm

Config File (OpenSubsonic)

Create config.json at:

• Linux/macOS default: ~/.config/skaldi/config.json
• Or ${XDG_CONFIG_HOME}/skaldi/config.json

Example:

{
  "opensubsonic": {
    "enabled": true,
    "library_id": "personal",
    "base_url": "https://navidrome.example.com",
    "username": "alice",
    "token": "server_token_secret",
    "timeout_ms": 2500
  }
}

Notes:

• Missing/empty config disables external search silently.
• Invalid enabled config fails fast on startup.
• External cover art is deferred in v1; placeholder thumbnails are shown.

API

Method	Path	Description
GET	/	Web UI
GET	/events	SSE stream
GET	/suggest?q={query}	Autocomplete suggestions
GET	/search?q={query}&mode=typeahead	Text suggestions + external track hits
GET	/search?q={query}&mode=full	Merged track search (OpenSubsonic + YT Music + YouTube)
POST	/queue	Add URL {"url":"..."}
DELETE	/queue/{index}	Remove item
POST	/playback	Control {"action":"pause\|resume\|skip\|previous\|play"}
POST	/upload	File upload (multipart/form-data)

/search response shape:

{
  "suggestions": ["query text", "another"],
  "tracks": []
}

Security

No authentication. Exposing to the internet allows arbitrary uploads and RCE via media parsers. Run only on trusted networks.

Development

just all    # lint, test, build
just lint   # gofmt, golangci-lint, go vet
just test   # go test -v -race ./internal/...
just vuln   # govulncheck

See AGENTS.md for architecture guidelines.

License

AGPL-3.0 - See LICENSE