Hama.bundle: an AniDB metadata agent for Plex anime libraries
Plex HTTP Anidb Metadata Agent (HAMA)
At a glance
- What is it?
- HAMA maps AniDB IDs onto TVDB and TMDB records so Plex can present anime with correct numbering, posters and summaries. It is a mature, GPL-3.0 Python agent whose value depends entirely on the accuracy of two external XML mapping files.
- Who is it for?
- Adopt HAMA if your library is anime-first and you can live with a legacy Plex agent that depends on ScudLee's XML mappings being current for the shows you own. Do not adopt it if your library is mostly Western television, if you want a maintained agent with an active release cadence (the last tagged release is from 2017), or if you are unwilling to review the HTML error reports it writes.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 66 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The numbering problem HAMA was built to solve
Anime releases rarely arrive with the season and episode numbering that TVDB or TMDB expects. A show may be split across seasons by broadcast year, released as OVAs between TV episodes, or known primarily by its AniDB identifier. Plex's default TV agents key off TVDB, so a file named for its absolute episode number can land in the wrong season or fail to match at all. HAMA's stated purpose is to bridge that gap: it provides both Movies and Series agents, and its central feature is AniDB ID to TVDB/TMDB ID matching, with studio and episode mapping supplied through ScudLee's XML mappings. The intended user is someone running a Plex server whose library is predominantly anime and who is willing to install a scanner alongside the agent. The README is explicit that it is strongly recommended to use Absolute Series Scanner in combination with HAMA, and offers a simple test: if all video files are showing in Plex with the right season and episode number, the scanner did its job.
How the agent resolves an AniDB ID into Plex metadata
The mechanism is a chain of lookups across four XML files. anime-titles.xml comes from the AniDB HTTP API and contains all anime titles. anime-list-full.xml maps an AniDB ID to a TVDB ID and supplies studio and episode mapping plus TMDB and TVDB IDs. anime-list-master.xml is ScudLee's AniDB to TVDB mapping, described as giving the studio and episode mapping list for the episode overview. anime-movieset-list.xml groups movies into collections, which the README notes exists because XBMC supported only movie collections and the files were originally developed for the AniDB mod XBMC plugin. Search is handled locally through the anime-titles.xml database file rather than against a live API. When a series is not found in AniDB, HAMA falls back to searching TVDB and TMDB automatically. Posters come from TVDB, and the README suggests assigning a poster to each AniDB ID in the AniDB to TVDB mapping file to avoid poster duplicates. Episode summaries are English only and come from TVDB via ScudLee's episode mappings. Studio preference is the mapping file first, then AniDB, since studio is often missing from AniDB. There is also a detail worth noting for anyone planning a large library: unique posters are produced by using the AniDB rank in the mapping to rotate the posters.
Installation, cache order and the settings that actually matter
HAMA is a Plex Metadata Agent, so installation means placing the bundle where Plex reads legacy agents and then selecting it in Settings. The README does not spell out a copy command, but it does name the data directory that matters at runtime: `.../Plex Media Server/Plug-in Support/Data/com.plexapp.agents.hama/DataItems`, which is where the HTML log files are written. Source resolution follows a fixed order. The XMLs are fetched from the internet using the Plex cache for one week, then local, then from the resource folder, and a copy is saved in the agent data folder in case of connection issues. Pictures and theme songs resolve differently: cache first, then the internet. That asymmetry is worth understanding before you debug a missing poster, because the XML and image paths do not fail in the same way. Two settings do most of the visible work. First, language order for the series name and episode titles is configured separately in Agent Settings, and the README notes support for Kanji characters in folders, filenames and titles. Second, Local Media Assets is not enabled for HAMA by default. To use local artwork you enable it at `Settings > Server > Agents (Legacy) > Shows > HamaTV | HamaMovies > "Local Media Assets (TV)"` and `Settings > Server > Agents (Legacy) > Movies > HamaMovies > Local Media Assets (Movies)`, placing it before HAMA so local files take priority. The naming conventions are conventional: `theme.mp3` for the theme song, `Season01a.ext` for a season poster, `banner/banner-1.jpg` for a banner, and `MovieName-Trailer.ext` or a `Trailers` folder for movie trailers. Subtitles and trailers are handled by Local Media Assets, not by HAMA itself, which is a distinction the README makes clearly.
The HTML error reports are the real maintenance interface
Most metadata agents fail quietly. HAMA does the opposite: it writes HTML log files for issues, with links to facilitate updating the source databases and even adding missing episodes. The files live in the DataItems folder and have names that describe exactly what is wrong, including `AniDB posters missing.htm`, `AniDB summaries missing.htm`, `anime-list anidbid missing.htm`, `anime-list studio logos.htm`, `anime-list tvdbid missing.htm`, `TVDB posters missing.htm` and `TVDB season posters missing.htm`. The example shown for the studio report is a line of HTML containing an AniDB link for aid 266, the title 'Case Closed', and the message that AniDB and anime-list are both missing the studio. This is a genuinely different posture from a black-box agent. The reports are written for a contributor, not just an operator, and the README frames them as a way for the community to update the mapping XML or TVDB more easily. The cost is that someone has to read them. A library with hundreds of series will produce a long list, and the list is only useful if you act on it.
Where HAMA is the wrong tool
The dependency on ScudLee's XML mappings is the main constraint, and it is not a minor one. If your show is not in anime-list-full.xml, the mapping does not exist and HAMA has nothing to translate the AniDB ID into. The README's own error report for a missing AniDB ID in the anime-list confirms this is an expected failure mode rather than an edge case. The fallback to TVDB and TMDB search only triggers when a series is not found in AniDB at all, which is a different situation from a series that exists in AniDB but has no mapping entry. There is also a hard limit on what the agent can fix: episode summaries are English only, so a multilingual library gets English descriptions regardless of the language order configured for titles. And the agent cannot repair numbering that the scanner produced. The README's own framing puts the responsibility on the scanner to deliver the right season and episode number; HAMA maps identifiers, it does not re-derive episode order from filenames. Finally, this is a legacy Plex agent, configured under an Agents (Legacy) settings path, and the repository's last tagged release is a Beta from 2017 with an earlier v1.0 from 2016. Anyone expecting a fast-moving agent should look elsewhere.
How HAMA differs from a TVDB-first agent
A conventional Plex TV agent treats TVDB as the primary key: it matches the show, then trusts TVDB's season and episode structure. HAMA inverts that. AniDB is the anchor, anime-titles.xml is the local search index, and TVDB and TMDB become secondary sources reached through a translation table. The practical difference shows up in two places. First, search behaviour: because HAMA searches a local XML database, matching does not depend on a live TVDB query, and the README notes that the XMLs are cached for a week and copied locally in case of connection issues. Second, episode-level metadata: summaries and screenshots come from TVDB, but the episode mapping that connects an AniDB episode to a TVDB episode comes from ScudLee's files, not from TVDB's own ordering. That means HAMA's accuracy is bounded by the mapping file's accuracy, not by TVDB's. A TVDB-first agent has no such translation layer and therefore no such failure point, but it also has no mechanism for the absolute-numbering anime releases that HAMA was designed around. Trakt scrobbling is listed as supporting HAMA GUIDs, which matters if you rely on Trakt and would otherwise lose scrobble history when switching agents.
Licence, upgrade cost and what to check before adopting
HAMA is GPL-3.0. If you install it as a Plex agent, the practical effect is that the bundle and any modified version you redistribute carry the same licence obligations. If you patch the agent locally to fix a mapping or add a feature, the GPL terms apply to that modified code if you share it. This is a description of the licence identifier, not legal advice; read the full text if redistribution is on your roadmap. On upgrade cost, the honest answer from the material is that there is little to upgrade to. The most recent release listed is a Beta from February 2017, described as a ZeroQI major re-write test release, and the prior release is v1.0 from April 2016. The repository shows a last push in 2026, so work continues on the branch, but the tagged releases do not reflect it. That means upgrades are likely to be pulls from master rather than version bumps, and you should expect to read commit history rather than release notes. The XML mappings are a separate moving part: because they are downloaded and cached for a week, a mapping correction upstream can reach your library without any change to the agent itself, which is convenient but also means a metadata regression can appear without an install. Before adopting, verify three concrete things: that anime-list-full.xml has entries for your AniDB IDs, that Absolute Series Scanner produces the season and episode numbers you expect, and that the DataItems folder is somewhere you will actually check. If all three hold, HAMA does something the default Plex agents do not.
Editorial conclusion
Adopt HAMA if your library is anime-first and you can live with a legacy Plex agent that depends on ScudLee's XML mappings being current for the shows you own. Do not adopt it if your library is mostly Western television, if you want a maintained agent with an active release cadence (the last tagged release is from 2017), or if you are unwilling to review the HTML error reports it writes. Before committing, verify that anime-list-full.xml contains entries for your specific AniDB IDs and that Absolute Series Scanner produces the season and episode numbers you expect, because HAMA cannot correct numbering that the scanner got wrong.
Community notes