# 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](https://github.com/yt-dlp/yt-dlp) + ffmpeg
- Python 3 + `pip install ytmusicapi`
- [Trunk](https://trunkrs.dev/) (for building the frontend)

### Build

```sh
# Backend (all crates)
cargo build --workspace

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

### Run the web app

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

### CLI tools

Each crate also works as a standalone CLI:

```sh
# 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)

```sh
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`:

```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

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

### Build from source

```sh
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

```sh
cargo test --workspace
```

## License

MIT