[Metadata Source Plugin] Romance.io

[plain-cover]

This plugin adds Romance.io as a metadata source in Calibre. Romance.io is a community site for romance novels with detailed reader tags (tropes, themes, settings, etc.), steam ratings, and user star ratings.

When you download metadata for a book, Calibre will search Romance.io, and if there is a match, the plugin:

• Finds the Romance.io book ID and shows a link to the book's Romance.io page in the book details panel
• Offers Romance.io cover art as a download option alongside other sources
• Fills in series, series number, and publication date metadata from Romance.io
• Maps Romance.io genre tags (e.g. time travel, enemies to lovers, small town, nerdy hero) to Calibre tags via a configurable table

The stored romanceio identifier is also used by the companion Romance.io Fields plugin to fetch ratings and tags into custom columns.

For more detailed instructions, see the plugin's GitHub.

Installation:
In Calibre: Preferences > Plugins > Get new plugins, search for "Romance.io", and click Install. Or download the zip from GitHub and install via Preferences > Plugins > Load plugin from file.

Usage:

1. After installing, go to Preferences > Metadata download and check the box next to Romance.io to enable it as a source.
2. Select a book in your library, click Edit metadata, then click Download metadata. If a match is found on Romance.io, you'll see "See at: Romance.io" in the results. Click OK to link your Calibre library book with the book found on Romance.io and download metadata.

Configuration:
Preferences > Metadata download > Romance.io > Configure selected source

• Metadata fields to download - choose which fields to pull (cover, series, tags, date, etc.)
• Tag mappings - map Romance.io tags to Calibre tags. Only mapped tags are imported.

Wrong book matched? If your title or author in Calibre differs from Romance.io (different edition name, spelling, etc.), the automatic search may not work. You can still manually link the book: open the book's detail page on Romance.io (URL contains /books/, not the series page), copy the ID from the URL (e.g. 5484ecd47a5936fb0405756c), then in Calibre open Edit metadata > Ids and add romanceio:5484ecd47a5936fb0405756c.

Notes:

• The plugin tries the Romance.io JSON API first (fast, no browser). If the API returns no result, it falls back to loading the page in the browser. If a browser window opens, ignore it - it will close automatically.
• Only English is supported for now.

Source code, documentation, & issue reporting: GitHub

If you find this plugin useful, a small donation is appreciated!
Donate via PayPal

[plain-cover]

Development Builds

If you want to test the latest unreleased changes before they make it into an official release, development builds are available on GitHub.

Development builds may contain bugs. If you encounter an issue with a development build, please report it on GitHub Issues with:

• The version number of the development build you are using (shown in Preferences > Plugins)
• Steps to reproduce the issue
• Any error messages or logs (right-click the Preferences gear icon and choose Restart in debug mode for verbose output; or click the job count in the bottom-right of Calibre, select the failed job, and click Show job details)

To install a development build: download the zip from GitHub and install via Preferences > Plugins > Load plugin from file.

[scarlettruin]

I have tried using this and successfully brought the tags into a field, but when you map them via preferences>metadata download>romance.io plugin ot doesn't do anything. It seems to be because it pulls through fields as a continuous single option instead of a list of tags. It only shows as a single 'tag' even when there's 20+ tropes from romance.io

[plain-cover]

Originally Posted by scarlettruin

I have tried using this and successfully brought the tags into a field, but when you map them via preferences>metadata download>romance.io plugin ot doesn't do anything. It seems to be because it pulls through fields as a continuous single option instead of a list of tags. It only shows as a single 'tag' even when there's 20+ tropes from romance.io

Thank you for trying out the plugin! I can't seem to replicate your issue. From my machine, I can go through the steps in the screenshots below and get the tag mapping working for multiple fields. We must be doing something differently!

I did find a setting that might be related and I just updated the plugin to 1.0.3 in case that addresses your issue (it should be available in Calibre shortly), as well as making the Readme more clear. Can you try it out and, if it's still not working, give me some additional info:

• If you are doing any steps differently than I am in the attached screenshots, or if not, where your results are different from mine
• The Romance.io link to the book you're using
• The exact values for "Romance.io Genre" and "Maps to Calibre Tag" that aren't working
• What result you're getting vs. what result you expected

With that info I should be able to figure out what's going wrong!

[scarlettruin]

Sorry for the delay! This week is crazy - I will take a look when i have some time tomorrow. Thank you

[Rellwood]

So....was it supposed to create an over 225GB folder recreating every instance of Chrome User data for every download?

I feel bad for the people who thought to just let this thing run on overnight so they can get all the tags....

I have a 1 TB SSD that has never been more than 60% full. Between this and another program that initially downloaded every audiobook I own (over 400 books) to my C drive when I pointed it elsewhere - I maxed out the drive - wiped the shadow copies and incurred another 88GB pagefilesys that needs to be fixed.

