[GUI Plugin] FanFicFare

[ownedbycats]

Originally Posted by JimmXinu

New Test Version Posted

2026-05-22
- Add retry_failedtoload_images option
- PI: Don't throw notifications when doing show_message()
- PI: INI Snippets

Three changes to this version:

PI: Don't throw notifications when doing show_message() -- What it says. FFF shouldn't generate notifications any time it shows a status message.

Add retry_failedtoload_images option -- When retry_failedtoload_images:true and you update an epub with images that failed to download since the image handling update back in Jan2026, FFF will retry them.

(I need to add the description for this to defaults.ini. This hasn't been hugely tested because my commonly updated stories don't have failed images, apparently.)

However, I don't think this should be turned on all the time, so I finally implemented:

PI: INI Snippets - Under 'Show Download Options' on the Add / Update dialog boxes there's now a dropdown for 'INI Snippet'. You can enter a one-time INI snippet, or use previously saved snippets.

FFF will offer to save one-time snippets and there's basic add/edit/remove snippets under the personal.ini tab in FFF config.

A new snippet will already have an [overrides] section. You can use other sections instead. But even if you remove all sections, FFF will still inject an [overrides] section header in front of the snippet because these are meant to be highest priority.

My personal use cases for this are retry_failedtoload_images as mentioned above, and ffnet check_next_chapter.

After I already set this up

[texasnightowl]

Originally Posted by JimmXinu

Here's one way:

[defaults]
# create a couple new entries.
# note the leading ',' it's necessary.
add_to_extra_valid_entries:,romships,platships

# copy regular ships into them.  
# All replace_meetadata/etc for ships will already be done.
include_in_romships:ships
include_in_platships:ships

# keep only those containing / in romships
include_metadata_pre:
 romships=~/

# remove any containing / from platships
exclude_metadata_pre:
 platships=~/

# put them in your columns.
# Use your custom column identifiers instead of #romships / #platships.
add_to_custom_columns_settings:
 romships=>#romships
 platships=>#platships

I added this code to my personal.ini and it's mostly working? But romships are not kept in the original ships order when sent to the custom column?

Example, this story has relationships listed as follows in my custom metadata column:

<p><span class='label'>Relationships</span>: <div class='metadata list' id='ships'><ul>
<li>James "Bucky" Barnes/Darcy Lewis</li>
<li>James "Bucky" Barnes/Steve Rogers</li>
<li>Darcy Lewis/Steve Rogers</li>
<li>James "Bucky" Barnes/Darcy Lewis/Steve Rogers</li>
<li>background Natasha Romanov/Clint Barton</li>
<li>background Tony Stark/Pepper Potts</li>
<li>Steve Rogers/Peggy Carter</li>
</ul></div><p>

But when romships writes to my custom column, the order is: background Natasha Romanov/Clint Barton, background Tony Stark/Pepper Potts, Darcy Lewis/Steve Rogers, James "Bucky" Barnes/Darcy Lewis, James "Bucky" Barnes/Darcy Lewis/Steve Rogers, James "Bucky" Barnes/Steve Rogers, Steve Rogers/Peggy Carter


My keep_in_order_ships:true line appears to work since the list is correct. So, how can I keep the "romships" in the same orders as the original ships list? (I tried to add a keep_in_order_romships:true and refreshed from saved metadata but that did not work.)

edit: adding my personal.ini with most commented stuff removed to shorten it up more.

## This is an example of what your personal configuration might look
## like.  Uncomment options by removing the '#' in front of them.

[defaults]
## [defaults] section applies to all formats and sites but may be
## overridden at several levels.  See
## https://github.com/JimmXinu/FanFicFare/wiki/INI-File for more
## details.

## firefox browser cache on new PC as of January 2025
## C:\Users\name\AppData\Local\Mozilla\Firefox\Profiles\kgl3ip34.default-release\cache2 
browser_cache_path:C:\Users\name\AppData\Local\Mozilla\Firefox\Profiles\kgl3ip34.default-release\cache2

