Main/docs/features/monitoring.md

Artist Monitoring

Monitoring lets Shanty automatically detect when your favorite artists release new music. When a new album or single is found, its tracks are added to your watchlist and queued for download.

Watching tracks vs. monitoring artists

In Shanty, tracks are what you watch. When you click "Watch All" on an artist page, every track in their current discography becomes a watched track. Those watched tracks get synced, downloaded, tagged, and organized by the pipeline.

Monitoring is different. Monitoring an artist means Shanty periodically checks MusicBrainz for new release groups (albums, singles, EPs) that did not exist when you last looked. When new releases are found, their tracks are automatically added to your watchlist.

In short:

• Watching is about tracks: "I want these specific tracks in my library."
• Monitoring is about artists: "Tell me when this artist puts out something new, and watch those tracks for me automatically."

You can watch tracks from an artist without monitoring them (just grab their existing catalog and move on). You can also monitor an artist to stay current with future 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 "Monitored" badge appears next to their name, and a checkmark shows in the Library view.

To stop monitoring an artist, click the Unmonitor button on their page.

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 tracks already in your watchlist.
3. Any new release groups are expanded into individual tracks 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 tracks 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, their tracks 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:

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:

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 Artists (under the individual 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.

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 normally after the skipped run.