[GUI Plugin] CleanRead

JHAT · 05-22-2026, 02:08 PM

CleanRead — Calibre Plugin
Author: JHAT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DESCRIPTION:

CleanRead is a language filter that sanitizes EPUB files for a cleaner reading experience by attempting to replace strong profanity with context-aware substitutions — handling compound words, dialect forms, verb uses, and idiomatic phrases — while preserving the author's voice and narrative tone.

Free Version - Fast, Less Precise, Customized Word Replacement
AI Enhanced Version - Slower, More Precise. Supports Anthropic and OpenAI. Requires Internet Connection and API Key. Minimal cost.

The original EPUB is never lost. The cleaned file keeps the original
filename (.epub) and the untouched original is automatically archived
alongside it as .ORIGINAL_EPUB. Both formats are registered in your
Calibre library so you can access either at any time.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
INSTALLATION

1. Download CleanRead_v2.0.0.zip (attached below)
2. In Calibre: Preferences → Plugins → Load plugin from file
3. Select CleanRead_v2.0.0.zip
4. Restart Calibre
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
USAGE

1. Select a book in your Calibre library
2. Select desired processing mode
3. If Free Mode, to check the word mapping, click "Customized Replacement Words" button. Double click a cell to change, click Save.
4. If AI Enhanced Mode, select Provider and click API Key Settings
5. Enter your API Key, Click Test Connection, Click Save.
6. Click ▶ Start

A summary report is shown when processing is complete.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
REQUIREMENTS

• Calibre 5.0 or later
• Windows, macOS, or Linux
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CHANGELOG

v2.0.0 (2026-05-23)

Removed flagged cleaning feature
Added Light/Dark mode compatibility, improving readability in dark mode
Implemented a profanity toggle to allow user to see / hide profanity in summary writeup
Added before and after so user can inspect changes. (Still working a screen sizing and column reset bug, but usable)
Updated to provide an AI option
Implemented customized word replacement for Free Mode (not required to AI Enhanced)

v1.0.0 (2026-05-22)
• Initial release

NOTE: Both AI processes, run very well. OpenAI tends to run long (avg 25 minutes depending on the length of the book). Anthropic tends to run more quickly (avg 2 minutes depending on the length of the book). This is driven based on your Rate Limits (Tier of service purchased), coupled with Model Speed. Regardless, both cost about the same .10-.15 cents. I will continue to tweak performance, however, there is only so much I can do on the performance side for OpenAI without purchasing a higher tier.

JSWolf · 05-22-2026, 02:54 PM

The plugin mostly works. But not fully. The problem is I have a sentence that not longer works when the plugin changes the profanity. You should to look for f*ck off and change it to something like bugger off.

Code:

‘Yup, well you can hell off. What do you want?’

Another phrase that's not done correctly is jack sh*t. You can use bugger all.

Code:

The press don’t know you, and even if they did, they don’t give Jack Crap.

Another phrase that wasn't translated correctly is f*ck-off. You could use piss off or sod off.

Code:

Recently built a hell-off development—an old warehouse on Shoreham Harbour.

Yet another is bad sh*t. Make it trouble.

Code:

‘You in some kind of bad crap?’ the American voice said.
Still unsure whether this was some kind of game, Michael said, ‘Bad crap, you got it.’

when the original says No sh*t Sherlock, there's nothing you can do to change it unless you change the entire phrase.

Code:

‘Right! No crap, Sherlock.’

Another that needs a revision. F*ck it does not work as it's changed. Use To hell with it.

Code:

‘Hell it,’ Mark said, brushing her aside, and eyeballing Grace again.

Give a f*ck should be changed to give a damn.

Code:

‘So I read in the stuff I downloaded from the net,’ he replied.</p>You don’t give a hell, do you?’

This one is more difficult. The original is F*ck me and what it got changed to does not work. In fact, I'm not sure what would work in place because those two words can mean different things.

Code:

Slipping her hands out, she reached around him, clicked his mouse to exit the program, then whispered into his ear, ‘Hell me.’

The original word is b*tch and changing it to witch works where what's used fails.

Code:

<p>‘So I read in the stuff I downloaded from the net,’ he replied.</p>‘You know, you can be such a complain at times,’ Branson said, reluctantly following him to the main entrance, through the doors and up the staircase past the displays of  truncheons.

JSWolf · 05-22-2026, 03:18 PM

One different problem. In one of the chapters, the plugin removed the entire paragraph. Here is what was removed.

Code:

<p>‘So I read in the stuff I downloaded from the net,’ he replied.</p>

