Plugins

Plugins add features Aurral doesn’t have on its own.

A plugin can add:

Actions to playlist, flow, album, artist, and track menus, such as Send to Plex.
Events, so it hears when a playlist changes, a track is played, a download finishes, or Aurral sends a notification.
A download source for tracks, or for whole albums.
A playlist import from links on another site.
A schedule, so it runs on its own every 15 minutes, hour, 6 hours, or day.
Admin access to Aurral’s API, so it can do anything an admin can do in Aurral, like creating playlists or requesting albums.

Plugins are app-wide. Only admins install them, turn them on, and set them up. Everyone sees the actions a plugin adds, except actions the plugin marks for admins.

Each plugin runs in its own process. A plugin that crashes, hangs, or answers with something Aurral can’t read fails on its own, and Aurral keeps working. Its errors show on its page in Settings > Plugins and in the log under plugin:<id>.

A plugin runs as Aurral, so it can read and change what Aurral can. Install plugins only from people you trust, the same as a Docker image.

Install a plugin

In Settings > Plugins, paste a link to the plugin’s GitHub repo under Install from a link and select Check. Aurral installs from the repo’s latest release. When a repo has more than one plugin, choose the ones you want. Aurral shows what each plugin uses and adds before you install it. A link to a .zip works too. Use the official plugins checks the repo of plugins the Aurral project maintains, such as Lidarr.

You can also put the plugin’s folder in the plugins folder of the data folder. In Docker that is /config/plugins, so a plugin with the id send-to-box lives in /config/plugins/send-to-box. Aurral reads the folder each time you open Settings > Plugins.

A new plugin is off. Open it, fill in its settings, and turn it on. If it has a Test button, use it to check its settings.

Aurral checks plugins installed from a link for a new version once a day. A plugin with one shows Update to its new version in Settings > Plugins, along with anything the new version adds, such as admin access. Nothing installs until you select Update on the list or on the plugin’s page. Remove deletes the plugin’s folder, its settings, and the files it kept.

Choose what a plugin adds

A plugin’s page lists everything it adds under Adds. Turn off any of them and the rest keep working. For example, keep a plugin’s Send to Plex action and turn off its download source.

Build a plugin with an agent

Under Build with an agent, select Copy prompt and paste it into an agent that supports MCP, such as Claude Code or Codex. Fill in what you want the plugin to do.

The prompt has a developer key that lets the agent read the plugin API, write a plugin, and test it against your Library. The agent can’t turn a plugin on, so you check it and turn it on when it’s ready. A key lasts 24 hours. Revoke it on the same page.

To write a plugin yourself, read the plugin API.

Download sources

A download source plugin joins the other download sources. Set its Priority on its page. Sources with a lower number are searched first.

Aurral checks every file a plugin downloads the same way it checks its own downloads. A file that doesn’t match goes to the review queue or is denied.

Playlist imports

A plugin that imports playlists shows as a source in Import playlist. Paste a link to a playlist on its site. Synced imports update on the schedule you choose, the same as other imports.

When a plugin fails

When a plugin throws an error, Aurral shows the plugin’s name and message, and the plugin’s page shows the last error with a link to report it.

When a plugin crashes, hangs, or answers in a shape Aurral can’t read three times in a row, Aurral turns it off. Its page says why. Turn it on again once it is fixed.

Safe mode

Safe mode runs Aurral with every plugin off and keeps each plugin’s own setting. Turn it on in Settings > Plugins. If Aurral won’t start, or the page won’t load, set AURRAL_SAFE_MODE=true and restart.

Before you report a bug in Aurral, check whether it still happens in safe mode. If it doesn’t, report it to the plugin.