Set Up HAMA for Accurate Anime Metadata in Plex

Published 2026-10-16 · PlexBeam

HAMA (HTTP Anidb Metadata Agent) is a third-party Plex metadata agent designed specifically for anime. It pulls metadata from AniDB — the most comprehensive anime database — and optionally supplements data from TheTVDB, TMDB, and other sources. HAMA solves the problems that make anime metadata frustrating in Plex: inconsistent episode numbering, missing seasons, specials that break ordering, and OVAs that do not exist in Western databases. This guide covers installation, configuration, and fixing the issues that come up with anime libraries.

Why HAMA Over Default Agents

Plex's built-in metadata agents (TheTVDB, TMDB) work well for Western TV but struggle with anime:

  • Episode numbering: Anime often uses absolute episode numbering (episode 1 through 500) rather than season-based numbering (S01E01). TheTVDB frequently changes its season structure for long-running anime, breaking existing libraries.
  • Specials and OVAs: Anime OVAs, ONAs, and specials are cataloged inconsistently across Western databases. Some are listed as Season 0 specials, others are separate series entries, and some are missing entirely.
  • Titles: Anime titles have Japanese, Romaji, and English variants. AniDB tracks all variants and matches regardless of which one your files use.
  • Multi-cour series: Anime series that air across multiple seasons (cours) are often listed as separate entries on TheTVDB but as one continuous series on AniDB.

HAMA uses AniDB as its primary source, which aligns with how anime is distributed and how most anime libraries are organized.

Prerequisites

ASS (Absolute Series Scanner)

HAMA requires the Absolute Series Scanner — a custom Plex scanner that supports absolute episode numbering. The default Plex Series Scanner expects SXXEXX format. ASS reads both SXXEXX and absolute formats and passes the correct information to HAMA.

AniDB Account

AniDB requires a registered account for API access. Create a free account at anidb.net. You need the username and password for HAMA configuration. AniDB enforces rate limits on API requests — do not share your credentials across multiple installations.

Installation

Install ASS (Absolute Series Scanner)

  1. Download the Absolute Series Scanner from its GitHub repository.
  2. Place the scanner file in your Plex scanners directory:
  • Windows: %LOCALAPPDATA%\Plex Media Server\Scanners\Series\
  • Linux: /var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Scanners/Series/
  • Docker: Inside the config volume at Library/Application Support/Plex Media Server/Scanners/Series/

Create the Scanners/Series directory if it does not exist.

Install HAMA

  1. Download the HAMA plugin from its GitHub repository.
  2. Place the entire plugin folder in the Plex plugins directory:
  • Windows: %LOCALAPPDATA%\Plex Media Server\Plug-ins\
  • Linux: /var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Plug-ins/
  • Docker: Inside the config volume at Plug-ins/

Restart Plex Media Server after installing both components.

Library Configuration

  1. Create a new library in Plex (or edit an existing anime library).
  2. Set the library type to TV Shows.
  3. Under Advanced settings, change the Scanner to Absolute Series Scanner.
  4. Change the Agent to HAS (HamaTV) — this is HAMA's display name in Plex.
  5. In the agent settings, enter your AniDB username and password.
  6. Configure metadata source priority. HAMA can pull data from multiple sources. A recommended order: AniDB for episode data, TheTVDB or TMDB for poster art (AniDB art quality is often lower).
  7. Save and scan the library.

File Naming for HAMA

Absolute Numbering

The simplest approach for HAMA: name files with absolute episode numbers.

Anime/Series Title/Series Title - 001.mkv

HAMA maps the absolute number to the correct AniDB episode. This works for both short series (12 episodes) and long-running series (500+ episodes).

AniDB ID Matching

For difficult matches, you can force HAMA to use a specific AniDB series ID by placing a file in the series folder:

Create a file named anidb.id containing just the AniDB series ID number. HAMA reads this file and uses the specified series instead of searching by title.

Season-Based Naming

HAMA also accepts standard SXXEXX naming through the Absolute Series Scanner. The scanner can be configured to map seasons to specific AniDB series entries using a custom mapping.

Series Mapping

HAMA includes a community-maintained mapping that connects TheTVDB season/episode numbers to AniDB entries. This mapping handles the common case where your files use TheTVDB numbering but you want AniDB metadata.

The mapping covers most popular anime series. For series not in the mapping, you have three options:

  • Rename files to use absolute numbering (simplest).
  • Add an anidb.id file to force the correct AniDB match.
  • Contribute a mapping to the community project (benefits everyone).

Handling Multi-Part Series

Sequels and Continuations

Anime sequels are typically separate entries on AniDB (Steins;Gate and Steins;Gate 0 are two distinct series). Store them in separate folders:

  • Anime/Steins;Gate (2011)/Steins;Gate - 001.mkv
  • Anime/Steins;Gate 0 (2018)/Steins;Gate 0 - 001.mkv

Split-Cour Series

Series that air in multiple cours (seasons with a break between them) may be one AniDB entry or multiple. Check AniDB for the specific series to determine how it is cataloged, then organize your files accordingly.

Movies and OVAs

Anime movies and OVAs associated with a series can be stored as specials:

Anime/Series Title/Specials/Series Title - S00E01 - OVA Title.mkv

Or as standalone entries in a separate anime movies library. The choice depends on whether you want them grouped with the TV series or browsable independently.

Poster Art and Metadata Quality

AniDB metadata is comprehensive for episode data but its poster art is often lower resolution than TheTVDB or TMDB. Configure HAMA to use a poster source priority that checks TMDB or TheTVDB first for artwork, falling back to AniDB for data that only AniDB has.

For specific series where the automatic art is poor, you can manually upload custom art through the Plex UI: click the series, select Edit, then Poster, and upload or search for a better image.

Troubleshooting

Series Not Matching

  • Check the AniDB page for your series to confirm the exact title HAMA should match against.
  • Add an anidb.id file with the correct series ID to force the match.
  • Verify your AniDB credentials are correct — expired or rate-limited accounts cause silent matching failures.

Episodes Out of Order

  • Verify your files use consistent numbering — either all absolute or all SXXEXX, not a mix.
  • Check whether the community mapping applies to your series. If the mapping is incorrect, absolute numbering with an anidb.id file is the most reliable fallback.

Specials Missing or Wrong

  • AniDB numbers specials differently from TheTVDB. Check AniDB for the special episode numbers and rename your files to match.
  • Place specials in a Season 00 or Specials folder with S00EXX numbering that corresponds to the AniDB special numbering.

AniDB Rate Limiting

AniDB enforces strict rate limits on API requests. When scanning a large library for the first time, the scan may take hours because HAMA must wait between requests. This is normal. Subsequent scans are faster because metadata is cached locally. Do not restart the scan when it appears slow — let it complete.

HAMA Not Appearing as Agent Option

  • Verify the plugin was placed in the correct directory with the correct folder name.
  • Restart Plex completely — not just a library refresh.
  • Check the Plex plugin log for errors loading the HAMA plugin.
← Back to Blog
More from LuxuriousComputers: LuxuriousComputers · Computer Repair · Remote Fix · Phone Repair · HVAC · Plex Support