is_adult:true


## Items to include in the title page
## this is the default
#titlepage_entries: seriesHTML,category,genre,language,characters,ships,status,datePublished,dateUpdated,dateCreated,rating,warnings,numChapters,numWords,publisher,description


## to change the order, ie. move genre to the end, after
## the summary, try
titlepage_entries: seriesHTML,category,language,characters,ships,status,datePublished,dateUpdated,dateCreated,rating,warnings,numChapters,numWords,publisher,description,<p>,<p>,<p>,genre


[epub]

## titlepage entry format
## ${id}, ${label}, ${value}
titlepage_entry:
 <b>${label}:</b> ${value}<br /><br />


[fanfiction.net]
username:XXXXXXXX
password:XXXXXXXX
use_basic_cache:true
continue_on_chapter_error:true
use_browser_cache:true
open_pages_in_browser:true
use_browser_cache_only:true
never_make_cover:true
skip_author_cover:true
slow_down_sleep_time:12
ships_label:Pairings
## How do I exclude "genre" as I don't want those tags?
include_subject_tags: extratags, category, characters, ships, status


[archiveofourown.org]
## include_subject_tags: extratags, genre, category, characters, ships, lastupdate, status
## I removed genre which seems to remove/hide all the freeform tags
include_subject_tags: extratags, category, characters, ships, status

username:XXXXXXXX
password:XXXXXXXX
slow_down_sleep_time:4

## if having issues, can try
use_archiveofourown_gay:true


keep_in_order_characters:true
keep_in_order_ships:true
keep_in_order_genre:true
keep_in_order_category:true


## extra_valid_entries:chapterslashtotal, chapterstotal
## removed kudos, hits, bookmarks, collections, collectionsURL, 
## collectionsHTML, bookmarked, bookmarktags, bookmarksummary, 
## bookmarkprivate, bookmarkrec, subscribed, markedforlater, 
## restricted
extra_valid_entries:fandoms, freeformtags, freefromtags,
 ao3categories, chapterslashtotal, chapterstotal, 
 subscribed, markedforlater, restricted, series00, 
 series01, series02, series03, series00Url, series01Url, 
 series02Url, series03Url, series00HTML,
 series01HTML, series02HTML, series03HTML
chapterslashtotal_label:Chapters/Total Chapters
chapterstotal_label:Total Chapters
fandoms_label:Fandoms
freeformtags_label:Freeform Tags
freefromtags_label:Freeform Tags
ao3categories_label:AO3 Categories
#comments_label:Comments
#collections_label:Collections
#collectionsHTML_label:CollectionsHTML
## removed comments, kudos, hits, bookmarks, collections
## collectionsURL, collectionsHTML, bookmarked, bookmarktags
## bookmarksummary, bookmarkprivate, bookmarkrec

custom_columns_settings:
 chapterslashtotal=>#chapters

## chapterslashtotal contains 1/3 or 1/1 or 3/? etc as reported by AO3.
## chapterstotal is just the total chapters part after the /
#include_in_chapterstotal:chapterslashtotal.NOREPL
#add_to_replace_metadata:
# chapterstotal=>^([0-9])+/(.+)$=>\2

## AO3 doesn't have anything it calls 'genre'.  The adapter used to be
## hardcoded to include the site specific metadata freeformtags &
## ao3categories in the standard metadata field genre.  By making it
## configurable, users can change it.
include_in_genre: freeformtags, ao3categories

## default
## include_in_category:fandoms

## AO3 chapters can include several different types of notes.  We've
## traditionally included them all in the chapter text, but this allows
## you to customize which you include.  Copy this parameter to your
## personal.ini and list the ones you don't want.
#exclude_notes:authorheadnotes,chaptersummary,chapterheadnotes,chapterfootnotes,authorfootnotes,inspiredlinks
exclude_notes:inspiredlinks


