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

Testing

cargo test --workspace

License

MIT