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
docs/features/monitoring.md
+82
View File
@@ -0,0 +1,82 @@
# Artist Monitoring
Monitoring lets Shanty automatically detect when your favorite artists release new music. When a new album or single is found, it is added to your watchlist and queued for download.
## How monitoring differs from watching
- **Watching** an artist means you have added some or all of their existing discography to your watchlist. Watched tracks go through the download pipeline.
- **Monitoring** an artist means Shanty periodically checks MusicBrainz for new releases that were not in the artist's discography when you first added them. When something new appears, it is automatically added to your watchlist.
You can watch an artist without monitoring them (just download their existing catalog), and you can monitor a watched artist to stay up to date with new releases.
## How to set up
1. Open the Shanty web UI and navigate to an artist's page (search for them or open them from your library).
2. Click the **Monitor** button on the artist page.
3. The artist is now monitored. A badge indicates their monitoring status.
To stop monitoring an artist, click the **Monitor** button again to toggle it off.
## How it works
When monitoring is enabled, Shanty runs a background check on a schedule:
1. For each monitored artist, it fetches the current list of release groups from MusicBrainz.
2. It compares this against the release groups already in the watchlist.
3. Any new release groups (albums, singles, EPs) are expanded into individual track wanted_items and added to the watchlist.
4. The artist's `last_checked_at` timestamp is updated.
If you have the pipeline scheduler enabled (the default), new releases are automatically downloaded on the next pipeline run.
## Automatic scheduling
Both the monitor check and the download pipeline run on configurable schedules:
| Task | Default interval | Config key |
|------|-----------------|------------|
| Monitor check | Every 12 hours | `scheduling.monitor_interval_hours` |
| Pipeline (Set Sail) | Every 3 hours | `scheduling.pipeline_interval_hours` |
This means that in the default configuration:
1. The monitor checks for new releases every 12 hours.
2. If new releases are found, they are added to the watchlist.
3. Within 3 hours, the pipeline runs automatically, downloading and processing the new tracks.
## Configuring schedules
In your config file:
```yaml
scheduling:
pipeline_enabled: true
pipeline_interval_hours: 3
monitor_enabled: true
monitor_interval_hours: 12
```
Or adjust these settings in the web UI under **Settings**.
To disable automatic scheduling entirely:
```yaml
scheduling:
pipeline_enabled: false
monitor_enabled: false
```
When disabled, you can still trigger checks manually from the Dashboard.
## Manual checks
You can trigger a monitor check at any time from the Dashboard by clicking **Check Monitored** (under the system actions). The results show how many artists were checked, how many new releases were found, and how many tracks were added.
Similarly, you can trigger the pipeline manually by clicking **Set Sail** at any time.
## Viewing monitored artists
The monitoring status is visible on each artist's page. You can also check the current monitor status via the API at `GET /api/monitor/status`, which returns a list of all monitored artists with their last check timestamps.
## Skipping scheduled runs
If you want to skip the next scheduled pipeline or monitor run without disabling them permanently, you can do so from the Dashboard. The skip is a one-time action -- the schedule resumes after the skipped run.
docs/features/musicbrainz-db.md
+80
View File
@@ -0,0 +1,80 @@
# MusicBrainz Local Database
MusicBrainz is the source of all music metadata in Shanty: artist information, album listings, track listings, and release data. By default, Shanty queries the MusicBrainz API over the internet, which is rate-limited to 1 request every 1.1 seconds.
Importing the MusicBrainz database locally eliminates this bottleneck for most lookups.
## What this does
The import downloads a full copy of the MusicBrainz database (as JSON dumps) and loads it into a local SQLite database on your machine. When Shanty needs to look up an artist's discography, release track listings, or recording details, it checks the local database first. If the data is found locally, the response is instant. If not (for example, very new releases), it falls back to the remote API.
## Why you might want this
Without the local database, browsing a new artist's full discography requires many API calls (one per release group, one per release to get track listings). With the rate limit, loading an artist with 15 albums can take 30-60 seconds.
With the local database, the same operation completes in under a second.
If you are casually using Shanty for a few artists, the caching system works well enough without the local database. But if you frequently browse and add new artists, the local database makes the experience dramatically faster.
## Requirements
- **Download size:** approximately 24 GB (compressed JSON dumps from MusicBrainz)
- **Database size:** approximately 16 GB (the resulting SQLite database)
- **Disk type:** SSD strongly recommended. The import writes millions of rows, which is very slow on spinning disks.
- **Time:** 12-24 hours for the initial import, depending on your hardware and disk speed.
- **Disk space total:** You need roughly 40 GB free during import (dumps + database). After import, you can delete the dump files to reclaim the 24 GB.
## How to set up via the web UI
1. Open the Shanty web UI and go to **Settings**.
2. Scroll to the **MusicBrainz Database** section.
3. Click **Import**.
4. Shanty downloads the dump files and imports them. Progress is shown on the Dashboard.
You can continue using Shanty while the import runs. It will use the remote API until the import completes.
## How to set up via the CLI
If you prefer the command line (or want to run the import on a more powerful machine):
```sh
# Inside Docker
docker compose exec shanty ./shanty mb-import --download
# From source
cargo run --release --bin shanty -- mb-import --download
```
Options:
- `--download` -- Download fresh dump files from metabrainz.org before importing. Without this flag, the import looks for existing dump files in the data directory.
- `--data-dir /path/to/dumps` -- Custom directory for dump files. Defaults to `{data_dir}/mb-dumps`.
The database is created at `{data_dir}/shanty-mb.db` by default. You can override this with the `musicbrainz.local_db_path` config option.
## Automatic weekly updates
MusicBrainz publishes new database dumps regularly. You can configure Shanty to automatically re-download and re-import them:
```yaml
musicbrainz:
auto_update: true
```
When enabled, Shanty checks weekly for new dumps and runs the import in the background if a newer dump is available. The existing local database continues to serve queries during the update.
## The hybrid approach
Shanty uses what it calls a "hybrid fetcher":
1. **Local database** is checked first for any MusicBrainz lookup (artist info, release groups, track listings, etc.).
2. **Remote API** is used as a fallback when data is not in the local database (new releases added after the last import, for example).
3. **Cache** is used for data that was fetched from the remote API, so repeated lookups do not hit the rate limit.
This means you get the best of both worlds: instant lookups for the vast majority of music that exists in the database dumps, and up-to-date data for newly released music via the API.
## Configuration options
| Option | Default | Description |
|--------|---------|-------------|
| `musicbrainz.local_db_path` | `{data_dir}/shanty-mb.db` | Path to the local SQLite database |
| `musicbrainz.auto_update` | `false` | Automatically re-import dumps weekly |
docs/features/playlists.md
+92
View File
@@ -0,0 +1,92 @@
# Playlists
Shanty can generate playlists from your library using similar-artist data from Last.fm. You can also create and edit playlists manually, export them as M3U files, and access them from Subsonic clients.
## Requirements
Playlist generation using the **similar-artist** strategy requires a Last.fm API key. Set it via the `SHANTY_LASTFM_API_KEY` environment variable:
```yaml
# In docker-compose.yml
environment:
- SHANTY_LASTFM_API_KEY=your_api_key_here
```
Get a free API key at: https://www.last.fm/api/account/create
Other playlist strategies (genre, random, smart rules) do not require an API key.
## Generating a playlist
1. Open the Shanty web UI and go to **Playlists**.
2. Click the **Generate** tab.
3. Choose a generation strategy:
- **Similar Artists** -- Start with one or more seed artists and build a playlist from their music and music by similar artists. This is the most useful strategy for discovering connections in your library.
- **Genre** -- Filter tracks by genre tags.
- **Random** -- A random selection from your library.
- **Smart Rules** -- Define rules based on track attributes (artist, album, year, genre, etc.).
4. For the Similar Artists strategy:
- Search for and select one or more **seed artists**.
- Adjust **popularity bias** (higher values favor well-known tracks, lower values dig deeper).
- Set the **track count** (how many tracks in the playlist).
- Choose **ordering**: interleave (mix artists evenly), score (highest match first), or random.
5. Click **Generate**.
The generated playlist is shown as a preview. You can then save it or adjust the parameters and regenerate.
## Saving a playlist
After generating a playlist, click **Save** to give it a name and store it. Saved playlists appear in the **Saved** tab.
## Editing a playlist
1. Go to the **Saved** tab in Playlists.
2. Click **Edit** on a playlist.
3. In the Edit tab, you can:
- **Drag and drop** tracks to reorder them.
- **Remove** tracks by clicking the remove button next to each track.
- **Add** tracks by searching in the track picker at the bottom.
- **Rename** the playlist or update its description.
## Exporting as M3U
To export a playlist as an M3U file (compatible with most music players):
1. Open a saved playlist.
2. Click **Export M3U**.
3. The file downloads to your computer.
M3U files contain file paths relative to your library, so they work with any music player that has access to the same library directory.
## Playlists via Subsonic
Saved playlists are available through the Subsonic API. Any Subsonic client that supports playlists (most do) can see and play your Shanty playlists.
To use this, make sure you have [Subsonic set up](subsonic.md) with a Subsonic password configured.
## Generation strategies explained
### Similar Artists
This uses Last.fm's similar-artist data to find tracks from artists related to your seeds. For example, if you seed with "Radiohead," the playlist might include tracks by Radiohead, Thom Yorke, Portishead, Massive Attack, and other similar artists -- but only tracks that exist in your library.
The **popularity bias** slider controls the balance:
- High bias (closer to 1.0): favors popular/well-known tracks
- Low bias (closer to 0.0): gives equal weight to all tracks
### Genre
Filters your library by genre tags and selects tracks that match. You can specify one or more genres.
### Random
A random sample from your entire library. If ordering is not set to "random," tracks are ordered by artist/album for easier listening.
### Smart Rules
Define custom rules like:
- Artist contains "Pink Floyd"
- Year is between 1970 and 1980
- Genre is "Progressive Rock"
Tracks matching all rules are included, up to the count limit.
docs/features/subsonic.md
+94
View File
@@ -0,0 +1,94 @@
# Subsonic Streaming
Shanty includes a Subsonic-compatible API that lets you stream your music library to mobile apps, desktop players, and other Subsonic clients.
## What is Subsonic?
Subsonic is a widely-supported protocol for streaming music from a personal server. Many music apps implement the Subsonic API, which means you can use any of them to stream your Shanty library to your phone, tablet, or desktop.
## Important note
Shanty implements a subset of the Subsonic API -- enough for browsing, streaming, playlists, and search. If you need a full-featured Subsonic server with advanced features like sharing, podcasts, or Internet radio, consider running [Navidrome](https://www.navidrome.org/) pointed at the same music library directory. Both can coexist.
## How to set up
### 1. Set a Subsonic password
The Subsonic protocol uses its own authentication system, separate from your Shanty web login.
1. Open the Shanty web UI and go to **Settings**.
2. Find the **Subsonic API** section.
3. Enter a password and click **Save**.
**Security note:** The Subsonic protocol transmits passwords as MD5 hashes (not encrypted). This is a limitation of the protocol itself. Do not reuse a password you use for other services. The Subsonic password is stored in plain text in the database, per the protocol specification.
### 2. Configure your client
In your Subsonic client app, add a new server with these settings:
| Field | Value |
|-------|-------|
| **Server URL** | `http://your-server-ip:8085` |
| **Username** | Your Shanty username |
| **Password** | The Subsonic password you set (not your web login password) |
Most clients automatically append `/rest` to the server URL. If your client asks for just the base URL, enter `http://your-server-ip:8085`.
If your client has separate fields for server address and port, enter the IP/hostname and `8085` separately.
### 3. Test the connection
Most clients have a "Test Connection" button. Use it to verify that the server is reachable and your credentials are correct.
## Recommended clients
These clients have been tested with Shanty's Subsonic implementation:
### Android
- **[Ultrasonic](https://f-droid.org/packages/org.moire.ultrasonic/)** -- Free and open source. Available on F-Droid and Google Play. Reliable and well-maintained.
- **[DSub](https://play.google.com/store/apps/details?id=github.daneren2005.dsub)** -- Feature-rich, supports offline caching.
- **[Symfonium](https://play.google.com/store/apps/details?id=app.symfonik.music.player)** -- Modern UI, excellent playback features. Paid app.
### Desktop
- **[Feishin](https://github.com/jeffvli/feishin)** -- Cross-platform desktop client with a modern interface. Free and open source.
## Supported Subsonic endpoints
Shanty implements these Subsonic API endpoints:
- **System:** `ping`, `getLicense`
- **Browsing:** `getMusicFolders`, `getIndexes`, `getMusicDirectory`, `getArtists`, `getArtist`, `getAlbum`, `getSong`, `getGenres`
- **Search:** `search3`
- **Media:** `stream`, `download`, `getCoverArt`
- **Playlists:** `getPlaylists`, `getPlaylist`, `createPlaylist`, `deletePlaylist`
- **Annotation:** `scrobble`
- **User:** `getUser`
## Transcoding
If your music is in Opus format (the default download format), many mobile clients cannot play it directly. Shanty automatically transcodes Opus files to MP3 when streaming via the Subsonic API. This requires ffmpeg, which is included in the Docker image.
If you download in MP3 format or your clients support Opus natively, you can disable transcoding:
```yaml
subsonic:
transcoding_enabled: false
```
## Troubleshooting
**"Authentication failed" in client:**
- Make sure you are using the Subsonic password, not your web login password.
- Make sure the username matches exactly (case-sensitive).
**Client cannot connect:**
- Verify the server URL includes the port (`http://ip:8085`, not just `http://ip`).
- Check that port 8085 is accessible from the device (firewall rules, same network, etc.).
**No music showing up:**
- Music must be organized in the library (run the pipeline at least once) to appear in the Subsonic API.
- Only tracks with file paths in the database are served.
**Audio does not play:**
- If using Opus format, make sure transcoding is enabled (it is by default).
- Check that ffmpeg is installed (included in Docker, must be installed manually for source builds).
docs/features/youtube-auth.md
+72
View File
@@ -0,0 +1,72 @@
# YouTube Authentication
Shanty downloads music from YouTube via yt-dlp. By default, it makes requests as a guest, which limits you to roughly 250 downloads per hour. Authenticating with a Google account increases this to roughly 1800 downloads per hour and grants access to age-restricted content.
## Should you set this up?
If you are downloading just a few albums at a time, guest mode is fine. If you are adding several artists at once or building a large library, authentication will save you a lot of waiting.
## Warning: Use a throwaway account
There is a small but real risk that Google may flag your account for unusual activity. Automated downloading is against YouTube's terms of service. To protect yourself:
- Create a new Google account specifically for this purpose.
- Do not use your main Google account.
- Do not use an account tied to important services (Gmail, Google Drive, etc.).
## How to set up
1. Open the Shanty web UI and go to **Settings**.
2. Scroll to the **YouTube Authentication** section.
3. Click **Authenticate**.
4. A noVNC browser window opens, showing Firefox inside the Shanty container.
5. Navigate to YouTube and log in with your throwaway Google account.
6. Once you are logged in, go back to the Shanty settings page and click **Done**.
Shanty extracts the YouTube cookies from Firefox and saves them. From this point forward, all downloads use your authenticated session.
## Docker port requirement
The noVNC interface runs on port **6080** by default. Your `docker-compose.yml` must expose this port:
```yaml
ports:
- "8085:8085"
- "6080:6080" # Required for YouTube login
```
If you are running Shanty on a remote server, you need to access noVNC from your browser at `http://your-server-ip:6080`. Make sure firewalls allow this port during the login process. You can close the port afterward if you want -- it is only needed during initial login and manual re-authentication.
The noVNC port is configurable via `download.vnc_port` in the config file.
## How auto-refresh works
YouTube cookies expire roughly every 2 weeks. Shanty automatically refreshes them using headless Firefox (no visible browser window needed):
- After you complete the login process, auto-refresh is enabled automatically.
- Every 6 hours (configurable via `download.cookie_refresh_hours`), Shanty launches Firefox in headless mode, loads YouTube using the saved profile, and exports fresh cookies.
- If a refresh fails, Shanty logs a warning and tries again at the next interval.
You can check the current cookie status in **Settings** under **YouTube Authentication**. It shows whether cookies are present, how old they are, and whether auto-refresh is enabled.
## Manual refresh
If cookies have expired and auto-refresh is not working, you can:
1. Click **Refresh** in the YouTube Authentication settings to trigger an immediate headless refresh.
2. If that fails, click **Authenticate** to log in again through noVNC.
## Clearing cookies
To remove all YouTube authentication data, click **Clear** in the YouTube Authentication settings. This deletes the cookies file and the Firefox profile, and disables auto-refresh.
## Configuration options
| Option | Default | Description |
|--------|---------|-------------|
| `download.cookies_path` | (auto) | Path to the cookies file. Managed automatically. |
| `download.cookie_refresh_enabled` | `false` | Auto-enabled after login. |
| `download.cookie_refresh_hours` | `6` | Hours between refresh attempts. |
| `download.rate_limit` | `250` | Requests/hour without cookies. |
| `download.rate_limit_auth` | `1800` | Requests/hour with cookies. |
| `download.vnc_port` | `6080` | Port for the noVNC login interface. |