## May 2026, testing some pairing/ships wrangling
## from https://www.mobileread.com/forums/showpost.php?p=4579994&postcount=11840
# create a couple new entries.
# note the leading ',' it's necessary.
add_to_extra_valid_entries:,romships,platships,firstship,otherships
# copy regular ships into them.  
# All replace_meetadata/etc for ships will already be done.
include_in_romships:ships
include_in_platships:ships
include_in_firstship:ships
include_in_otherships:ships

# keep only those containing / in romships
include_metadata_pre:
 romships=~/

# remove any containing / from platships
exclude_metadata_pre:
 platships=~/


keep_in_order_romships:true
keep_in_order_platships:true
keep_in_order_otherships:true


# put them in your columns.
# Use your custom column identifiers instead of #romships / #platships.
add_to_custom_columns_settings:
 romships=>#pairings
# platships=>#platships


replace_metadata:
## copied from a user on mobileread site,publisher=>archiveofourown.org=>Archive of Our Own
 publisher=>archiveofourown.org=>AO3 by FFF
 characters=>^OC(s|)$=>Original Character(s)
 characters=>^OFC(s|)$=>Original Female Character(s)
 characters=>^OMC(s|)$=>Original Male Character(s)
 characters=>^Original (.*)Character(\(s\)|s|).*$=>Original Character(s)
## Generic Cleanup
# category=> (- All Media Types|- Fandom|\(Movies\)|\(Movie [0-9]+\)|\(Comics\)|\(TV\))$=>
 characters=>\(mentions of\) =>
 characters=> \([Ch]haracter\)=>
 characters=> ?\((cameo|briefly|if you squint|sort of)\)=>
 characters=> - Character=>
 characters=>^Other mentions$=>
## replace orphan_account author links with one that works.
 authorUrl=>(/users/orphan_account)/pseuds/.*$=>\1
## Marvel stuff
 category=>^Marvel$=>Marvel Cinematic Universe
 category=>^Marvel \(Comics\)$=>Marvel Cinematic Universe
 category=>^Marvel \(Movies\)$=>Marvel Cinematic Universe
 category=>Captain America.*=>Marvel Cinematic Universe
 category=>The Avengers.*=>Marvel Cinematic Universe
 category=>Thor.*=>Marvel Cinematic Universe
 category=>Iron Man.*=>Marvel Cinematic Universe
 category=>Black Panther.*=>Marvel Cinematic Universe
 category=>Shang-Chi.*=>Marvel Cinematic Universe
 category=>Black Widow.*=>Marvel Cinematic Universe
 category=>Doctor Strange.*=>Marvel Cinematic Universe
 category=>Deadpool.*=>Marvel Cinematic Universe
 category=>Hulk.*=>Marvel Cinematic Universe
 category=>Spider.*=>Marvel Cinematic Universe
 category=>^Invaders \(Marvel\)$=>Marvel TV (Invaders)
 category=>WandaVision.*=>Marvel TV (WandaVision)
 category=>Hawk[Ee]ye.*=>Marvel TV (Hawkeye)
 category=>Guardians of the Galaxy.*=>Marvel Cinematic Universe
 category=>The Falcon and the Winter Soldier.*=>Marvel TV (TFatWS)
 category=>The Defenders.*=>Marvel TV (The Defenders)
 category=>^Marvel Avengers Movies Universe$=>Marvel Cinematic Universe
 category=>^the avengers 2012$=>Marvel Cinematic Universe

[JimmXinu]

Originally Posted by texasnightowl

But when romships writes to my custom column, the order is: background Natasha Romanov/Clint Barton, background Tony Stark/Pepper Potts, Darcy Lewis/Steve Rogers, James "Bucky" Barnes/Darcy Lewis, James "Bucky" Barnes/Darcy Lewis/Steve Rogers, James "Bucky" Barnes/Steve Rogers, Steve Rogers/Peggy Carter

At that point, it's Calibre alphabet ordering the column, not FFF.

