# The Bangumi Jellyfin plugin overrides the metadata provider, and the override rules are the hard part > A Jellyfin and Emby metadata provider for bgm.tv that pulls Chinese animation information and can sync playback progress back. Its most interesting behaviour is how a per-directory bangumi.ini forces an episode into a normal season or a specials season, overriding whatever the provider returned. **kookxiang/jellyfin-plugin-bangumi** — bgm.tv plugin for jellyfin - Repository: https://github.com/kookxiang/jellyfin-plugin-bangumi - Stars: 1,144 · Forks: 45 - Language: C# - License: GPL-2.0 - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/kookxiang-jellyfin-plugin-bangumi ## A metadata provider for bgm.tv, with a progress sync back The plugin is a bgm.tv metadata provider for Jellyfin, written to pull Chinese animation information and images, with support for syncing playback progress to bgm.tv. That is two directions of traffic, and the second one is what makes the plugin more than a scraper. Fetching metadata is a one way operation that every metadata provider does. Writing a user's watched progress back to a third party site means the plugin holds a user's bgm.tv credentials and makes authenticated writes on their behalf, which is a different level of responsibility and is why the account binding flow is described in detail. The plugin is packaged in the standard Jellyfin way, with a `Jellyfin.Plugin.Bangumi/` directory for the plugin, a `Jellyfin.Plugin.Bangumi.Test/` directory for the tests, a solution file, a `Directory.Build.props` and a `Directory.Packages.props` for central package management, and a `web/` directory for the client side assets. There is a parallel `Emby.Plugin.Bangumi/` directory, so the same provider targets both media servers. The licence is GPL-2.0, and the primary language is C#. The release history shows a plugin that is maintained for both platforms. Version 1.7.7 came on 2026-09-08, 1.7.6 on 2026-01-18 and 1.7.5 on 2025-11-12, and the last push to the repository was on 2026-10-18 with the repository not archived. The build workflow badge at the top of the README points at a GitHub Actions build, and there are two download channels, a CI latest tag and a GitHub stable release. ## Installation is a plugin repository URL, and there are three of them The install path goes through the Jellyfin plugin catalogue, and the details are worth reading because the plugin hosts its own catalogue. In the Jellyfin console you choose Plugins, then Repositories, then Add, and then find the Bangumi plugin in the catalogue. Three repository URLs are offered, and the README says you can pick according to your network conditions. ``` https://kookxiang.github.io/jellyfin-plugin-bangumi/repository.json https://jellyfin-plugin-bangumi.kookxiang.dev/repository.json https://jellyfin-plugin-bangumi.pages.dev/repository.json ``` The first is GitHub Pages, the second is Cloudflare Pages, and the third is Cloudflare Pages marked as not recommended. The recommendation against the third is presumably about a hosting path, and the existence of three is a practical hedge for users behind networks where one of them is slow or blocked. After installation you can update from the admin backend, and the README recommends this method. Manual installation is the fallback. You download the plugin DLL into the Plugins/Bangumi folder under the Jellyfin data directory and restart the server. The Emby path is documented separately and carries a hard version requirement. The Emby build of the plugin requires version 4.9.0.33 or newer, and anything below that will fail to start the plugin. The README points at the linuxserver/emby and emby/embyserver images for versions above that floor. The DLL goes into the plugins folder under the Emby data directory, followed by a restart. ## Per-user account binding needs a second plugin on Jellyfin 12 Account binding is where the plugin reaches outside its own boundary, and on Jellyfin 12 it depends on another plugin. For a regular user to manage their own bgm.tv authorisation in their own Jellyfin settings, you first have to install File Transformation, the jellyfin-plugin-file-transformation project, at a version compatible with your Jellyfin version, and restart the server. Then you enable the regular user account binding entry point in the account page of the Bangumi plugin. The README is precise about what that switch does and does not do. The feature is off by default. It only injects the entry point into Jellyfin Web, it does not modify web files, and it does not affect scraping or existing playback sync. There is also a documented failure behaviour. If File Transformation is missing, incompatible, or fails to register the transformation, the switch will not turn on. If it is enabled and you then uninstall the dependency, it is automatically saved as off at the next Jellyfin start or status check. That is a deliberate design, and it is a good one, because a security relevant switch that silently stays on after its dependency disappears would be a problem. On permissions, the README states that regular users can manage only their own binding, while administrators can still manage other users' bindings from the plugin page. The alternative for anyone who does not want a second plugin installed is the admin route, where the administrator manages the account from the plugin page. The File Transformation dependency exists purely to give end users a self-service path. ## The directory type override beats the provider, and that is the design This is the part of the plugin with the most interesting logic, and the README documents it in unusual detail. You can choose a directory type in the plugin's library configuration, or set it in a `bangumi.ini` file in the directory containing the video. ```ini [Bangumi] Type=Normal ``` There are three values. `Auto` is the default and can be omitted, and it keeps automatic detection and allows a directory to mix main episodes and extras. `Normal` forces the episodes in that directory to be treated as main episodes, using non-zero season numbers. `Special` forces them to be treated as extras, using season zero. The precedence rules are where the real behaviour is. The forced mode takes priority over the file name, the directory name, the old season number, and the type returned by Bangumi. The episodes are re-matched by their belonging entry and episode number, and the previously saved per-episode IDs are not carried over, including when the trust existing Bangumi ID option is on. When several types share the same episode number, the configured type is preferred; when there is no matching type, metadata of another type can still be used, but the final classification stays as configured. The scope is deliberately narrow. The configuration applies only to the directory where the `bangumi.ini` is located and does not recurse into subdirectories. After saving, you refresh the metadata for that directory for it to take effect. A second, finer-grained override exists in the same file, letting you set the entry ID and episode offset per file name, with no web interface for editing it. The details and examples are in the project's wiki page on the extra configuration file, and the README says the wiki is authoritative. The design rationale is clear. Chinese anime directories routinely mix main episodes with extras in one folder, and a provider that guesses from the file name will misclassify some of them. Making the correction an explicit, local, per-directory setting that beats the provider entirely is the only reliable way to handle it. ## Missing and upcoming episodes come from an offline database only The Jellyfin 12 feature for missing and upcoming episodes is careful about what it does, and the constraints are the interesting part. You enable the option to show aired-but-missing episodes or to show upcoming episodes in the plugin's metadata settings, select the libraries to enable it for, and save, then rescan the library. It is off by default, the library also needs the Bangumi episode metadata source enabled, and whether clients display the missing or upcoming entries depends on the client's own display settings. The network behaviour is the notable part. The feature only uses the already downloaded offline database and does not request the online interface. It only imports episodes that Bangumi marks as main episodes, with an integer episode number and a complete valid broadcast date. Episodes with decimal numbers, specials and episodes with unknown dates are skipped. Entries airing today or later are handled by the upcoming switch. When the offline data is missing, existing placeholders are kept and the feature waits for the data to recover. The matching is by the existing season's Bangumi ID, with the first season allowed to use the series ID. The `ID` in the directory's `bangumi.ini` takes priority, and the `Offset`, `CorrectIndex`, `Skip` settings and the forced specials configuration apply as they do elsewhere. The feature does not guess or create entirely missing seasons, and a first scan may need to be repeated because the season mapping and episode scraping are not yet complete. The cleanup rules are equally explicit. A placeholder stores metadata only and has no media file behind it. A repeated scan updates existing placeholders, and once the files arrive a scan removes the corresponding placeholder. Turning the feature off, deselecting the library or skipping the directory means the next scan deletes only the placeholders this feature created, not media files and not virtual episodes from other sources. Turning off the Bangumi series metadata source for the library blocks the feature from running, and the README says to turn the feature off and complete a cleanup scan first. ## Conclusion Adopt jellyfin-plugin-bangumi if you run Jellyfin or Emby for Chinese animation and want metadata and artwork from bgm.tv plus playback progress sync. Do not adopt it if your library has no directory level control, because the finer-grained file name override lives in a bangumi.ini beside the media and there is no web interface for editing it. Verify first that the Jellyfin version you run is compatible with the plugin build, that the account binding flow you need is either the admin flow or the File Transformation dependent user flow, and that a rescan of a test directory produces the season numbering you expect before you point it at your whole library. ## FAQ ### How do I install the Bangumi plugin for Jellyfin? In the Jellyfin console choose Plugins, Repositories, Add, and pick the Bangumi plugin from the catalogue. Three repository URLs are offered, on GitHub Pages and two on Cloudflare Pages. For a manual install, copy the plugin DLL into the Bangumi folder under the Jellyfin plugins directory and restart. ### Can regular Jellyfin users manage their own bgm.tv account binding? Yes, but only on Jellyfin 12 and only with the File Transformation plugin installed at a compatible version. The switch injects an entry into Jellyfin Web without modifying web files, and it stays off automatically if File Transformation is removed. Administrators can always manage other users' bindings from the plugin page. ### How do I force a directory to be treated as extras instead of main episodes? Set Type=Special in a bangumi.ini file in that directory, or pick the directory type in the library configuration. The forced mode overrides the file name, directory name, old season number and the type returned by Bangumi, and it applies only to that directory without recursing into subdirectories. ### Does the missing and upcoming episodes feature call the bgm.tv online interface? No. It uses only the already downloaded offline database. It imports only main episodes with an integer episode number and a valid broadcast date, and when the offline data is missing it keeps existing placeholders and waits for the data to recover. ### What Emby version does this plugin support? The Emby build requires Emby 4.9.0.33 or newer, and older versions will fail to start the plugin. The README points at the linuxserver/emby and emby/embyserver images for versions above that floor. ## Sources - [Issues](https://github.com/kookxiang/jellyfin-plugin-bangumi/issues) - [kookxiang/jellyfin-plugin-bangumi on GitHub](https://github.com/kookxiang/jellyfin-plugin-bangumi) - [License: GPL-2.0](https://github.com/kookxiang/jellyfin-plugin-bangumi/blob/master/LICENSE) - [README](https://github.com/kookxiang/jellyfin-plugin-bangumi/blob/master/README.md) - [Releases](https://github.com/kookxiang/jellyfin-plugin-bangumi/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kookxiang-jellyfin-plugin-bangumi