Main/readme.md

Shanty

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

Quick Start with Docker

This is the recommended way to run Shanty.

1. Create a file called docker-compose.yml:

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

volumes:
  shanty-data:

2. Replace /path/to/your/music with the directory where you want your music library stored.

3. Start the container:

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:

# 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

Documentation

• Getting Started -- step-by-step setup guide
• Configuration Reference -- all config options and environment variables
• API Reference -- REST and Subsonic API documentation
• Feature Guides:
  • YouTube Authentication -- higher rate limits with cookie auth
  • MusicBrainz Local Database -- instant metadata lookups
  • Subsonic Streaming -- mobile and desktop playback
  • Playlists -- generation, editing, and export
  • Monitoring -- automatic new release detection

License

MIT