skaldi

README

Skaldi

Self-hosted network jukebox. One Go binary, one embedded web UI, zero external Go dependencies.

Runs mpv locally, serves a browser UI on your LAN, and provisions self-contained yt-dlp + bun runtimes into ~/.cache/skaldi/ on first run. No system Python or package manager required.

Features

• Queue URLs or upload local files
• Search YouTube and YouTube Music
• Optional OpenSubsonic library search
• Real-time state sync over SSE
• Queue reordering, history, volume, mute
• mDNS advertising at skaldi.local

Requirements

• mpv, ffmpeg
• Go 1.26+ to build from source

brew install mpv ffmpeg                  # macOS
sudo pacman -S mpv ffmpeg avahi          # Arch
sudo apt install mpv ffmpeg avahi-utils  # Debian/Ubuntu

Quick Start

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

Listens on http://localhost:8080 (LAN URL logged on startup). First run needs network access to provision yt-dlp + bun.

Configuration

Env overrides config; config overrides defaults. Config at $XDG_CONFIG_HOME/skaldi/config.json (or SKALDI_CONFIG).

Setting	Env	config.json	Default
Listen port	SKALDI_PORT	server.port	8080
Provision	SKALDI_PROVISION=0	provision: false	on

Provisioning bypass — set SKALDI_PROVISION=0 and put yt-dlp + bun on PATH (alongside mpv, ffmpeg). Skaldi uses them directly and skips all downloads.

NixOS

Flake ships a self-contained package and a NixOS module. The packaged binary is wrapped with mpv, ffmpeg, yt-dlp, bun, avahi from the store and runs with SKALDI_PROVISION=0 — never downloads anything.

nix run github:reuski/skaldi

{
  inputs.skaldi.url = "github:reuski/skaldi";

  # in your nixosConfiguration modules:
  imports = [ skaldi.nixosModules.default ];

  services.skaldi = {
    enable = true;
    openFirewall = true;
    settings = {
      server.port = 8080;
      # opensubsonic = { enabled = true; library_id = "personal"; ... };
    };
  };

  services.avahi.enable = true; # for skaldi.local
}

Runs under a hardened DynamicUser, joined to the audio group for ALSA. PipeWire/PulseAudio may need extra wiring — override systemd.services.skaldi.environment (e.g. PULSE_SERVER) or serviceConfig.SupplementaryGroups.

OpenSubsonic

Optional. Enable via config.json:

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

Security

Designed for trusted networks. No authentication — do not expose directly to the internet.

License

AGPL-3.0. See LICENSE.