If your custom column type is "Comma separated text, like tags, shown in tag browser", Calibre will sort them.

If your custom column type is "Text, shown in tag browser", Calibre will not sort them.

But note that this type is treated as a single string. If you have "n/m, b/a" you will not be able to use Calibre's tag browser to look for "n/m" and "b/a" separately in that column. You'll only see the one value "n/m, b/a". See attached.

If there's a way to get both display in original order and use as separate tags, I don't know what it is. Anybody else have a way?

[texasnightowl]

ah. ok. yeah, #pairings column is comma separated text, like tags, shown in the tag browser.

maybe I give that up and use the firstship and otherships code example that was within a few posts of the romships/platships code. I mean usually...but not always...authors list the main ship first. Usually secondary pairings are side or background. But this is AO3, so not always!

[wildfire070]

Originally Posted by JimmXinu

PI: INI Snippets - Under 'Show Download Options' on the Add / Update dialog boxes there's now a dropdown for 'INI Snippet'. You can enter a one-time INI snippet, or use previously saved snippets.

FFF will offer to save one-time snippets and there's basic add/edit/remove snippets under the personal.ini tab in FFF config.

This is something I never knew I needed! Super useful. Thank you for adding this feature.

[bigwoof]

just wanted to check if there is a way to set a default value for the "do you want to download an identical book" question that comes up when an author decides to play strange games with their books?

I ask because I was trying to update a few scribblehub books and left fanficfare running to do that. I came back some time later and found that the whole download process had stalled as the popup basically stalled the entire process until I clicked "always". then everything resumed.

is there a way to set a value for this in the ini files? I did a quick search in the wiki and in the code and did not see anyting obvious

It's this code (appears in 4 places in fff_plugin.py) -- although I don't see the always and never options. where are they coming from?

if len(identicalbooks) > 1:
                    identicalbooks_msg = _("More than one identical book by Identifier URL or title/author(s)--can't tell which book to update/overwrite.")
                    identicalwhy_msg = _('<b>%(url)s</b> is already in your library more than once.')%{'url':url}
                    if mi:
                        identicalwhy_msg = _('<b>%(title)s</b> by <b>%(author)s</b> is already in your library more than once with different source URLs.')%{'title':mi.title,'author':', '.join(mi.author)}
                    if question_dialog_all(self.gui,
                                           _('Download as New Book?'),'''
                                             <h3>%s</h3>
                                             <p>%s</p>
                                             <p>%s</p>
                                             <p>%s</p>
                                             <p>%s</p>
                                             <p>%s</p>
                                             <p>%s</p>'''%(_('Download as New Book?'),
                                                           identicalbooks_msg,
                                                           identicalwhy_msg,
                                                           _('Do you want to add a new book for this URL?'),
                                                           _('New URL: <a href="%(newurl)s">%(newurl)s</a>')%{'newurl':book['url']},
                                                           _("Click '<b>Yes</b>' to a new book with new URL."),
                                                           _("Click '<b>No</b>' to skip URL.")),
                                           show_copy_button=False,
                                           question_name='download_new_dup',
                                           question_cache=self.question_cache):
                        book_id = None
                        mi = None
                        book['calibre_id'] = None
                        identicalbooks = []
                        collision = book['collision'] = ADDNEW
                    else:
                        raise exceptions.NotGoingToDownload(identicalbooks_msg,"minusminus.png")

[JimmXinu]

Originally Posted by bigwoof

just wanted to check if there is a way to set a default value for the "do you want to download an identical book" question that comes up when an author decides to play strange games with their books?

Can you explain "play strange games with their books"?


If this came up because you have more than one book with the same identifier:url value, the answer is to select which book with that identifier:url in library and update from there.

If it came up because you had more than one book with the same title/author and no book with identifier:url matching the incoming storyUrl, you could turn off the title/author check.


The 'Yes to All' and 'No to All' come from dialog.py:question_dialog_all(). It wasn't that long ago, we didn't even have that and you had to answer for each story that was affected.

