ShokoRelay

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

This is a plugin for Shoko Server that acts as a Custom Metadata Provider for Plex. It is a successor to the ShokoRelay.bundle legacy agent/scanner and mirrors all of its functionality (including the automation scripts). Scanning is much faster and there are many new features included as well. Just like the old bundle this is intended to work with series of all types within a single "TV Shows" library. All you need to get started is a populated Shoko Server and Plex Media Server.

Due to the lack of a custom scanner this plugin leverages a VFS (Virtual File System) to ensure that varied folder structures are supported. This means that your anime can be organised with whatever file or folder structure you want. There is one caveat though. A folder cannot contain more than one AniDB series at a time if you want it to correctly support local media assets (like posters or theme songs). The VFS will be automatically updated when a file move or rename is detected by Shoko.

Installation

Shoko

[!IMPORTANT] The VFS is created inside each of Shoko's "destination" type folders under a subfolder named !ShokoRelayVFS (configurable under Advanced Settings > VFS Root Path). To stop Shoko from scanning the generated links, navigate to Shoko's installation directory and add the following regex entries to settings-server.json under Exclude:

"Exclude": [
  "[\\\\\\/]!AnimeThemes[\\\\\\/]",
  "[\\\\\\/]!ShokoRelayVFS[\\\\\\/]"
],

• Be sure to also exclude the AnimeThemes Root Path (default !AnimeThemes) if you plan on using AnimeThemes.
• After excluding the VFS in Shoko's settings, extract the latest release into Shoko Server's plugins directory
• Restart Shoko Server

Setup

• Once the Server has loaded navigate to Shoko Relay's dashboard at the following URL:
  • http(s)://{ShokoHost}:{ShokoPort}/api/plugin/ShokoRelay/dashboard
• Mandatory:
  • Click the Generate VFS button in the "Shoko: VFS" section to initialize your collection
    • First time generation may take several minutes to complete with a large library
  • A report of the run will be written to logs/vfs-report.log inside the plugin directory
    • You can download the latest report via a dashboard toast that will appear when the process completes
  • The VFS will automatically update when it detects files have been renamed or moved
• Recommended:
  • Link the plugin to your Plex account via the Start Plex Auth button in the "Plex: Authentication" section
    • Once clicked it will change to a Login link which will redirect you to app.plex.tv/auth
    • From there you can login to Plex as normal using your credentials and then close the tab
    • This will enable: Auto Scanning, Scrobbling (webhooks) and enhanced collection/ratings support
• There are additional options at the bottom under "Provider Settings" which also contains a "Help" button in the top right.

[!TIP] If you are sharing the symlinks over an SMB share they may not appear depending on the Samba Configuration. An example entry for smb.conf that may help to mitigate this is listed below:

[global]
    follow symlinks = yes

<details> <summary><b>Recommended Shoko Server Configuration</b></summary><br>

Enable the following options in Shoko to ensure that Plex has at least one source of metadata for everything:

• Settings > AniDB > Download Options
  • [x] Character Images
  • [x] Creator Images
• Settings > TMDB > TMDB Options
  • [x] Auto Link
  • [x] Auto Link Restricted
• Settings > TMDB > TMDB Download Options
  • [x] Download Alternate Ordering
  • [x] Download Backdrops
  • [x] Download Posters
  • [x] Download Logos
  • [x] Download Networks (available in settings-server.json)
• Settings > Collection > Relation Options
  • [x] Auto Group Series
  • [x] Determine Main Series Using Relation Weighing

</details>

Plex

Metadata Agent

• Navigate to Settings > Metadata Agents
• Click Add Provider in the Metadata Providers header and supply the following URL:
  • http(s)://{ShokoHost}:{ShokoPort}/api/plugin/ShokoRelay
• Click Add Agent in the Metadata Agents header, name it Shoko Relay and select it as the primary provider
• Under additional providers select Plex Local Media then click the + and Save

Library

[!TIP] If you previously used the legacy ShokoRelay.bundle you can simply convert your existing libraries to the new agent. This allows you to maintain watched states and video preview thumbnails. A full metadata refresh is required after the first scan.

• The Shoko Relay agent requires a TV Shows type library to be created (or an existing one to be used)
• Under Add Folders be sure to only enter a !ShokoRelayVFS (or the configured VFS Root Path) as the directory
• Under Advanced simply change the Scanner of the library to Plex TV Series and the Agent to Shoko Relay
• Additionally it is highly recommended to set the following Advanced settings:
  • [x] Use season titles
  • [x] Use local assets
  • Collections: Hide items which are in collections
  • Seasons: Hide for single-season series

<details> <summary><b>Legacy Agent Cleanup</b></summary><br>

Once you are happy with your new libraries you can safely delete all of the old data left behind from any anime related legacy agents you may have used. To do so simply navigate to your Plex Media Server data directory and search for the full agent name. You can then delete all of the files and folders found that match the search result. Some example search terms are listed below:

com.plexapp.agents.hama
com.plexapp.agents.shoko
com.plexapp.agents.shokorelay

</details>

Plex: Automation

[!NOTE] The Plex automation interval or "Int." (listed under the "Plex: Authentication" section) can be configured to control how often Generate Collections and Apply Critic Ratings runs. An interval of 24-hours or above is recommended as Shoko rarely updates this information.

Collection Generation

• Currently Plex's Provider Framework does not allow collections to be automatically assigned
  • They have to be injected manually via Plex's HTTP API instead
• Click the Generate Collections button in the "Plex: Automation" section to start this process
• Requires Plex authentication

Notes:

As a bonus this supports using the primary series poster as the collection poster (if configured under "Provider Settings"). Custom local posters can also be used by placing them in the configured Collection Posters Root Path (default !CollectionPosters) folder. These files are simply named after the Shoko group name (or ID) that you wish them to apply to. Empty collections will also be removed automatically during collection generation.

Critic Rating Application

• The Provider Framework supports TMDB ratings but they are not visible outside of the "New Plex Experience"
• To mitigate this the Apply Critic Ratings button on the dashboard is available
  • This makes Plex for Web/Desktop show the ratings next to a generic grey star in the UI
• The rating source for this can be configured (or disabled) under Critic Rating Mode in the Provider Settings
• Requires Plex authentication

Force Partial Scans

• When Force Partial Scans is enabled Plex's HTTP API will be used to scan folders modified by the VFS watcher
• Requires Plex authentication

Auto Scrobble

• When Auto Scrobble is enabled Plex's webhook will be used to forward scrobble events to shoko
• This can be enabled in the Plex Web/Desktop App under Settings > Webhooks
  • Click Add Webhook and enter: http(s)://{ShokoHost}:{ShokoPort}/api/plugin/ShokoRelay/plex/webhook
  • Click Save Changes to complete the process
• The webhook respects the Include Ratings and Exclude Admin settings in the Sync Watched States Menu
• Managed users must be added to Extra Plex Users on the dashboard if you wish them to be included
• Requires a Plex Pass subscription

Shoko: Automation

• Remove Missing A button which will remove files that are no longer present from Shoko
  • Unlike the "Remove Missing Files" action in Shoko's WebUI this will remove all traces of the files from the Shoko DB
  • Entries will always be removed from the AniDB MyList as well
• Import A button which will make shoko rescan all "Source" type drop folders
• Sync A button which opens a modal allowing for watched state syncing from Plex to Shoko or Shoko to Plex
  • This includes any users configured under Extra Plex Users in the "Plex: Authentication" section
  • Requires Plex authentication
• Schedule Offset An input which contr