shanty

A modular, self-hosted music management application for the high seas. Shanty aims to be a better alternative to Lidarr — managing, tagging, organizing, and downloading music, all built as a collection of standalone Rust tools that work together seamlessly through a web UI.

Features

• Search MusicBrainz for artists, albums, and tracks
• Watch artists/albums — automatically expands to individual track-level monitoring
• Download music via yt-dlp with YouTube Music search (ytmusicapi)
• Tag files with MusicBrainz metadata (fuzzy matching + MBID-based lookup)
• Organize files into clean directory structures with configurable templates
• Web UI — Yew (Rust/WASM) dashboard with real-time status, search, library browser

Architecture

Shanty is a Cargo workspace where each component is its own crate and git submodule. Each crate is both a library (for the web app) and a standalone CLI binary.

Crate	Description	Status
shanty-db	Sea-ORM + SQLite schema, migrations, queries	Done
shanty-index	Music file scanning and metadata extraction (lofty)	Done
shanty-tag	MusicBrainz client, fuzzy matching, file tag writing	Done
shanty-org	File organization with configurable format templates	Done
shanty-watch	Watchlist management, MB discography expansion	Done
shanty-dl	yt-dlp backend, rate limiting, download queue	Done
shanty-search	SearchProvider trait, MB search + release groups	Done
shanty-web	Actix backend + Yew frontend	Done (MVP)
shanty-notify	Notifications (Apprise, webhooks)	Stub
shanty-playlist	Playlist generation	Stub
shanty-serve	Subsonic-compatible music streaming	Stub
shanty-play	Built-in web player	Stub

Quick Start

Prerequisites

• Rust (edition 2024)
• yt-dlp + ffmpeg
• Python 3 + pip install ytmusicapi
• Trunk (for building the frontend)

Build

# Backend (all crates)
cargo build --workspace

# Frontend (Yew/WASM)
cd shanty-web/frontend && trunk build

Run the web app

cargo run --bin shanty-web -- -v
# Open http://localhost:8085

CLI tools

Each crate also works as a standalone CLI:

# Index a music directory
cargo run --bin shanty-index -- /path/to/music -v

# Tag untagged tracks
cargo run --bin shanty-tag -- --all --write-tags -v

# Search MusicBrainz
cargo run --bin shanty-search -- artist "Pink Floyd"

# Add to watchlist (expands album to individual tracks)
cargo run --bin shanty-watch -- add album "Green Day" "Dookie"

# Sync watchlist to download queue and process
cargo run --bin shanty-dl -- queue sync -v
cargo run --bin shanty-dl -- queue process -v

# Organize files
cargo run --bin shanty-org -- --from-db --target ~/Music -v

Full pipeline (CLI)

shanty-watch add album "Green Day" "Dookie" --mbid <release-mbid>
shanty-dl queue sync -v
shanty-dl queue process -v
shanty-tag --all --write-tags -v
shanty-org --from-db --target ~/Music -v

Configuration

Create ~/.config/shanty/config.yaml:

library_path: ~/Music
download_path: ~/.local/share/shanty/downloads
organization_format: "{artist}/{album}/{track_number} - {title}.{ext}"

# Filter which release types to show (empty = studio only)
# Options: Compilation, Live, Soundtrack, Remix, DJ-mix, Demo
allowed_secondary_types: []

web:
  port: 8085
  bind: 0.0.0.0

tagging:
  write_tags: true
  confidence: 0.85

download:
  format: opus
  search_source: ytmusic
  # cookies_path: ~/.config/shanty/cookies.txt  # for higher YT rate limits

Docker

Quick start

# Edit compose.yml to set your music library path, then:
docker compose up -d
# Open http://localhost:8085

Build from source

docker build -t shanty .
docker run -d \
  -p 8085:8085 \
  -v ./config:/config \
  -v shanty-data:/data \
  -v /path/to/music:/music \
  shanty

Volumes

Mount	Purpose
/config	Config file (config.yaml)
/data	Database (shanty.db) and downloads
/music	Your music library

Environment variables

Variable	Default	Description
SHANTY_CONFIG	/config/config.yaml	Config file path
SHANTY_DATABASE_URL	sqlite:///data/shanty.db?mode=rwc	Database URL
SHANTY_LIBRARY_PATH	/music	Music library path
SHANTY_DOWNLOAD_PATH	/data/downloads	Download directory
SHANTY_WEB_PORT	8085	HTTP port
SHANTY_WEB_BIND	0.0.0.0	Bind address

Testing

cargo test --workspace

License

MIT