I have been trying to delete this folder for over an hour - it still has 130GB to go.

Just thought you all should know.

[plain-cover]

Originally Posted by Rellwood

So....was it supposed to create an over 225GB folder recreating every instance of Chrome User data for every download?

I'm so sorry about that! I've been using the plugin for a few months myself and never ran into this because the JSON API used to work fine and Chrome was rarely needed. Since it went down about a week ago, the plugin has been relying on Chrome much more heavily, and you would definitely notice this if you're backfilling an entire library.

Luckily it was an easy fix. I've just updated the plugin (v1.0.6) so that the profile folders are now created in your system's TEMP directory and deleted immediately after Chrome closes. Even if Chrome crashes, the cleanup will still run. The plugin will also delete any leftover profile folders from the old location the next time it runs.

If you've already accumulated a lot of folders you could either:

1. Let the new version of the plugin (v1.0.6) clean up for you - just run it again after updating and it will delete the old folders automatically. If you have a lot of data built up, the first fetch may take a while to clean up before starting.

2. Delete the user_data folder manually to get the space back immediately. You can delete the entire user_data subfolder safely, since it's not related to your personal Chrome profile. The drivers and downloads subfolders next to it are fine to keep - those have the chromedriver binary and avoid re-downloading it every time. It's located here:

Windows: C:\Users\<your username>\.calibre_selenium\user_data\
Mac/Linux: ~/.calibre_selenium/user_data/

Thank you for noticing this and sorry again for filling up your computer

[scarlettruin]

I might be mixing this up with the other romance.io plugin, but i am having issues with both I think.

Looking first at the fields issue - my problem here is that the metadata download doesn't find anything from romance.io, even when ive made the same amendments to the configuration that you show in your screenshots. I've purposefully tried it on popular books that i know exist on romance.io, but i get nothing but the other sources - it says its checking romance.io but never ever finds metadata from it.

Is there anyway i can get data to find out why this would be? Does it need the latest update of Calibre itself?

I've attached where I have set everything up for the metadata download

[DNSB]

I downloaded the latest version from GitHub and unchecked my other metadata plugins. Testing on a couple of my spouse's book, I got a few tags, the series and index and a low res cover image. I did notice that Chrome popped up to fetch the page. The lack of a summary is pretty much a don't bother with this plugin for me since I normally leave the Tags unchecked in the metadata fields to download. My spouse wants the summary so again, making this plugin a non-starter.

[plain-cover]

Originally Posted by scarlettruin

I've attached where I have set everything up for the metadata download

I don't see an attachment - could you share the log output you're seeing in the plugin? That would help me figure out what's going wrong!

[plain-cover]

Originally Posted by DNSB

The lack of a summary is pretty much a don't bother with this plugin for me since I normally leave the Tags unchecked in the metadata fields to download. My spouse wants the summary so again, making this plugin a non-starter.

This is super helpful feedback, thank you! I'll take a stab at adding the summary for the next release. Hopefully it's not too complicated!

[plain-cover]

Originally Posted by DNSB

The lack of a summary is pretty much a don't bother with this plugin for me since I normally leave the Tags unchecked in the metadata fields to download. My spouse wants the summary so again, making this plugin a non-starter.

I have added the ability to download the book summary (into the Calibre "Comments" field) and rating metadata from Romance.io! Check out the latest version 1.1.0.

[scarlettruin]

Originally Posted by plain-cover

I don't see an attachment - could you share the log output you're seeing in the plugin? That would help me figure out what's going wrong!

Sure!