[texasnightowl]

Where I have ended up for now...is I did create a new custom column for main pairing to go along with my previous pairings custom column. I added/tweaked the two sets of code (romships/platships and firstship/otherships) and for now, I have firstship writing to the new "Main Pairing" column and romships (all "/" romantic pairings, including the first one) writing to my "All Pairings" column.

Now...will this work all the time? No. In general the main pairing is usually the first pairing listed. But not always. But...it should work the majority of the time. We'll see.

But...I may still change it up since I do have a minor handful of fics that are platonics only...

Other next step...figure out how I want to handle name orders in ships. I tend to like seeing certain characters names first regardless of who they are paired with instead of AO3's alphabetizing. Example, I'd rather see Jane/Adam and Jane/Steve instead of Adam/Jane and Jane/Steve. So I'll have to see how many replace_metadata ships entries I want to mess around with!

[bigwoof]

Originally Posted by JimmXinu

Can you explain "play strange games with their books"?


If this came up because you have more than one book with the same identifier:url value, the answer is to select which book with that identifier:url in library and update from there.

If it came up because you had more than one book with the same title/author and no book with identifier:url matching the incoming storyUrl, you could turn off the title/author check.


The 'Yes to All' and 'No to All' come from dialog.py:question_dialog_all(). It wasn't that long ago, we didn't even have that and you had to answer for each story that was affected.

"play strange games with their books" comment was because I only notice this with scribblehub books where the book used to be a full book and now it has become stubbed/partial. so I assumed the authors did something..

<edit> not only for scribblehub now that I remember correctly. fanfiction.net used to have this same error for 2 or 3 books during the period when the servers were hyper unreliable. but that has not occured recently </edit>

for me, I always select "yes to all" and deal with whatever happened later..

just checking if there is a way to set that as the default so that I don't need to stay at my laptop watching the "getting book metadata" first pass carefully just in case it hits one of these cases. I would like to just start the updates, leave and forget it, and then take care of the dups later..

Thanks for the great plugin btw!

In my request list of "things to fix corner cases for odd sites" requests, there is the one above and also a request to make this ini option

"check_next_chapter:false"

toggleable via a hotkey as I've lost track of how many times I've had to set this to true to deal with fanfiction.net metadata issues and then set it back to false to avoid the extra page errors on normal books.

[JimmXinu]

Originally Posted by bigwoof

"play strange games with their books" comment was because I only notice this with scribblehub books where the book used to be a full book and now it has become stubbed/partial. so I assumed the authors did something..

If you can't tell specifically what you want to bypass...

FFF has several different checks and dialogs. For one example, the check for changing story URL can already be suppressed if you set the tag "FFF Frozen URL" on that book.

Originally Posted by bigwoof

In my request list of "things to fix corner cases for odd sites" requests, there is the one above and also a request to make this ini option

"check_next_chapter:false"

toggleable via a hotkey as I've lost track of how many times I've had to set this to true to deal with fanfiction.net metadata issues and then set it back to false to avoid the extra page errors on normal books.

That's one of the specific examples of something the new INI Snippet feature is good for.

[texasnightowl]

Originally Posted by texasnightowl

But...I may still change it up since I do have a minor handful of fics that are platonics only...

actually...question...

if romships is empty, ie. there were no "/" pairings, how would I tell it to write "General fic" or "No romantic pairings" or something instead of leaving it blank?

I will go back and review some posts around that discussion to see if it came up. Haven't done that yet.

[bigwoof]

Originally Posted by JimmXinu

If you can't tell specifically what you want to bypass...

FFF has several different checks and dialogs. For one example, the check for changing story URL can already be suppressed if you set the tag "FFF Frozen URL" on that book.

ahh but the issue is that I don't know which book will throw this error as it keeps changing. it's okay. I don't regularly update scribblehub -- I do it every 6 months or so. but when I do, I just have to remember that I can't leave it unattended as it's somewhat likely some book will throw one of the four errors that trigger this popup.

