174 lines
4.6 KiB
Markdown
174 lines
4.6 KiB
Markdown
# 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
|