****************************** Romance.io (1, 1, 1) ******************************
Found 0 results
Downloading was aborted
identify - start. title=Haunting Adeline (Cat and Mouse Duet Book 1), authors=['H. D. Carlton'], identifiers={'mobi-asin': 'B09CLVJJ77'}
System info: OS=Windows 11 (10.0.26200), Python=3.14.2, Calibre=9.4.0
Searching for book...
Attempting JSON API search first...
JSON API request: https://www.romance.io/json/search_b...+H.+D.+Carlton
JSON API request failed: HTTPError 403: HTTP Error 403: Forbidden
✗ JSON API search attempt 1 failed: HTTPError: HTTP Error 403: Forbidden
Will retry in 2.0s...
JSON API search retry attempt 2/3...
JSON API request: https://www.romance.io/json/search_b...+H.+D.+Carlton
JSON API request failed: HTTPError 403: HTTP Error 403: Forbidden
✗ JSON API search attempt 2 failed: HTTPError: HTTP Error 403: Forbidden
Will retry in 2.0s...
JSON API search retry attempt 3/3...
JSON API request: https://www.romance.io/json/search_b...+H.+D.+Carlton
JSON API request failed: HTTPError 403: HTTP Error 403: Forbidden
✗ JSON API search attempt 3 failed: HTTPError: HTTP Error 403: Forbidden
✗ JSON API search failed after 3 attempts
JSON API had technical failures. Falling back to Chrome/HTML scraping...
Searching Romance.io: https://www.romance.io/search?q=Haun...+H.+D.+Carlton
Vendored import path: 'C:\\Users\\xxwil\\AppData\\Roaming\\calibre\\plug ins\\Romance.io.zip'
seleniumbase: loaded via direct zipimport
chromedriver found at 'C:\\Users\\xxwil\\.calibre_selenium\\drivers\\chr omedriver.exe'
Chrome version: 147.0.7727.102, chromedriver version: 147.0.7727.57
Page loaded successfully (747808 bytes)
Secondary element 'has-background' found
Found 50 search results
✓ HTML scraping found match: 60f280edb572b50e269dc061
Found 1 match(es), fetching detailed metadata...
Attempting JSON API fetch for 60f280edb572b50e269dc061...
JSON API request: https://www.romance.io/json/books/60...72b50e269dc061
JSON API request failed: HTTPError 403: HTTP Error 403: Forbidden
✗ JSON API fetch attempt 1 failed: HTTPError: HTTP Error 403: Forbidden
Will retry in 2.0s...
JSON API fetch retry attempt 2/3...
JSON API request: https://www.romance.io/json/books/60...72b50e269dc061
JSON API request failed: HTTPError 403: HTTP Error 403: Forbidden
✗ JSON API fetch attempt 2 failed: HTTPError: HTTP Error 403: Forbidden
Will retry in 2.0s...
JSON API fetch retry attempt 3/3...
JSON API request: https://www.romance.io/json/books/60...72b50e269dc061
JSON API request failed: HTTPError 403: HTTP Error 403: Forbidden
✗ JSON API fetch attempt 3 failed: HTTPError: HTTP Error 403: Forbidden
✗ JSON API fetch failed after 3 attempts
JSON API had technical failures. Falling back to HTML scraping for 60f280edb572b50e269dc061...
HTML fetch: requesting book page for 60f280edb572b50e269dc061
Vendored import path: 'C:\\Users\\xxwil\\AppData\\Roaming\\calibre\\plug ins\\Romance.io.zip'
seleniumbase: loaded via direct zipimport
chromedriver found at 'C:\\Users\\xxwil\\.calibre_selenium\\drivers\\chr omedriver.exe'
Chrome version: 147.0.7727.102, chromedriver version: 147.0.7727.57

[DNSB]

I did some testing on 1.1.1 and it seems to function well. The summary now has paragraph breaks. The cover images are still small but as near as I can tell from looking at the website, that is how romance.io stores them.

Here's the log file from one test:

Spoiler:

Running identify query with parameters:
{'title': 'A Duke Worth Choosing', 'authors': ['Sally Forbes'], 'identifiers': {'amazon_ca': 'B0GHZTZW1B', 'mobi-asin': 'B0GHZTZW1B', 'romanceio': '69748b025fa3d5ff5d4887ad'}, 'timeout': 30}
Using plugins: Romance.io (1, 1, 1)
The log from individual plugins is below

****************************** Romance.io (1, 1, 1) ******************************
Found 1 results
Downloading from Romance.io took 14.239079713821411


