Search and tag comics, manga, manhwa, manhua, bande dessinée and magazines from VerseDB without leaving ComicTagger. This plugin adds VerseDB as a metadata source next to Comic Vine, Metron and GCD, so you can match a series and write full metadata straight to your archives.
VerseDB is a community-driven comic book database. It catalogues over a million issues across 150,000+ series, with 168,000+ characters, 86,000+ creators and thousands of teams and story arcs. Unlike most comic databases, it isn't built around western single issues alone. Manga, manhwa, manhua, bande dessinée and magazines are all first-class.
A few things make it a good source to tag from:
- Broad coverage. Western comics sit next to manga and international formats, so one source can tag a mixed shelf. Right-to-left reading is detected and flagged for manga.
- Curated accuracy. Records are maintained and corrected by collectors through a moderation system and reconciled across several data sources, so credits, characters and arcs stay clean.
- Key issues marked. First appearances, origins, deaths and major events are tagged on the issues that carry them.
- API-first. This plugin talks to VerseDB's documented public REST API, the same one that powers the website and mobile apps.
A free account is enough to tag with, and the whole catalogue is free to read. Pro raises the request budget, which is what matters for bulk runs (see Rate limits and caching).
- ComicTagger 1.6.0b7 or later (the release that added the rate-limit callback the plugin uses).
- A VerseDB account and a personal API token with the
read:publicscope. A free account can create one.
How you install depends on how you run ComicTagger.
The packaged builds don't have a Python environment to install into, so they load plugins from a folder:
-
Download
versedb_talker-1.0.0-py3-none-any.whlfrom the latest release. -
Move the
.whlinto ComicTagger's plugin directory (leave it as a file, don't unzip it):- Windows:
%APPDATA%\ComicTagger\plugins - macOS:
~/Library/Application Support/ComicTagger/plugins - Linux:
~/.config/ComicTagger/plugins
ComicTagger also shows this path under Settings as a clickable "Plugin Dir" link, if you'd rather open it from the app.
- Windows:
-
Restart ComicTagger, then select VerseDB under Settings → Comic Sources.
When you upgrade, delete the old .whl first: ComicTagger loads every plugin file in the folder and doesn't compare versions, so two copies will clash.
Rather build it yourself? From a checkout:
pip install build
python -m build
# produces dist/versedb_talker-1.0.0-py3-none-any.whlIf you run ComicTagger out of a Python environment, install the talker into that same environment. ComicTagger picks it up through the comictagger.talker entry point, so there's nothing else to register:
pip install versedb_talker-1.0.0-py3-none-any.whl # the wheel from the latest release
pip install . # from a checkoutRestart ComicTagger either way.
Open Settings → Comic Sources and select VerseDB, or pass the flags on the command line:
| Setting | CLI flag | Notes |
|---|---|---|
| API Key | --versedb-key |
Your personal API token. Required. |
| API URL | --versedb-url |
Defaults to https://versedb.com/api/v1/. Only change this for a self-hosted or staging instance. |
| Use series start as volume | --versedb-use-series-start-as-volume |
Writes the series start year into the volume field instead of the volume number. |
| Fetch variant covers | --versedb-fetch-variant-covers |
Fetches alternate variant covers to help cover matching. Adds one request per issue that has variants, so it's off by default. |
Use Test Source to check the token before you start tagging.
A single issue lookup returns almost everything ComicTagger keeps, so tagging an issue is usually one request:
| ComicTagger field | Comes from |
|---|---|
| series / issue / title | series name, issue_number, issue name |
| series aliases | series alias list |
| publisher / imprint | issue publisher and imprint |
| year / month / day | cover_date, falling back to release_date |
| volume | series volume number (or start year, with the option above) |
| issue count | series cached_issues_count |
| description | issue solicitation, the publisher's own copy |
| genres | series genres |
| credits | issue creators, with their role |
| characters / teams / story arcs | the matching issue fields |
| locations | issue locations (a free-text list) |
| page count / price | issue page_count and price |
| gtin | first of isbn, upc, ean |
| language / format | series language and format |
| maturity rating | issue content_rating_label |
| critical rating | issue average rating |
| manga flag | series medium (manga reads right-to-left; manhwa and manhua are flagged as manga) |
| series group | the franchise the series belongs to, e.g. Batman |
| cover | images.cover_lg |
| alternate covers | issue variant covers, with the "Fetch variant covers" option above |
| web link | https://versedb.com/issue/{id}/{slug} |
When ComicTagger asks for a series rather than an issue, the series description comes from the series' publisher_description — again the publisher's own copy, and blank where there isn't any.
The API allows 300 requests an hour and 4,000 a day on the free tier, and 1,000 an hour and 20,000 a day on Pro, counted against your account. The talker leaves a short gap between requests and stores results in ComicTagger's cache, so repeat lookups don't go back to the server. If it does hit a 429 it waits out the Retry-After window and retries.
A large tagging run can still use up the free-tier budget, so Pro is the better fit for bulk work. If a run starts failing with rate-limit errors and waiting a few minutes doesn't help, it's likely the daily cap rather than the hourly one, and the budget won't come back until the next day.
VerseDB's own IDs are used as the source identifiers. The public API doesn't expose Comic Vine, GCD or Metron IDs, so there's no match-by-foreign-id shortcut: matching works by series search and issue number, the same as the other talkers.
The public API returns the whole catalogue: unlike the VerseDB website and mobile app, it does not filter results by the content preferences on your account (NSFW visibility, hidden mediums, languages or genres). Searches here can therefore turn up series you've hidden elsewhere.
pip install -r requirements-dev.txt
pip install -e .Apache-2.0. See LICENSE.