Shanty/Main
1
0
Fork 0
Code Issues 9 Pull Requests Actions 1 Packages Projects Releases Wiki Activity

documentation
CI / check (push) Successful in 1m29s
Details
CI / docker (push) Successful in 1m57s
Details

Browse Source
This commit is contained in:
Connor Johnstone
2026-03-23 16:17:01 -04:00
parent c7110fbbe7
commit 53b3a644a1
12 changed files with 1518 additions and 157 deletions
Download Patch File Download Diff File Expand all files Collapse all files
readme.md
+59 -147
View File
@@ -1,172 +1,84 @@
# shanty
# 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.
Shanty is a self-hosted music management application. It searches MusicBrainz for artists and albums, downloads music from YouTube, tags and organizes files, and serves your library over the Subsonic protocol for streaming on any device.
## 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)
- **Watch** artists or albums to track their full discography at the individual track level
- **Download** music via yt-dlp with YouTube Music search
- **Tag** files automatically using MusicBrainz metadata
- **Organize** files into clean directory structures with configurable templates
- **Web UI** — Yew (Rust/WASM) dashboard with real-time status, search, library browser
- **Stream** your library to any Subsonic-compatible music app
- **Playlists** generated from similar-artist data (Last.fm), with drag-and-drop editing and M3U export
- **Monitor** artists for new releases, automatically added to your watchlist
- **Web UI** built in Rust/WASM for managing everything from your browser
## Architecture
## Quick Start with Docker
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.
This is the recommended way to run Shanty.
| 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`:
**1.** Create a file called `docker-compose.yml`:
```yaml
library_path: ~/Music
download_path: ~/.local/share/shanty/downloads
organization_format: "{artist}/{album}/{track_number} - {title}.{ext}"
services:
shanty:
image: git.squid-inc.dev/connor/shanty:latest
ports:
- "8085:8085"
- "6080:6080"
volumes:
- ./config:/config
- shanty-data:/data
- /path/to/your/music:/music
environment:
- SHANTY_WEB_BIND=0.0.0.0
restart: unless-stopped
# 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
volumes:
shanty-data:
```
## Docker
**2.** Replace `/path/to/your/music` with the directory where you want your music library stored.
### Quick start
**3.** Start the container:
```sh
# Edit compose.yml to set your music library path, then:
docker compose up -d
```
**4.** Open `http://localhost:8085` in your browser. Create an account on first launch.
**5.** Search for an artist, click **Watch All**, then click **Set Sail** to start downloading.
## Quick Start from Source
For developers who want to build and run locally:
```sh
# Prerequisites: Rust (edition 2024), yt-dlp, ffmpeg, Python 3, ytmusicapi, Trunk
git clone https://git.squid-inc.dev/connor/shanty.git
cd shanty
# Build frontend
cd shanty-web/frontend && trunk build --release && cd ../..
# Build and run
cargo run --release --bin shanty -- -v
# Open http://localhost:8085
```
### Build from source
## Documentation
```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
```
- [Getting Started](docs/getting-started.md) -- step-by-step setup guide
- [Configuration Reference](docs/configuration.md) -- all config options and environment variables
- [API Reference](docs/api.md) -- REST and Subsonic API documentation
- **Feature Guides:**
- [YouTube Authentication](docs/features/youtube-auth.md) -- higher rate limits with cookie auth
- [MusicBrainz Local Database](docs/features/musicbrainz-db.md) -- instant metadata lookups
- [Subsonic Streaming](docs/features/subsonic.md) -- mobile and desktop playback
- [Playlists](docs/features/playlists.md) -- generation, editing, and export
- [Monitoring](docs/features/monitoring.md) -- automatic new release detection
## License