JHAT · 05-22-2026, 03:18 PM

Jon, thank you for the feedback! I have tried to account for some of the edge cases and thought I had most of them. I will work to incorporate these into the next version.

I will check the removed paragraph issue as well. In my testing I haven't run into that before. May I ask the book you are running this against? I would like to test using the same parameters. Thanks!!

JSWolf · 05-22-2026, 03:57 PM

Quote:

Originally Posted by JHAT

Jon, thank you for the feedback! I have tried to account for some of the edge cases and thought I had most of them. I will work to incorporate these into the next version.

I will check the removed paragraph issue as well. In my testing I haven't run into that before. May I ask the book you are running this against? I would like to test using the same parameters. Thanks!!

I don't know if I've edited my post since you replied. So you may want to read it again.

Anyway, it works not bad. Once you fix these things, it will work better. I know it can be hard to think of everything.

Happy to help.

In case you want to get the book I used, it is Dead Simple by Peter James. It's the first book in the Roy Grace series.

BetterRed · 05-22-2026, 06:16 PM

Windows 10, Calibre 9.8

Cannot read the popup text in Dark mode:

Click image for larger version

Name: Screenshot 2026-05-23 074913.jpg
Views: 20
Size: 44.1 KB
ID: 223483

Plugin should respect the Tweaks->save_original_format setting. I have it set to False, the widely used Modify Epub plugin respects the setting, so there's a precedent.

When I add a book I put a copy of the 'original' in the book's data folder. Calibre's '.ORIGINAL_XXXX' scheme does not suit my workflow patterns.

Suggested enhancement: allow user to maintain substitutes e.g. 'naff all' for 'bugger all', 'foxtrot oscar' for 'f*** off'.

BR

JSWolf · 05-22-2026, 06:48 PM

One problem is what to do when a word of phrase can have multiple meaning.

Comfy.n · 05-22-2026, 07:02 PM

I googled foxtrot oscar, lol.

Havent tried the plugin yet, but I'm following the discussion. ^ ^

Comfy.n · 05-22-2026, 07:35 PM

Quote:

Originally Posted by BetterRed

Windows 10, Calibre 9.8
Cannot read the popup text in Dark mode:

Yes.

a** 17 occurrences
b**** 1 occurrences
d*** 6 occurrences
f*** 172 occurrences
g***** 2 occurrences
s*** 55 occurrences

How about adding an option to show the full words in the above summary, and perhaps add a report option to show before/after snippets?

Wiggo · 05-22-2026, 11:00 PM

Quote:

Originally Posted by Comfy.n

Yes.

a** 17 occurrences
b**** 1 occurrences
d*** 6 occurrences
f*** 172 occurrences
g***** 2 occurrences
s*** 55 occurrences

How about adding an option to show the full words in the above summary, and perhaps add a report option to show before/after snippets?

I'm really wondering what g***** is? You could turn this plugin into a little in-Calibre game.

I would call the plug-in C.U.N.T. - Clean Up Naughty Terms.

Comfy.n · Yesterday, 05:09 AM

Quote:

Originally Posted by Wiggo

I'm really wondering what g***** is? You could turn this plugin into a little in-Calibre game.

I would call the plug-in C.U.N.T. - Clean Up Naughty Terms.

and then one would need a plugin to clean up plugins naughty names...

Dr. Drib · Yesterday, 06:51 AM

I think a plugin of this nature is just plain silly.

It reminds me of the high school that prevented students from doing research on breast cancer using the internet.

Here, let me write that word again and boldface it: breast.

How strange: As I look around me, I see the world has not imploded. (I admit to seeing someone who actually scratched his ass [excuse me: 'behind'] while walking down the street, but his action may be attributed to a lack of social skills.)

If certain words are bothersome, then don't read the book. One can always read solely YA fiction or books of such nature where the reality of the world is mostly absent. I think that Literature that inquires into the nature of who we are and how we (re)act with one another is what will endure; and, actually, I feel that ANY genre of (non)fiction/literature that remains honest with its readers is what really matters.

As for issues of piracy, Mobileread does NOT condone piracy in any shape or form. A plugin that specifically removes "piracy metadata" speaks volumes about what this plugin is partially interested in.

JHAT · Yesterday, 08:38 AM

Thanks Everyone for your thoughts and feedback (and humor)

.
I am new to this thread and this is my first plugin attempt and I appreciate the support to improve. I created a new post with version 1.1.0. I'm not sure if that is right protocol?