---
Title : A Duke Worth Choosing: A Historical Regency Romance Book
Author(s) : Sally Forbes
Tags : Historical, Romance
Series : Broken Dukes of Healing #1
Rating :
Published : 2026-01-22T00:00:00+00:00
Identifiers : romanceio:69748b025fa3d5ff5d4887ad
Comments : <p>“She’s worth forty thousand pounds… and not one person in London can be bothered to learn her name.” </p>
<p>She fled society to be free, only to find the one man who truly saw her. </p>
<p>Lady Charlotte Fairfax is the Season’s most glittering prize, and its most exhausted prisoner. Dukes and earls circle her like creditors, her parents calculate her future like an investment, and every dance feels like a bargain struck over her heart. </p>
<p>So Charlotte does the only scandalous thing left. </p>
<p>She disappears. </p>
<p>With a borrowed name and a plain gown, she flees Mayfair’s marriage mart to Berkshire, accepting a quiet post as a respectable widow’s companion, determined to be valued for her mind, her kindness, and her courage… not her dowry. </p>
<p>But peace at Harcourt Hall doesn’t last. </p>
<p>Major Nathaniel Harcourt returns home wounded from war—stern, honorable, and far too perceptive. He’s not interested in flirtation, or society games… until he meets the new companion who speaks like a lady, watches like a strategist, and hides a secret heavy enough to ruin them both. </p>
<p>As village gossip blooms, stolen glances turn to stolen moments, and a sharp-eyed guardian begins to suspect the truth. Because if Charlotte is found, her father will drag her back to London, and into a loveless match arranged for power and profit. </p>
<p>Now Charlotte must choose to<br />
return to the gilded cage… or risk everything for a love that finally sees her. </p>
<p>A clean, swoony Regency romance featuring a runaway heiress, a wounded war hero, a country house haven, witty banter, slow-burn tenderness, and a satisfyingly triumphant happily-ever-after.Also free with Kindle unlimited.</p>
identify - start. title=A Duke Worth Choosing, authors=['Sally Forbes'], identifiers={'amazon_ca': 'B0GHZTZW1B', 'mobi-asin': 'B0GHZTZW1B', 'romanceio': '69748b025fa3d5ff5d4887ad'}
System info: OS=Windows 11 (10.0.26200), Python=3.14.2, Calibre=9.7.0
Found 1 match(es), fetching detailed metadata...
Attempting JSON API fetch for 69748b025fa3d5ff5d4887ad...
JSON API request: https://www.romance.io/json/books/69...a3d5ff5d4887ad
JSON API endpoint unavailable (404): https://www.romance.io/json/books/69...a3d5ff5d4887ad
JSON API: book 69748b025fa3d5ff5d4887ad not available via JSON (404), will try HTML
✗ JSON API fetch attempt 1 failed: JsonApiBookNotFoundError: JSON API: book 69748b025fa3d5ff5d4887ad not available via JSON (404), will try HTML
Book not found in JSON API (404), skipping retries. Will try HTML.
JSON API had technical failures. Falling back to HTML scraping for 69748b025fa3d5ff5d4887ad...
HTML fetch: requesting book page for 69748b025fa3d5ff5d4887ad
Vendored import path: 'C:\\Users\\dbowe\\AppData\\Roaming\\calibre\\plug ins\\Romance.io.zip'
seleniumbase: loaded via direct zipimport
chromedriver found at 'C:\\Users\\dbowe\\.calibre_selenium\\drivers\\chr omedriver.exe'
Chrome version: 147.0.7727.102, chromedriver version: 147.0.7727.117
Page loaded successfully (112137 bytes)
HTML fetch: parsing 112137 bytes of HTML for 69748b025fa3d5ff5d4887ad
HTML fetch: page validated, extracting metadata for 69748b025fa3d5ff5d4887ad
✓ HTML scraping found match: HtmlElement
parse_title (raw): A Duke Worth Choosing: A Historical Regency Romance Book

(Broken Dukes of Healing #1)
parse_title (cleaned): A Duke Worth Choosing: A Historical Regency Romance Book
parse_authors: ['Sally Forbes']
parse_series_from_title: series_name='Broken Dukes of Healing', series_index='1.0'
parse_tags: found 3 tags
parse_publish_date: 2026-01-22 00:00:00+00:00
parse_description: extracted 1720 characters
_build_metadata_from_html - romanceio_id: 69748b025fa3d5ff5d4887ad, mi: Title : A Duke Worth Choosing: A Historical Regency Romance Book
Author(s) : Sally Forbes
Series: 'Broken Dukes of Healing' (index: 1.0)
Tags from Romance.io (3): ['victorian', 'regency', 'historical']
Final tags (2): ['Historical', 'Romance']
setting pubdate: 2026-01-22 00:00:00+00:00
setting rating: 0 (source: 0.0)
setting comments (1729 chars)
_build_metadata_from_html - final mi.pubdate: datetime.datetime(2026, 1, 22, 0, 0, tzinfo=datetime.timezone.utc)

************************************************** ******************************
The identify phase took 14.24 seconds
The longest time (14.239080) was taken by: Romance.io
Merging results from different sources
We have 1 merged results, merging took: 0.00 seconds

[plain-cover]

Originally Posted by scarlettruin

Sure!

****************************** Romance.io (1, 1, 1) ******************************
Found 0 results

Thanks for the logs! Now I see what's going wrong. The first error you're hitting is that your IP address is being blocked by Cloudflare when the plugin tries to reach Romance.io's JSON API (HTTP 403 Forbidden). This doesn't happen on any IP address I've tested on and I haven't heard about it from any other users so far so I think this is specific to your IP address. It may be due to using a VPN or a shared high-traffic IP that Cloudflare has flagged.

The plugin falls back to Chrome when JSON fails, and Chrome did find your book successfully, but because I didn't have specific handling for 403s, we were retrying the same failed JSON API request 3x, which took long enough that I think Calibre's metadata download system was timing out. So you got 0 results despite the book actually being found.

The new v1.1.2 adds 403 handling so we won't keep retrying, but instead skip directly to the working Chrome download. If it still times out, now you'll at least get the title, authors, cover, and Romance.io identifier rather than nothing.

Give it a try and let me know if you're still seeing any issues!