133 lines
3.7 KiB
Markdown
133 lines
3.7 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
|
|
```
|
|
|
|
## Testing
|
|
|
|
```sh
|
|
cargo test --workspace
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|