Plugins

Aviato is built on an advanced plugin system that allows for nearly every aspect of Aviato to be extended and customized by both official and unofficial plugins.

This page covers how to install, configure, and manage plugins on a running server, and what kinds of plugins exist. If you are writing your own plugin, see the developer documentation instead.

What plugins do

Aviato itself is a thin core that orchestrates work. Almost everything you see in the UI is provided by a plugin: your movies library, the artwork on a poster, the subtitle track on an episode, the file scanner that finds new media. The Aviato team ships a set of official plugins covering the common use cases, and anyone can publish their own.

A typical install runs several plugins at once. For example, a movies library backed by local files and TMDb metadata uses four:

Local Filesystem, to scan files from disk.
Movies Library, to define what a movie is and how it browses.
TMDb, to identify and enrich movie metadata.
Thumbnail Generator, to produce preview images from video files.

Plugins run as isolated background processes, so a misbehaving plugin cannot crash the server. If a plugin fails repeatedly, Aviato disables it and surfaces the error in the admin UI rather than retrying forever.

Managing plugins

Plugin management lives in Settings > Plugins. Every plugin currently installed on your server appears in this list, along with its status, capability tags, and any configuration it exposes.

Installing from the marketplace

The simplest way to install a plugin is from the in app marketplace. Go to Settings > Plugins > Browse marketplace to see every plugin published to the Aviato plugin marketplace, filterable by media type and capability.

Click a plugin to see its description, author, supported media types, and required permissions. Install downloads it, validates the manifest, and starts the plugin. No server restart is required.

You can also browse the marketplace from the web at aviato.media/plugins without an Aviato server running.

Installing manually

Self published or in development plugins can be installed by dropping the plugin folder into the plugins directory inside your Aviato data directory. Each plugin must live in its own subdirectory containing a valid plugin.json manifest at the top level.

Aviato watches the plugins directory and picks up changes immediately, so a newly dropped plugin appears in the installed list without a restart. A plugin with an invalid manifest is rejected with a clear error message pointing at the failing field.

Configuring a plugin

Most plugins expose a few user settings, such as an API key, a default language, or a list of paths to scan. Click a plugin in the installed list to open its configuration page.

Saved configuration is sent to the plugin and persists across restarts. Required fields that have not been filled in surface as a warning in the plugin list, and may prevent the plugin from doing useful work until you provide them. Optional fields fall back to the plugin's declared defaults.

Some plugins also expose per library configuration rather than (or in addition to) global settings. Per library configuration appears on the library's settings page, not on the plugin page itself.

Enabling, disabling, and removing

Each plugin has an enable toggle. Disabling a plugin stops it and unregisters its capabilities, but keeps the install and its configuration on disk so you can reenable it later without losing your settings.

Removing a plugin deletes it from your data directory entirely. Libraries that depend on the plugin's capabilities stop working until you install a replacement, so make sure nothing in your setup relies on the plugin before uninstalling it.

Updates

Aviato periodically checks the marketplace for new versions of your installed plugins. When updates are available, a badge appears at the top of Settings > Plugins showing how many plugins have updates waiting. Open the plugin in the marketplace to review the new version and click Upgrade to apply it.

Manually installed plugins are not tracked against the marketplace; you replace the folder yourself when you want to update them.

Logs and diagnostics

Every plugin has its own log stream, viewable from the admin dashboard at /admin/dashboard. Use this when a plugin is misbehaving. Failed metadata lookups, scan errors, rate limit warnings, and crashes all surface here.

If a plugin crashes repeatedly, Aviato trips a circuit breaker on it and marks the plugin as failed in the UI. Restarting the plugin from the admin dashboard clears the breaker and tries again.

Capabilities

A plugin declares one or more capabilities that tell Aviato what it can do. When choosing or browsing plugins, capabilities are the easiest way to understand what a plugin contributes.

Library plugins

Library plugins define a type of media: movies, TV shows, music, photos, audiobooks, books, or any custom type a plugin author cares to invent. They describe the schema of an item, the entities it contains (a TV show contains seasons which contain episodes), how items group, sort, and filter, and the layout of the item detail page.

Every library you create in Aviato is backed by exactly one library plugin. Official library plugins ship for the common media types. Community plugins can introduce entirely new ones.

Indexer plugins

Indexer plugins identify your media against an external metadata source. Given a file or folder, they reach out to a service such as TMDb, MusicBrainz, or Audible, find the right match, and return rich metadata: titles, descriptions, cast, cover art, release dates, and more.

You can install multiple indexers for the same media type and let Aviato use them together. For example, both TMDb and an open data alternative can supply movie metadata, with Aviato merging the results.

Indexers usually require an API key for the upstream service. The plugin's configuration page explains where to get one.

Filesystem plugins

Filesystem plugins are the bridge between Aviato and your actual files. The bundled Local Filesystem plugin reads files from paths you mount into the server. Other filesystem plugins can expose remote sources such as cloud storage, network shares, or anything else with a file like API.

Most users only ever need Local Filesystem. The capability exists so that future plugins can integrate Aviato with any storage backend.

Hook plugins

Some plugins do not provide a long lived capability at all. Instead, they react to events as media flows through Aviato's ingestion pipeline. These hook plugins are how features such as thumbnail generation, embedded metadata extraction, subtitle discovery, and poster fetching are implemented.

Hook plugins generally need no configuration. You will rarely interact with them directly beyond enabling or disabling the feature they provide.

UI extensions

Plugins can also extend the Aviato web interface by adding actions to item pages, sections to detail views, or panels to settings. These extensions are declared by the plugin and load lazily in the browser, so a plugin that contributes UI does not slow down the rest of Aviato.

When you install a plugin that adds UI, the new surfaces appear in the relevant pages automatically.

Dependencies

Some plugins depend on others. A metadata enrichment plugin might require a specific indexer; a library plugin might rely on a particular filesystem source. Dependencies are declared in the plugin's manifest and enforced at startup. Aviato refuses to start a plugin whose dependencies are missing or disabled, and shows the missing dependency in the admin UI so you can install it.

The marketplace surfaces a plugin's dependencies on its detail page, so you can see what else you will need before installing.

Permissions and trust

Plugins run with the same privileges as the Aviato server itself. They can read and write the data directory, reach the network, and run subprocesses. Treat installing a plugin the same way you would treat installing any other piece of software on your server.

Official plugins are reviewed and signed by the Aviato team, and shown with an Official badge in the marketplace. Community plugins are unreviewed; install only ones from authors you trust, or audit the source yourself before installing.