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

```yaml
services:
  shanty:
    image: git.rcjohnstone.com/connor/shanty:latest
    ports:
      - "8085:8085"
      # - "6080:6080"  # Optional: expose if YouTube login iframe doesn't load
    volumes:
      - ./config:/config
      - ./data:/data
      - /path/to/your/music:/music
    environment:
      - SHANTY_WEB_BIND=0.0.0.0
    restart: unless-stopped
```

**2.** Replace `/path/to/your/music` with the directory where you want your music library stored. The `./data` directory will be created automatically and stores the database, downloads, and any imported MusicBrainz data. If you plan to use the [local MusicBrainz database](docs/features/musicbrainz-db.md), put this on an SSD.

**3.** Start the container:

```sh
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.rcjohnstone.com/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](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

MIT