Originally Posted by JimmXinu

That's one of the specific examples of something the new INI Snippet feature is good for.

oh very nice! completely missed this new feature in the test version.. thank you!!

[JimmXinu]

Originally Posted by texasnightowl

actually...question...

if romships is empty, ie. there were no "/" pairings, how would I tell it to write "General fic" or "No romantic pairings" or something instead of leaving it blank?

I will go back and review some posts around that discussion to see if it came up. Haven't done that yet.

Add a line to custom_columns_settings to set that string to your column with flag 'n' for (new only) before the line that sets it from ships?

A replace_metadata pattern like ^[^/]*$ that matches any string that does not contain "/"?

Leave it blank? It's a column for ships and there aren't any.

[texasnightowl]

Originally Posted by JimmXinu

Leave it blank? It's a column for ships and there aren't any.

I don't mind the "Main Ship" (#mainship) column, ala 'firstship' being blank.

But I suppose I would like the "All Pairings" (#pairings) column, aka 'romships' to not be blank.

So if there are no romships at all, then I would like 'platships' to populate the #pairings column.

Add a line to custom_columns_settings to set that string to your column with flag 'n' for (new only) before the line that sets it from ships?

So, right now my custom_columns_settings in personal.ini is:

custom_columns_settings:
 chapterslashtotal=>#chapters
 firstship=>#mainship
 romships=>#pairings

So are you saying if I populate platships to #pairings first, then if romships is blank it would remain populated by whatever platships data was?

custom_columns_settings:
 chapterslashtotal=>#chapters
 platships=>#pairings,n
# or alternately literally the string "No Romantic Ships" like:
 "No Romantic Ships"=>#pairings,n
 firstship=>#mainship
 romships=>#pairings

And I swear, I've been on the github & wiki but I don't know where it talks about flags like 'n'?

[JimmXinu]

Originally Posted by texasnightowl

So are you saying if I populate platships to #pairings first, then if romships is blank it would remain populated by whatever platships data was?

custom_columns_settings:
 chapterslashtotal=>#chapters
 platships=>#pairings,n
# or alternately literally the string "No Romantic Ships" like:
 "No Romantic Ships"=>#pairings,n
 firstship=>#mainship
 romships=>#pairings

And I swear, I've been on the github & wiki but I don't know where it talks about flags like 'n'?

Basically, yes.

From (plugin) defaults.ini:

## (Plugin Only) - You can also populate calibre custom columns with
## the site specific metadata using custom_columns_settings (but only
## if 'Allow custom_columns_settings from personal.ini' is checked in
## the plugin GUI config.)  There are three parts, the entry name,
## then the label of the calibre custom column, then (optionally) a
## 'mode'.  'r' to Replace any existing values, 'a' to Add to existing
## value (use with tag-like columns), and 'n' for setting on New books
## only.  (Default is 'r'.)

## Literal strings can be set into custom columns using double quotes.
## Each metadata=>column mapping must be on a separate line and each
## needs to have one space at the start of each line.  There is also a
## special case for Integer and Float type custom columns: The static
## value "None" will clear the column.

## 'r_anthaver' and 'n_anthaver' can be used to indicate the same as
## 'r' and 'n' for normal downloads, but to average the metadata for
## the differents story in an anthology before setting in integer and
## float type custom columns.  This can be useful for a averrating
## column, for example.
## 'r_anthmax' and 'n_anthmax' indicate 'r' and 'n' for normal
## downloads, but to use the highest value for the metadata from the
## differents story in an anthology in integer and float type custom
## columns.
## Default is to sum the values of all stories, and numChapters and
## numWords are always summed.

#custom_columns_settings:
# cliches=>#acolumn
# themes=>#bcolumn,a
# timeline=>#ccolumn,n
# "FanFiction"=>#collection
# averrating=>#averrating,r_anthaver