Configuring Shokofin
With Shokofin installed, there's a couple things that need to be done before it can be used as a metadata provider for your anime collection. The goal is to get Shokofin configured to your liking in a way so that you don't have to visit the settings very often once set.
Connecting to Shoko Server
Before you start using the plugin, it is important to connect it to a running instance of Shoko Server. Head over to Shokofin's plugin settings and provide the private host, username, and password to get that connected.
Option | Description |
---|---|
Private Host URL | The local IP or hostname that your running Shoko Server can be accessed directly from wherever Jellyfin is running. |
Public Host URL (Optional) | A public IP or hostname that can be used to access Shoko Server when the private host URL is not accessible from your browser when accessing Jellyfin. Most commonly used when Jellyfin is accessed outside your network or other complex network setups. If you do not know what any of this means, leave this field empty. |
Username | The username to your administrator account for Shoko Server. |
Password | The password to your administrator account for Shoko Server. |
After you've established a connection to a running instance of Shoko Server, feel free to skim through the plugin settings detailed below and adjust Shokofin to your liking. If the defaults work just fine, go ahead and skip to Creating a Shoko Library.
Configuring the Plugin Settings
The following will detail what each setting does and common use cases where necessary. Do note that certain options when changed will require a library recreation for existing libraries that use Shokofin as a provider and will be indicated where appropriate. Additional information on the subject can be found in the Recommendations section of the docs for Shokofin.
Attention Windows Users
If you are running Jellyfin on Windows, some additional setup is required to ensure the Virtual File System (VFS) feature can function. The VFS is an important quality of life feature and is normally enabled by default. More info on what the VFS is and what it means for you if you choose not to use it is detailed in our Recommendations section. Or you can jump straight to Microsoft's guide to enable developer mode which will allow Shokofin to create symbolic links on Windows and allows the VFS to function. Restarting Jellyfin is required once developer mode has been enabled.
Advanced Options
Shokofin provides some advanced options that are normally hidden. They can be made accessible in the plugin settings by clicking the Shoko Server version number under the Connection Settings section 7 times to enable Advanced Mode. Advanced options will be indicated using the ⚠ symbol in the sections below.
Metadata
The following settings will allow you to customize what information Shokofin will pull in as metadata for your media entries. Any changes to these settings will require you to replace all metadata for libraries that use the plugin as a provider.
Title Settings
⚠ | Option | Description | Default |
---|---|---|---|
Main Title Source | Enable and order available sources in the priority you want used for the main title of your series. | Shoko | |
Alternate/Original Title Source | Enable and order available sources in the priority you want used for the alternative title of your series. | None | |
Add Prefix to Episodes | Adds the type and number to the title of non-standard episodes such as specials. (e.g. S1, O1) | ✓ | |
⚠ | Allow Any Title in Selected Language | Allows for alternative titles to be utilized if an official title is not present in the given language. Only applies to AniDB title selectors when using a title override that follows language settings. |
Description Settings
⚠ | Option | Description | Default |
---|---|---|---|
⚠ | Cleanup AniDB Descriptions | Prettifies AniDB descriptions and converts them to markdown supported by Jellyfin. | ✓ |
Description Source | Enable and order available sources in the priority you want used for the descriptions of your series. | Shoko |
Tag & Genre Settings
⚠ | Option | Description | Default |
---|---|---|---|
⚠ | Ignore Unverified Tags | Don't use any user-submitted tags that have not been verified by AniDB. | ✓ |
⚠ | Tag Sources | Select which types of tag categories you want to use ranging from setting to themes to technical aspects. | All except Ungrouped and Unsorted |
⚠ | Tag Inclusion Filters | Filter which kind of tags to include ranging from spoilers to tag relationships. | All except Spoilers |
⚠ | Minimum Weight for Tags | Choose the minimum weight a tag must have to be included, not including weightless tags. | All Allowed |
⚠ | Maximum Depth for Tags | The maximum relative depth of a tag to be included based on it's source category. | 0 |
⚠ | Genre Sources | Select which types of genre categories you want to use ranging from elements to source material to target audience. | General Elements, Source Material, Target Audience |
⚠ | Genre Inclusion Filters | Filter which kind of genres to include ranging from spoilers to tag relationships. | All except Spoilers |
⚠ | Minimum Weight for Genres | Choose the minimum weight a genre must have to be included, not including weightless tags. | 2 Stars |
⚠ | Maximum Depth for Genres | The maximum relative depth of a genre to be included based on it's source category. | 1 |
Image Settings
⚠ | Option | Description | Default |
---|---|---|---|
Add Language Code | Adds the language code to any image metadata provided which Jellyfin can use to prioritize images based on a library's configured language. If a library has no language set, Jellyfin will prioritize the English labeled images. | ||
⚠ | Respect Preferred Image | Respect the preferred image flag sent from Shoko Server when selecting the correct image to use for the library. Setting this will also set the language code to the preferred language code for the library if 'Add Language Code' is enabled, thus ensuring it is always selected for the library. | ✓ |
Miscellaneous Settings
⚠ | Option | Description | Default |
---|---|---|---|
⚠ | Content Rating Sources | Enable and order available sources in the priority you want used for the media content ratings (TV-G, TV-PG, TV-MA, XXX) of your series. | TMDB, AniDB |
⚠ | Production Location Sources | Enable and order available sources in the priority you want used for the production locations of your series. | AniDB, TMDB |
Third Party Integration
⚠ | Option | Description | Default |
---|---|---|---|
Add Third Party IDs | Enable which third party IDs to provide for other plugins to consume with supported media items. | AniDB |
Library
Configure the behavior for how your media will be grouped and displayed within a library. Any changes to these settings will require you to remove the library in Jellyfin, wait for the library to fully disappear from the Jellyfin homepage, and create it once again following the instructions at Creating a Shoko Library.
Basic Settings
⚠ | Option | Description | Default |
---|---|---|---|
⚠ | Automatically Merge Multiple Versions of Videos | Enable to allow Shokofin to merge alternate versions of the same media into a single displayed entry. | ✓ |
Use Groups for Shows | Enable this to have Shokofin group your media the same way that can be seen in Shoko Server. This requires grouping to be setup and configured within Shoko Server itself for this setting to work. | ||
⚠ | Season Ordering | Choose the behavior of how seasons are ordered. You can choose between letting Shoko Server decide, order by release date, or order chronologically using AniDB relations. | Let Shoko decide |
Specials Placement Within Seasons | Change this to adjust where specials are placed in their respective season or filter them out entirely. | Always place specials after the normal episodes | |
Separate Movies From Shows | Enable this to filter out movies from a Jellyfin Shows library. Also separates movies from displaying alongside shows within a native Jellyfin collection and places each type under their respective headings. | ||
Add Missing Episodes/Seasons | Add episode/season entries for media that is not currently present in your local collection. Display settings for each Jellyfin user will have to be adjusted to show missing episode information to make use of this feature. | ✓ | |
⚠ | Disable Movie Library Filtering | By default we filter out anything that is not a movie in Jellyfin Movie libraries. Enable this if you want everything to show up as movies in your Jellyfin Movie libraries instead. | ✓ |
⚠ | Force Movie Special Features | Append all specials that belong to an AniDB movie series as special features for the movie(s). By default only some specials will be automatically recognized as special features, but by enabling this option you will force all specials to be used as special features. This setting applies to movie series across all library types, and will break movie series that contain specials in a show type library. |
Collection Settings
⚠ | Option | Description | Default |
---|---|---|---|
Collections | Configure how native Jellyfin collections should be created if at all based on Shoko Server provided metadata. | Do not create collections | |
⚠ | Require Two Entries for a Collection | If collection creation is enabled, only create a collection when the collection will contain at least two items. | ✓ |
New/Existing Library Settings
⚠ | Option | Description | Default |
---|---|---|---|
Import Folder Mapping | Only displays when an existing library is being configured. Displays the identified import folder name that the library is mapped to inside Shoko Server. A deletion button will be displayed as a way to remove the mapping configuration and allow Shokofin to remap the folder on the next library scan. | N/A | |
Use the Virtual File System (VFS) | This feature allows you to disregard the underlying disk file structure while automagically meeting Jellyfin's requirements for file organization. It also ensures that no unrecognized files appear in your library and allows us to fully leverage Jellyfin's native features better than we otherwise could. This enables us to effortlessly support trailers, special features, and theme videos for series, seasons and movies, as well as merge partial episodes into a single entry. All this is possible because we disregard the underlying disk file structure to create our own using symbolic links. Refer to our Recommendations page for additional information on what to expect whether you choose to use this feature or not. | ✓ | |
Legacy Library Filtering | Adjust how Shokofin filters out unrecognized media from your library. Set to Strict to hide all media not yet recognized by Shoko Server. Set to Lax to allow unrecognized media to appear in the library. Set to Auto to have Shokofin filter out unrecognized media only if no other providers are enabled for the library. Only applies to libraries not using the VFS. VFS managed libraries will always act as though Strict has been set. | Strict |
VFS
The Virtual File System (VFS) allows you to disregard the underlying disk file structure, automatically meeting Jellyfin's system requirements for file organization through the use of symbolic links. This setup ensures that no unrecognized files appear in your library and allows you to fully leverage Jellyfin's native features effortlessly. While this approach is relatively new and still undergoing testing, it is stable enough for daily use. We encourage adopting this system and reporting any issues you encounter to help improve it further. Below are some settings you can use to tweak the VFS's behavior to your liking.
Refer to our Recommendations page for additional information on what to expect whether you choose to use this feature or not.
Basic Settings
⚠ | Option | Description | Default |
---|---|---|---|
Add Trailers | Makes trailers appear as a native feature that Jellyfin can use. | ✓ | |
Add Credits as Theme Videos | Make OPs/EDs appear as a native theme video that Jellyfin can use. | ✓ | |
Add Credits as Special Features | Make OPs/EDs show up as native special features within Jellyfin. | ||
Add Release Group to Path | Will add full or short release group names to all automatically linked files in the VFS. 'No Group' will be used if the file is not associated with a release group in Shoko Server. Warning: The release group in the file name may change if the release group info is incomplete, unavailable, or otherwise updated in Shoko Server at a later date. This may cause episode/movie entries to be 'removed' and 'added' as new entries when that happens. Use at your own risk. | ||
Add Resolution to Path | Will add the resolution of the media to all automatically linked files in the VFS if available. Warning: Though rare, we may fail to read the media info in Shoko Server when the files were first added (e.g. because of a corrupt file, encountering an unsupported new codec, etc.), then reading it later. This may cause episode/movie entries to be 'removed' and 'added' as new entries when that happens. Use at your own risk. |
VFS Location Settings
⚠ | Option | Description | Default |
---|---|---|---|
⚠ | Resolve Links Before VFS | If a library contains symbolic links to media, it will follow them until a final 'real' file is found and use the path of said file for the VFS. | |
⚠ | Attach VFS to Libraries | Makes the VFS file structure that Shokofin automatically created show up as a library folder. This allows reusing the same media folder(s) across multiple libraries without needing other workarounds. Useful for separating movies and series into separate libraries while still using the same media folder for both. | |
⚠ | VFS Location | Change the location that Shokofin will place the VFS structure it generates on your system. Changing this will cause your library to 'remove' and 're-add' itself because of the path changes. You will need to manually move your VFS root if you plan to keep it when toggling this setting. Trick-play files will need to be backed-up beforehand and moved back the next library scan if you want to avoid regenerating them after you change this setting. You have been warned. | Jellyfin Data Directory |
Users
Configure watch-state synchronization for each Jellyfin user. By default, all synchronization features are disabled and must be configured and linked to a user in Shoko Server if desired.
User Settings
Option | Description |
---|---|
Enable Synchronization Features | Enable syncing certain data between Jellyfin and Shoko Server. The specific behavior on what gets synced and when can be configured using the remaining options in this section. Leaving this setting unchecked will disable synchronization entirely, regardless of other synchronization settings. |
Sync Watch-State on Import or Refresh | When media gets scanned into your library or when a library's metadata gets refreshed, sync watch-state between Jellyfin and Shoko Server. |
Sync Watch-State After Playback | Sync watch-state with Shoko Server when you finish watching a movie, episode, or other video. |
Sync Watch-State Events During Playback | Sync partial watch-state to Shoko Server on play/pause/stop/resume events during media playback. |
Sync Watch-State Live During Playback | Sync partial watch-state to Shoko Server at a regular interval during media playback. |
Lazy Sync Watch-State Events With Shoko | Wait about 10 seconds before syncing any of the above configured watch-state events to Shoko Server. This will prevent accidental clicks and/or previews from marking a file as watched in Shoko Server, and will also keep them more in sync with Jellyfin since it's closer to how Jellyfin handles the watch-state internally. |
Sync Watch-State for Restricted Videos | Allow syncing watch-state for adult content to Shoko Server. |
Username | The user in Shoko Server to sync the above watch-state events to. |
Password | The password for the specified Shoko Server account. |
SignalR
SignalR is a feature that allows for real-time communication with your running Shoko Server so that Shokofin has the ability to react to certain types of events such as file events and refresh events. This means that when Shoko Server identifies new media or updates metadata for your media, Shokofin can immediately import new or update existing media in your library.
Connection Status
Option | Description |
---|---|
Connection Status | Shows the current status of the SignalR connection. Will display if SignalR is disabled or enabled and if SignalR is currently connected or in the process of reconnecting to your running Shoko Server. SignalR can also be manually connected or disconnected using the button below this indicator. |
SignalR Settings
⚠ | Option | Description | Default |
---|---|---|---|
Auto Connect on Start | Attempt to connect to your running Shoko Server when Jellyfin starts up. | ||
⚠ | Auto Reconnect Intervals | A comma separated list of intervals given in seconds to try to reconnect to your running Shoko Server if Shokofin ever gets disconnected. The provided list will have duplicates removed and will be performed in sorted order starting from the shortest time span when reconnecting. Once the longest interval has been reached and fails to reconnect, Shokofin will stop attempting to reconnect and leave SignalR disconnected until otherwise reconnected. | 0, 2, 10, 30, 60, 120, 300 |
⚠ | Event Sources | Choose which event sources to react to for metadata events. | Shoko, AniDB, TMDB |
New/Existing Library Settings
⚠ | Option | Description | Default |
---|---|---|---|
File Events | Have Shokofin listen for file events from Shoko Server when new media gets added or moved around in the file system and trigger library updates accordingly. Especially useful if your Jellyfin library is using a network share for it's media location where native file events may not be available for Jellyfin's real time monitoring to function. Can be used as a complete replacement for Jellyfin's built-in real time monitoring or used alongside it. | ✓ | |
Metadata Events | Have Shokofin listen for metadata update events from Shoko Server when metadata gets added, updated, or removed and trigger library updates accordingly. Can be useful when media was missing episode titles or other info initially but was added or updated at a later time. |
Misc
The following section is for any additional settings not covered by the other sections and does not show up unless Advanced Mode is enabled.
Miscellaneous Settings
⚠ | Option | Description | Default |
---|---|---|---|
⚠ | Show in Menu | Creates a shortcut to the Shokofin plugin settings in the Jellyfin dashboard's sidebar. | |
⚠ | Ignored Folder Names | A comma separated list of folder names to ignore during a library scan. Useful for skipping folders generated by a NAS or other pieces of software that access the file system where media resides. Only applicable to libraries not managed by the VFS as files not recognized by Shoko Server are already ignored. | .streams, @recently-snapshot |
Creating a Shoko Library
Before creating a library, be sure the plugin is configured to your liking as certain options may require creating a library from scratch when changed due to how Jellyfin works internally. More information on the subject can be found in the Recommendations section of the docs for Shokofin. Creating a new library rather than enabling Shokofin on an existing library is required due to the nature of how Jellyfin and Shokofin work together.
Let's get started by adding a new library in Jellyfin's dashboard. All important options that will impact your experience with Shokofin is detailed as follows:
Content Type
The "Shows" type is best for most use cases, as Shokofin will still display anime movies in the library unless configured to separate movies from shows. If you configured Shokofin to separate movies, you will need to create a "Movies" library as well as a "Shows" library.
Setting the type to "Mixed Movies and Shows" will work, but is not recommended due to quirks within Jellyfin, and with how Shokofin works as a plugin. Any other library type is otherwise unsupported.
Folders
When specifying the media library's file path, be aware that any path you give must point to a directory with the same contents that Shoko Server sees in it's configured import folder(s).
For example, if Shoko Server knows the import folder for your collection as C:\ShokoImport\
, and Jellyfin is given a folder /mnt/anime
, as long as both directories contain the same things, Shokofin will be able to identify your media. Pointing Jellyfin to further nested folders seen within Shoko's import folder will also work, such as /mnt/anime/shows
and /mnt/anime/movies
given that both C:\ShokoImport\shows
and C:\ShokoImport\movies
also exist.
If you intend to have multiple Shokofin managed libraries to separate movies from shows, be sure that the folders specified for each library are different from each other due to how Jellyfin keeps track of metadata internally. You can also work around this using multiple volume/bind mounts or with a symbolic link or by enabling the Physically Attach VFS to Libraries advanced setting in the VFS tab of the plugin settings. You can read more about this in the Recommendations section of our docs.
Language and Country
With Shokofin, setting the preferred download language will not do anything unless a corresponding override was set in the plugin's Metadata Settings. If a relevant override is set that makes use of the library's language preferences, this is the value that will be used for determining the overridden metadata.
Country is not used by Shokofin at this time and can be left unset.
Embedded Info
To prevent any possible clashing with Shokofin's metadata retrieval, leave these two options disabled as it can result in mixed metadata and other strange behavior.
Real Time Monitoring
Real time monitoring can be enabled if you desire, which will let Jellyfin listen to file system events for new and modified files. This option will not do anything however if your file system does not support these events, and is especially common with network mounts like NFS or SMB shares. As an alternative, Shokofin provides a feature called SignalR in it's plugin settings which will allow Shokofin to maintain a constant connection to Shoko Server to receive and trigger updates for new and updated files/metadata. More information on configuring this feature can be found in the SignalR section of this page.
Metadata Downloaders
When using Shokofin, it is recommended to not enable any other metadata providers for all library types to prevent mixed metadata along with a slew of other problems from occurring. This is due to other metadata providers identifying the media incorrectly or just clashing in general with how your collection is organized.
Automatically Refresh Metadata
Setting the library to automatically refresh can be configured if you would like. This feature may be unnecessary if you utilize SignalR to have Shokofin refresh metadata on-demand as new metadata is found.
Metadata Savers
Important
DO NOT enable metadata saving using NFO files with libraries managed by Shoko, and if any are present among your media library, DELETE THEM NOW. The reasoning behind this is that Jellyfin prioritizes metadata from NFO files above any other metadata provider. This results in weird or broken behavior since Shokofin is unable to override metadata that's sourced from an NFO.
Either find any files in your library that have the .nfo
extension using your file explorer and delete them, or run the following command in a terminal according to your operating system. Be sure to substitute the path with the location of your library.
Windows (Powershell):
Get-ChildItem -Path 'C:\path\to\library\' '*.nfo' | Remove-Item
Linux:
find /path/to/library/ -name "*.nfo" -type f -delete
Image Fetchers
Shoko should be enabled and set as the top-most image fetcher for all library types and categories. Any additional metadata providers may be enabled, but can have mixed results where incorrect images are fetched. One that is known to work without issue alongside Shokofin is the Screen Grabber fetcher.
Saving Artwork Into Media Folders
When using the VFS feature provided by Shokofin, it is recommended to leave this option disabled as the artwork would end up saved into the symbolic linked file structure that Shokofin creates within the data directories of Jellyfin. For non-VFS managed libraries, this is not an issue and can be set according to personal preference.
Merge Series Across Folders
If you are using the VFS feature provided by Shokofin, this setting will not change any behavior. For non-VFS managed libraries, it is recommended to enable this no matter what. Enabling lets Shokofin better group your media into series that reflect your Shoko library without being limited by Jellyfin and the media's underlying folder structure.
Wrapping Up
Once you've confirmed the creation of your library after all that configuration, your library should be well on it's way with pulling in metadata and getting your library ready for use. This may be a time consuming process, so feel free to read through the Shokofin FAQs or the Recommendations of Shokofin for any other expectations and useful knowledge when it comes to the plugin.