@Dr.Drib, thank you for highlighting the point on piracy. I do not condone piracy and will add a disclaimer in the next iteration. Poor choice of words on my part. My intention is to identify "data" that doesn't look natural. epubs are mostly html, xml, css, which makes it very easy for alterations to be imped text/hyperlinks, etc. Public Domain material typically have added pages with links out. May be more appropriately titled "vulnerability checks" or something like that. I'll wordsmith it.

DiapDealer · Yesterday, 08:50 AM

A plugin that claims to remove watermarks is also arguably not something Mobileread would wish to host. Watermarking is still a form of DRM. Mobileread will not host drm-removal software.

JSWolf · Yesterday, 08:51 AM

Quote:

Originally Posted by JHAT

Thanks Everyone for your thoughts and feedback (and humor)

.
I am new to this thread and this is my first plugin attempt and I appreciate the support to improve. I created a new post with version 1.1.0. I'm not sure if that is right protocol?

@Dr.Drib, thank you for highlighting the point on piracy. I do not condone piracy and will add a disclaimer in the next iteration. Poor choice of words on my part. My intention is to identify "data" that doesn't look natural. epubs are mostly html, xml, css, which makes it very easy for alterations to be imped text/hyperlinks, etc. Public Domain material typically have added pages with links out. May be more appropriately titled "vulnerability checks" or something like that. I'll wordsmith it.

You need to ask to have that thread deleted. You do not create a new thread for a new plugin version. You edit the first post of this thread to replace the old version with the new version and you edit the post to give info on the new post. So please edit the first post in this thread.

OH and you will need to remove the clean & strip section of the plugin.

05-22-2026, 02:54 PM	#2
JSWolf Resident Curmudgeon Posts: 83,488 Karma: 153646249 Join Date: Nov 2006 Location: Roslindale, Massachusetts Device: Kobo Libra 2, Kobo Aura H2O, PRS-650, PRS-T1, nook STR, PW3	The plugin mostly works. But not fully. The problem is I have a sentence that not longer works when the plugin changes the profanity. You should to look for fck off and change it to something like bugger off. Code: ‘Yup, well you can hell off. What do you want?’ Another phrase that's not done correctly is jack sht. You can use bugger all. Code: The press don’t know you, and even if they did, they don’t give Jack Crap. Another phrase that wasn't translated correctly is fck-off. You could use piss off or sod off. Code: Recently built a hell-off development—an old warehouse on Shoreham Harbour. Yet another is bad sht. Make it trouble. Code: ‘You in some kind of bad crap?’ the American voice said. Still unsure whether this was some kind of game, Michael said, ‘Bad crap, you got it.’ when the original says No sht Sherlock, there's nothing you can do to change it unless you change the entire phrase. Code: ‘Right! No crap, Sherlock.’ Another that needs a revision. Fck it does not work as it's changed. Use To hell with it. Code: ‘Hell it,’ Mark said, brushing her aside, and eyeballing Grace again. Give a fck should be changed to give a damn. Code: ‘So I read in the stuff I downloaded from the net,’ he replied.</p>You don’t give a hell, do you?’ This one is more difficult. The original is Fck me and what it got changed to does not work. In fact, I'm not sure what would work in place because those two words can mean different things. Code: Slipping her hands out, she reached around him, clicked his mouse to exit the program, then whispered into his ear, ‘Hell me.’ The original word is btch and changing it to witch works where what's used fails. Code: <p>‘So I read in the stuff I downloaded from the net,’ he replied.</p>‘You know, you can be such a complain at times,’ Branson said, reluctantly following him to the main entrance, through the doors and up the staircase past the displays of truncheons. Last edited by JSWolf; 05-22-2026 at 03:37 PM.*

05-22-2026, 03:18 PM	#3
JSWolf Resident Curmudgeon Posts: 83,488 Karma: 153646249 Join Date: Nov 2006 Location: Roslindale, Massachusetts Device: Kobo Libra 2, Kobo Aura H2O, PRS-650, PRS-T1, nook STR, PW3	One different problem. In one of the chapters, the plugin removed the entire paragraph. Here is what was removed. Code: <p>‘So I read in the stuff I downloaded from the net,’ he replied.</p>

05-22-2026, 03:18 PM	#4
JHAT Member Posts: 10 Karma: 10 Join Date: May 2026 Device: Kindle	Jon, thank you for the feedback! I have tried to account for some of the edge cases and thought I had most of them. I will work to incorporate these into the next version. I will check the removed paragraph issue as well. In my testing I haven't run into that before. May I ask the book you are running this against? I would like to test using the same parameters. Thanks!! Last edited by JHAT; 05-22-2026 at 03:21 PM.

