Overview

Shisho has a plugin system that lets you extend its functionality with JavaScript. Plugins hook into the book processing pipeline to add support for new file formats, enrich metadata from external sources, and generate alternative output formats.

What Plugins Can Do

There are four types of plugins, each serving a different purpose:

Type	Purpose	Example
Input Converter	Convert unsupported file formats into supported ones	MOBI to EPUB
File Parser	Extract metadata from file formats Shisho doesn't natively support	PDF metadata extraction
Metadata Enricher	Look up and add metadata from external APIs	Fetching descriptions and genres from Goodreads
Output Generator	Generate alternative download formats from existing files	EPUB to MOBI conversion

Plugins run in a sandboxed environment with controlled access to the filesystem, network, and system commands. Each plugin declares exactly what permissions it needs in its manifest.

Alias-aware resolution

Resource names returned by plugins — authors, narrators, series, genres, tags, and publishers — are resolved through Shisho's standard name lookup, which checks aliases. If a plugin returns a name that matches an alias, Shisho maps it to the existing canonical resource instead of creating a duplicate. No plugin changes are needed to take advantage of aliases.

Installing Plugins

Plugins are installed from plugin repositories — curated lists of available plugins hosted on GitHub. Shisho ships with an official repository enabled by default.

To install a plugin:

1. Go to Admin > Plugins
2. Browse the Discover tab to see plugins from enabled repositories
3. Click Install on the plugin you want

Plugins can also be installed by placing them directly in the plugin directory for development or testing purposes.

Plugin Status

Each installed plugin has a status that determines whether it runs. You can see the status on the Installed tab and on each plugin's detail page.

Status	What it means
Active	Plugin is loaded and participating in scans/enrichment per its mode.
Disabled	You turned the plugin off via its enable toggle. Turn it back on to re-enable.
Error	The plugin is installed but failed to load — usually a manifest or runtime problem. The detail page shows the underlying error.
Incompatible	The plugin's minShishoVersion is higher than your running version. Update Shisho to use this plugin.

When enabling a plugin fails, a toast shows the load error and the plugin row is marked Error. Open the plugin's detail page to see the full error text in monospace; use it to fix the plugin's manifest or code. If the plugin came from a repository, check for an updated version — the error may already be fixed upstream.

Configuring Plugins

Many plugins have configuration options, such as API keys for external services. After installing a plugin:

1. Go to Admin > Plugins
2. Click a plugin in the Installed tab to open its detail page
3. Fill in the required configuration fields in the Configuration section
4. Save

Execution Order and Plugin Modes

When multiple plugins of the same type are installed (e.g., two metadata enrichers), you can control the order they run in and set their mode. Go to Admin > Plugins, click the gear icon in the top-right to open the Advanced plugin settings dialog, and use the Order section to drag plugins to reorder them within each hook type.

Each plugin can be set to one of three modes:

Mode	Automated Scans	Manual Identification	Use Case
Enabled	Runs automatically	Available	Default — plugin participates fully
Manual Only	Skipped	Available	Rate-limited APIs, pay-per-use enrichers
Disabled	Skipped	Unavailable	Temporarily turn off without uninstalling

Manual Only mode is only available for metadata enrichers. It lets you keep a plugin available for on-demand use (e.g., clicking "Identify" on a specific book) without having it run on every file during a library scan.

Per-Library Settings

Plugins can be customized on a per-library basis. In the library settings, you can:

• Set the mode for specific plugins in that library (enabled, manual only, or disabled)
• Reorder plugin execution for that library
• Toggle individual fields for metadata enrichers (e.g., allow a plugin to set genres but not the description)

If no per-library customization is set, the global plugin settings apply.

Field Controls for Metadata Enrichers

Metadata enrichers declare which fields they may modify (e.g., description, genres, cover). You can control this at two levels:

• Global: Enable or disable specific fields for a plugin across all libraries
• Per-library: Override the global setting for individual libraries

This gives you fine-grained control over what metadata each plugin is allowed to change.

Updating Plugins

When a new version of a plugin is available, you'll see an update indicator in Admin > Plugins. Click Update to install the latest version. Updates are applied instantly without restarting the server.

Plugin Security

Plugins run in a sandboxed JavaScript environment. Each plugin must declare its required permissions in its manifest:

• HTTP access: Which domains the plugin can make requests to (this also applies to coverUrl downloads — the server validates the URL domain against the plugin's allowed list)
• File access: Whether the plugin can read or write files beyond its own directory
• FFmpeg access: Whether the plugin can use FFmpeg for media processing
• Shell access: Which specific shell commands the plugin can execute

These permissions are visible when installing a plugin so you can review what access it needs before enabling it.