05-22-2026, 06:16 PM	#6
BetterRed null operator (he/him) Posts: 22,681 Karma: 33011292 Join Date: Mar 2012 Location: Sydney Australia Device: none	Windows 10, Calibre 9.8 Cannot read the popup text in Dark mode: Plugin should respect the Tweaks->save_original_format setting. I have it set to False, the widely used Modify Epub plugin respects the setting, so there's a precedent. When I add a book I put a copy of the 'original' in the book's data folder. Calibre's '.ORIGINAL_XXXX' scheme does not suit my workflow patterns. Suggested enhancement: allow user to maintain substitutes e.g. 'naff all' for 'bugger all', 'foxtrot oscar' for 'f*** off'. BR

Yesterday, 06:51 AM	#12
Dr. Drib Grand Sorcerer Posts: 46,044 Karma: 61392301 Join Date: Jan 2007 Location: Peru Device: KINDLE: Oasis 3, Scribe (1st), Matcha; KOBO: Libra 2, Libra Colour	I think a plugin of this nature is just plain silly. It reminds me of the high school that prevented students from doing research on breast cancer using the internet. Here, let me write that word again and boldface it: breast. How strange: As I look around me, I see the world has not imploded. (I admit to seeing someone who actually scratched his ass [excuse me: 'behind'] while walking down the street, but his action may be attributed to a lack of social skills.) If certain words are bothersome, then don't read the book. One can always read solely YA fiction or books of such nature where the reality of the world is mostly absent. I think that Literature that inquires into the nature of who we are and how we (re)act with one another is what will endure; and, actually, I feel that ANY genre of (non)fiction/literature that remains honest with its readers is what really matters. As for issues of piracy, Mobileread does NOT condone piracy in any shape or form. A plugin that specifically removes "piracy metadata" speaks volumes about what this plugin is partially interested in. Last edited by Dr. Drib; Yesterday at 06:58 AM.

05-22-2026, 06:48 PM	#7
JSWolf Resident Curmudgeon Posts: 83,488 Karma: 153646249 Join Date: Nov 2006 Location: Roslindale, Massachusetts Device: Kobo Libra 2, Kobo Aura H2O, PRS-650, PRS-T1, nook STR, PW3	One problem is what to do when a word of phrase can have multiple meaning.

05-22-2026, 07:02 PM	#8
Comfy.n want to learn what I want Posts: 2,215 Karma: 7966751 Join Date: Sep 2020 Device: Libra Colour	I googled foxtrot oscar, lol. Havent tried the plugin yet, but I'm following the discussion. ^ ^

Yesterday, 08:38 AM	#13
JHAT Member Posts: 10 Karma: 10 Join Date: May 2026 Device: Kindle	Thanks Everyone for your thoughts and feedback (and humor) . I am new to this thread and this is my first plugin attempt and I appreciate the support to improve. I created a new post with version 1.1.0. I'm not sure if that is right protocol? @Dr.Drib, thank you for highlighting the point on piracy. I do not condone piracy and will add a disclaimer in the next iteration. Poor choice of words on my part. My intention is to identify "data" that doesn't look natural. epubs are mostly html, xml, css, which makes it very easy for alterations to be imped text/hyperlinks, etc. Public Domain material typically have added pages with links out. May be more appropriately titled "vulnerability checks" or something like that. I'll wordsmith it.

Yesterday, 08:50 AM	#14
DiapDealer Grand Sorcerer Posts: 29,457 Karma: 212177022 Join Date: Jan 2010 Device: Nexus 7, Kindle Fire HD	A plugin that claims to remove watermarks is also arguably not something Mobileread would wish to host. Watermarking is still a form of DRM. Mobileread will not host drm-removal software.

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
[GUI Plugin] Streamer - RSVP Speed Reader plugin for Calibre	npapadacis	Plugins	6	04-24-2026 03:00 AM
[Plugin] LOI-Generator - edit] plugin to generate a List of Illustrations	KevinH	Plugins	1	01-19-2023 04:31 PM
[Metadata Source Plugin] Empty Plugin? (Fake Identifier)	mneimeyer	Plugins	3	11-11-2019 08:07 PM
[Plugin] QuickPrefsEdit - Edit plugin prefs json files.	slowsmile	Plugins	3	07-25-2018 08:14 PM
Goodread Perception Expander plugin not shown on plugin list (kobo h2o)	www	KOReader	4	09-28-2017 10:34 AM