[Conversion Output] KFX Output

[jhowell]

KFX Conversion Output Plugin

The purpose of the KFX Output plugin is to convert e-books into KFX files that can be sideloaded to newer Kindle apps and devices. This allows books obtained from sources other than Amazon to be read with Enhanced Typesetting, multi-thumbnail Page Flip, non-justified alignment, continuous scrolling, page curl, Guided View for comics, and sticky notes (on Kindle Scribe).

Most owners of newer Kindle devices no longer need to use this plugin to obtain KFX format. As of October 2023 Amazon converts most personal documents sent using send-to-kindle to KFX.

(Note: If you want to sideload your books via USB and only want somewhat better typography when reading then using the "Add soft hyphens" option of the "Polish books" command in calibre version 4.6 or higher should be considered as an alternative to using KFX. It is less difficult to use and the book format it works with is compatible with more devices and software. The same effect can be achieved in older versions of calibre using the Hyphenate This! plugin.)


Background:

Spoiler:

Amazon has added support for several advanced features in newer kindle reading apps and firmware. Enhanced Typesetting allows improved rendering of e-book content using hyphenation, kerning and ligatures. Enhanced Typesetting is required for the correct rendering of books in Arabic, Hindi, Gujarati, Marathi, Malayalam, Tamil, and Traditional Chinese. Page Flip, improved manga experience (fast continuous page turns, pan/zoom, crop margins, page spreads), and Guided View for comics provide improved navigation within a book's contents.

Only e-books in the proprietary KFX format support these features and currently only Amazon sourced e-books and personal documents downloaded directly from Amazon to apps and devices are available in this format.

Amazon Kindle Previewer 3 is software that takes books in EPUB format and renders them with Enhanced Typesetting. It does this by converting the EPUB file to KPF, which has the same content as KFX but in a different container. This plugin is able to invoke the Previewer for conversion and reformat its output from KPF to produce KFX files suitable for sideloading.

The plugin performs the following steps during conversion:

• Convert from the original e-book format to EPUB.
• Correct some common EPUB content issues that cause problems for the Previewer.
• Use the Amazon Kindle Previewer 3 command-line interface to convert from EPUB to KPF.
• Repackage the KPF data into a KFX container.

KFX books delivered by Amazon are a bundle of files composed of an encrypted main container, a metadata container, auxiliary containers (zero or more) and a DRM voucher. The plugin instead generates an equivalent unencrypted monolithic KFX file, which is supported by Amazon reading apps and devices when sideloaded.

A more in-depth discussion of the KFX format can be found in the KFX Format thread, the MobileRead Wiki (KFX), and the KDP help pages.

KPF (Kindle Package Format) is a ZIP archive. The main components are a descriptive KCB file in JSON format and a KDF file containing the main book content in an SQLITE database. KPF can be produced by Kindle Previewer 3 and Kindle Create.

Installation:

Spoiler:

In order for the plugin to function Amazon's Kindle Previewer 3 must be installed. It is available from https://www.amazon.com/Kindle-Previe...de=21381691011 for Windows and MacOS. If given a choice of installation location choose the default. Install it while signed in to the same user account that you use to run calibre. Version 3.89.0 (Nov 19, 2024) is recommended for best results, except under Linux. (Versions below 3.38.0 are not compatible with this plugin. Versions newer than 3.89.0 have not been tested and might not be compatible.)

The Linux platform is not supported by the Kindle Previewer, however the Windows version can be installed under Wine. The Previewer can be used to perform conversions in spite of it producing numerous "DEBUG" and "fixme" messages. The Previewer's GUI does not function under Wine but that does not matter since the CLI is used by this plugin for conversion. Because calibre needs to be able to invoke Wine it is unlikely to work if calibre is installed within a container such as Flatpak, Snap, or AppImage. The most recently reported working configuration is Kindle Previewer 3.76.0 running on Archlinux with 6.9.7-zen1-1-zen kernel and wine-stable 9.0-2. Kindle Previewer 3.74.0 running on Fedora Linux 39 and Kindle Previewer 3.60 and wine-7.0-rc4 running on Gentoo 5.15.12 have also been reported to work. Other software combinations are untested and may not function properly. (Older versions of Kindle Previewer, such as 3.73.0, can be downloaded using the Internet Archive Wayback Machine.)

Install the KFX Output plugin and restart calibre as described in the Introduction to plugins thread.

You can tell if the plugin/Previewer combination is functioning properly by attempting to convert a book that is known to work. One example is this edition of Frankenstein by Mary Shelley.

Configuration:

Spoiler:

Configuration of the conversion options for plugin is done in the KFX Output tab in the conversion options dialog. Defaults for future conversions can be set under Preferences, Output Options, KFX Output. These options are described in the Usage section.

Other configuration options for this plugin can be found under Preferences, Plugins, Conversion output. Select KFX Output from the list and click Customize plugin.

In addition "tweaks" can be configured to set less frequently used options. Set them by going to Preferences->Advanced->Tweaks->Plugin tweaks. Tweaks are entered as Python variable assignments. Tweak settings will apply to all conversions. See the calibre manual for more information.

In most cases the plugin will be able to locate Kindle Previewer 3 automatically in order to use it for conversion. However if the default location was not used when installing the Kindle Previewer and the plugin reports that it is unable to locate it, the "kfx_output_previewer_path" plugin tweak can be used to indicate the actual installation folder used. (Windows paths require double backslashes.) For example:

kfx_output_previewer_path = 'C:\\Program Files (x86)\\Kindle Previewer 3'

A unique ASIN can be forced to be created during conversion even if an ASIN identifier or internal book metadata is present by setting the "kfx_output_ignore_asin_metadata" plugin tweak. Use:

kfx_output_ignore_asin_metadata = True

Setting the "kfx_output_wineprefix" plugin tweak will override the default WINEPREFIX when launching the Kindle Previewer under Linux.

Usage:

Spoiler:

The plugin is activated by selecting KFX as the output format when converting books in calibre. An alternative command line interface is available for advanced users. (See below.)

By default the converted book will be marked as an Amazon supplied book, but because the book was not actually purchased from Amazon unexpected behavior may sometimes result. The book can be marked as a personal document instead using the "Create personal document instead of book" conversion option. This may be of use if odd behavior is experienced.

If the calibre book being converted has a 10-character mobi-asin, amazon, or asin identifier that starts with B then this will be used as the ASIN of the KFX file created. Otherwise a unique ASIN will be generated. A unique ASIN can be forced to be created even if an ASIN identifier or internal book metadata is present by setting the "kfx_output_ignore_asin_metadata" plugin tweak. A unique ASIN is also always generated for personal documents regardless of the identifiers present.

The plugin reports error messages produced by the Kindle Previewer in the conversion job log. Some additional information can be obtained by selecting "Show full Kindle Previewer conversion logs" in the conversion options. This might occasionally be useful in diagnosing a failure to convert a book.

Page numbers contained in an NCX pageList, NAV page-list, or page-map.xml within the source EPUB will be converted. (The plugin CLI must be used to preserve pages from a NAV page-list since calibre discards that during conversion.) Amazon APNX is not supported as a page number source.

An option is available to create approximate page numbers in cases where page numbers are not present in the source format. The lookup name of a custom column holding the desired number of pages for each book may be specified, otherwise the page count will be determined automatically from the amount of book content.

The time needed for the Kindle Previewer to perform conversion will vary based on the size and complexity of the book. In some rare cases conversion appears to become hung up and never complete. Selecting "Enable conversion timeout" will cause any conversions that run for more then 15 minutes to terminate automatically. In this case the conversion log may help to diagnose the cause of the problem.

A conversion option will cause the Kindle Previewer to produce a quality report listing potential problems such as missing back links on footnotes and broken links to external websites. If this is enabled any quality messages will be included in the conversion log.

It is recommended that the "Tablet" output profile be selected in the Page setup section of conversion options to avoid having images downscaled by the calibre conversion pipeline.

The resulting KFX file can be viewed using the Kindle Previewer. However, the Previewer only supports the file extension ".azw8" for opening KFX files instead of ".kfx". Workarounds are available for Windows or MacOS to allow files created by this plugin with a .kfx extension to be viewed more easily. (For Windows use "Open KFX with Kindle Previewer 3" (see this post) and for MacOS use "Preview KFX" (see this post.)

KFX files created by the plugin must be sideloaded (transferred into the target device's storage). Calibre version 2.80 or later supports sideloading and viewing metadata for books in KFX format on connected Kindle devices. Calibre version 3.29 or later will also create cover thumbnails when KFX books are sent to a Kindle device.

To sideload using calibre, you need to configure KFX as a format that can be sent to that device. With your device connected click on the "Device" drop-down menu and choose "Configure this device". Under "Select available formats and their order for this device", add a checkmark to "kfx" and use the arrow buttons move it up/down and set its priority relative to the other formats.

Sideloading may also be done manually. The procedure for doing this varies by device type:

• Kindle e-ink devices: Instructions
• Amazon Fire tablets: Instructions (KFX files must be marked as ebook instead of personal document if placed in the Books folder of Internal Storage. The "Docs" app must be used instead of "Books" to view personal documents.)
• Kindle for iOS app: See "Use iTunes to share files between your computer and your iOS or iPadOS device" This can be done without a cable if "Sync with this iPhone over Wi-Fi" is enabled in iTunes. (You will not be able to use iCloud or the Files app for this transfer.)
• Kindle for Android app: Copy the file to the kindle or Books folder within main internal storage of the device (/sdcard). (The Local File Access setting controls which folders can be used.) If that does not work try placing files in Android/data/com.amazon.kindle/files.

The WordDumb plugin for calibre can be used to create and sideload the data files needed to enable the Word Wise and X-ray features for sideloaded KFX books. The X-Ray Builder Windows Application can also produce X-ray files. Books in KFX format cannot make use of X-Ray if they are marked as personal documents when created.

Showing Cover Thumbnail Images on E-Ink Kindle Devices:

Spoiler:

The Kindle apps on Android, Fire, and iOS devices will show cover thumbnails for sideloaded KFX books without any additional effort. In some cases the book must be opened at least once for the cover thumbnail to appear.

E-ink Kindle devices instead show a generic cover thumbnail in the Home and Library screens by default. If cover thumbnails are desired on a Kindle device additional steps are required using one of the following approaches.

Method A - Personal document cover thumbnails

Kindle devices running firmware version 5.15.1 or later will show cover thumbnails for sideloaded KFX files that are marked as personal documents without any additional effort. The conversion option to create a "personal document" (not a "book") must be used in order for cover thumbnails to appear using this method.

Kindle devices with firmware 5.14.3.2 or older will show only generic cover thumbnails for personal documents and do not support this method.

Method B - calibre cover thumbnails

When the calibre "Send to device" function is used to send a KFX book to an e-ink Kindle a cover thumbnail image will also be sent. Calibre version 7.14 or later is required for Scribe devices, version 4.17 or later for other Kindles. The default conversion option to create a "book" (not a "personal document") must be used in order for calibre cover thumbnails to be used.

In some cases the calibre cover thumbnails may be replaced by generic covers the first time that the Kindle connects to Amazon after a book is loaded. After sending a KFX book to a Kindle and ejecting the device, wait a moment to determine whether or not the cover thumbnail for the book has been replaced by a generic cover. If so then reconnect the Kindle to calibre in order to fix the cover thumbnail. See the topic "Covers for books I send to my e-ink Kindle show up momentarily and then are replaced by a generic cover?" in the calibre FAQ for more information. Remaining in Airplane Mode will also prevent thumbnail removal.

Method C - Amazon cover thumbnails

If Amazon sells a book that is equivalent to the one being sideloaded then it is possible to have Amazon provide a cover thumbnail for that book.

Amazon identifies books that it sells using a ten character Amazon Standard Identification Number (ASIN). If an ASIN is set in a KFX book then the e-ink Kindle device will automatically download the corresponding cover thumbnail image from Amazon's servers after the book is sideloaded. Your Kindle will need to have a Wi-Fi or 3G connection for this to work properly.

Setting an ASIN can be used to force the Kindle to download cover thumbnails from Amazon in cases when the calibre "Send to device" function is not being used to transfer books.

Warning: If calibre version 4.17 or later is used to sideload the book then calibre will replace the Amazon cover thumbnail with its own cover thumbnail the next time that the Kindle is connected.

In order to set an ASIN:

• Search amazon.com with a web browser for an Amazon Kindle book equivalent to the book you are converting and bring up its page. The Amazon web page must be for a Kindle-edition, a print edition will not work. If there is no equivalent book this procedure will not work. (If your Kindle is registered with an account at a country-specific Amazon site, such as amazon.co.uk, then you must use ASINs from the same site. Each Amazon web site uses its own ASINs.)
  
• The web browser address bar will have something like "https://www.amazon.com/gp/product/B005MZN2B2/...". The ASIN for the book is the 10-character string that begins with a "B".
  
• In calibre select your book, choose "Edit Metadata", and in the "Ids:" field add "amazon:B005MZN2B2" (without the quotes and using the ASIN you discovered). If there is something already in the "Ids:" field then separate the new information with a comma.
  
  Calibre supports ASINs for country-specific Amazon stores by appending the country code to the identifier name when creating the "amazon" identifier. For example:
  amazon:B0064CPN7I --> https://www.amazon.com/dp/B0064CPN7I
  amazon_uk:B00BAJ6GL2 --> https://www.amazon.co.uk/dp/B00BAJ6GL2
  amazon_de:B016PFA0YO --> https://www.amazon.de/dp/B016PFA0YO
• You can verify that the ASIN is set correctly by selecting the book in calibre and looking at the book details panel (usually on the far right). There should be an "Amazon.com" entry in the "Ids:" section. Click on "Amazon.com" there and your browser will open to the associated web page. Verify that the browser shows the expected book and that it is a Kindle edition, not a print edition. Use "Edit Metadata" to fix the ASIN if not.
  
• Convert the book to KFX. The default conversion option to create a "book" (not a "personal document") must be used in order for Amazon cover thumbnails to appear.
  
• Manually sideload it to your kindle device. After you eject your Kindle from your computer the cover thumbnail will be automatically downloaded from Amazon's servers.

Method D - Manual thumbnail loading

The ExtractCoverThumbs program can be used as an alternative to calibre for producing thumbnails. See the MobileRead thread.

Cover thumbnails will be replaced by generic covers the first time that the Kindle connects to Amazon after a KFX book is loaded. To avoid this problem first sideload books to the Kindle, disconnect, wait a few minutes, and then reconnect the Kindle before using ExtractCoverThumbs.

The default conversion option to create a "book" (not a "personal document") must be used in order for manual cover thumbnails to appear.

Command Line Interface (CLI):

Spoiler:

The KFX Output plugin has a command line interface for advanced users. Conversion using the CLI bypasses the calibre conversion pipeline, resulting in a KFX file that more closely reflects the formatting of the original book. Use of the CLI is necessary to convert books that are not supported by calibre conversion, such as those using fixed layout(eg. comics and print replica) or Kindle-specific media queries.

Conversion via CLI does not work for books that have DRM. If the book you are trying to convert has DRM you will need to import it into calibre first so that DRM can be removed and then export it from calibre for use by the plugin CLI.

usage: calibre-debug -r "KFX Output" -- [-h] [-a ASIN] [-c] [-d] [-p PAGES]
                                        [-q] [-t] [-l]
                                        infile [outfile]

Convert e-book to KFX format

positional arguments:
  infile                Pathname of the .epub, .opf, .mobi, .doc, .docx, .kpf,
                        or .kfx-zip file to be converted
  outfile               Optional pathname of the resulting .kfx file

optional arguments:
  -h, --help            show this help message and exit
  -a ASIN, --asin ASIN  Optional ASIN to assign to the book
  -c, --clean           Save the input file cleaned for conversion to KFX
  -d, --doc             Create personal document (PDOC) instead of book (EBOK)
  -p PAGES, --pages PAGES
                        Create n approximate page numbers if missing from
                        input file (0 for auto)
  -q, --quality         Include Kindle Previewer quality report in log
  -t, --timeout         Stop conversions lasting over 15 minutes
  -l, --logs            Show log files produced during conversion

Documentation for calibre-debug can be found here. See the note here regarding MacOS. For that OS the full path for the command may be needed: /Applications/calibre.app/Contents/MacOS/calibre-debug


Conversion from EPUB or Word Document

If an EPUB file is used as the infile it will be passed to the Amazon Kindle Previewer for conversion to KPF and then the result will be repackaged as KFX. This bypasses any manipulation of the EPUB by the calibre conversion pipeline. English language MS Word DOC and DOCX files and MOBI files (created using kindlegen version 2.9 without the -dont_append_source option) can also be converted the same way.

Examples:

calibre-debug -r "KFX Output" -- input.epub output.kfx  (Converts input.epub to output.kfx)
calibre-debug -r "KFX Output" -- "my book.epub"         (Produces my book.kfx)

An unzipped EPUB can also be converted by passing the OPF file as input. In that case the OPF is passed directly to the Kindle Previewer for conversion without any fix ups being done.


Conversion from KPF

If a KPF file is used as the infile it is repackaged as KFX. This can be used to convert books and comics produced using Amazon Kindle Create or to convert KPF files exported from the Kindle Previewer.

Converting Comics and Manga:

Spoiler:

Comics in KFX format with Guided View (panel-by-panel mode) can be produced using Amazon's Kindle Create. Choose Create New and select Comics as the format. After creating the comic use the Publish option to produce a KPF file and then convert that to KFX using the plugin's command line interface. (Do not use the calibre GUI for comic conversion. It is not compatible with fixed-layout comics.)

For example, if the comic is named mycomicbook.kpf it can be converted to KFX using the following command:

calibre-debug -r "KFX Output" -- mycomicbook.kpf

KFX comics sideloaded to an e-ink Kindle with firmware older than 5.16.6 will display in manga mode, even if they are not manga, and Guided View does not function. Conversely, fast-scrolling manga mode does not function in the Android or iOS Kindle app, but comics with panels will display using Guided View.

Comics produced using Kindle Comic Converter or Amazon's Kindle Comic Creator cannot be converted using this plugin. The plugin is also not able to convert fixed layout comics and manga from source formats such as CBR, CBZ, EPUB, or MOBI.

Converting PDFs for Markup on Kindle Scribe:

Spoiler:

Scribe users can only write directly on pages if the book is in the Print Replica variant of KFX format. Colorsoft Kindles do not display PDF files in color but will show color if the file is converted to Print Replica KFX. That format is normally produced when sending a PDF though Amazon's send-to-kindle service for delivery to those device types.

To generate that format for sideloading you need to import a document in PDF format into Amazon's Kindle Create software. Choose Create New and select Print Replica as the format. After importing the PDF file chose Edit, Preserve Links in order to keep as much functionality of the original PDF as possible. Use the Publish option to produce a KPF file and then convert that to KFX using the plugin's command line interface.

For example, if the KPF file is named my book.kpf it can be converted to KFX using the following command:

calibre-debug -r "KFX Output" -- "my book.kpf"

Print Replica KFX format is only supported on Scribe and Colorsoft devices, not on regular Kindles. Despite being unsupported it appears to display properly on newer Kindle models running the latest firmware but not on older ones.

Exporting annotations made to side loaded Print Replica KFX will probably not be possible via email. Hand drawn annotations are stored on the Scribe as hidden notebooks. Those can be extracted from the Scribe and then converted to EPUB format containing SVG images by using the KFX Input plugin, however the EPUB will only contain the annotations and not the underlying PDF page backgrounds.

Dealing with Conversion Errors

Spoiler:

The conversion to KFX is mostly done by Amazon's Kindle Previewer. That software will only produce a result if the original format can be converted cleanly to KFX. Books containing incorrect formatting or unsupported features will intentionally fail to convert. That is normal, expected behavior. (This strategy differs from most other calibre conversions which are expected to succeed as best they can even if all of the formatting in the original book cannot be carried through to the target format.)

The plugin corrects some minor issues in the source EPUB that prevent conversion by Previewer: non-UTF8 character encoding, obfuscated fonts, unsupported languages, missing/duplicated title, and a few others. But most potential problems cannot be fixed automatically. Some examples of things that may cause a conversion failure are:

• Incorrect HTML or CSS files. (The calibre editor can often be used to detect and correct these problems. EPUBs can be validated using EpubCheck.)
• Large tables.
• Incorrect or unusual style properties or values.
• SVG images.
• Images with internal errors.
• Fixed-layout books, including comics and manga.
• OS language selection. For example conversion fails under Windows when set to Turkish.
• Miscellaneous things that trigger bugs in the Previewer software.

First make sure that you have the most recent version of the Kindle Previewer installed. Amazon has updated it over time and has fixed bugs that resulted in conversion failures.

If a conversion error occurs the plugin will report the error message produced by the Kindle Previewer in a pop-up error dialog box in calibre. The error messages produced by the Previewer are sometimes cryptic and in many cases no specific reason for the conversion failure is provided.

The Previewer sometimes provides guidance to help with fixing problems that can prevent conversion to KFX or produce incorrect conversion results. This information will be shown in conversion job log.

You can view the conversion job log after an error occurs to see additional information on why the conversion failed. To access the log, either click on the "Jobs: 0" label in the lower right corner of the calibre window or use the Alt-Shift-J keyboard shortcut to activate the Jobs dialog. Select the failed conversion job from the list (the most recent will be first) and click the "Show job details" button. To copy the log to the clipboard under Windows, click within the log text then press Ctrl-A (select all) and Ctrl-C (copy). You can then paste it wherever you like.

When Previewer errors occur it can be a tedious trial-and-error process to get a book to convert to KFX. One procedure is to use the calibre editor to selectively remove pieces of the source book until conversion is successful. This will narrow down what part of the book is causing the Previewer failure. This requires knowledge of EPUB and HTML details, can take a lot of time and effort, and may not be ultimately successful.

An easier method that will often allow a book to be converted to KFX format is to do the conversion in two steps. First convert the book to MOBI format with the "MOBI file type" option in the MOBI Output tab set to "old". Then convert from MOBI to KFX. This works because some types of HTML formatting are stripped out during conversion to MOBI and this may include whatever is blocking KFX conversion. However the resulting KFX file will be missing some of the formatting of the original book.

If a conversion fails and you feel that the failure may have been caused by a problem with the plugin itself, rather than the Kindle Previewer, please report it in this thread along with the associated error message and log. When posting log contents please enclose them in [spoiler]...[/spoiler] tags. The ScrambleEbook plugin can be used to remove copyrighted text, allowing the source file that fails to convert to be posted on MobileRead.

Typographic Widows and Orphans

Spoiler:

Typographic widows and orphans are a single line of a longer paragraph appearing by itself at the top or bottom of the screen. In late 2019 the KFX renderer in reading apps and devices was changed to no longer produce these by default. As a result there will often be screens of text that will have fewer lines than expected and this can be annoying some people.

Kindle firmware prior to version 5.12.2 always allows widows and orphans to occur. Kindle firmware 5.12.2 always prevents widows and orphans. Starting with firmware version 5.12.3 this under the control of the "widows" and "orphans" properties in the source file converted to KFX.

One way to restore the pre-5.12.2 handling of widows and orphans for most books is to add the following to the "Extra CSS" in the "Styling" tab of the "Look & feel" section in the conversion dialog:

body {orphans: 1 !important; widows: 1 !important}

Updating book metadata

Spoiler:

The metadata and cover images in KFX files produced by this plugin can be updated to match the current data in the calibre library by a Metadata Writer Plugin that is built into this plugin. This is activated in calibre using the "Embed metadata" function, "Save to disk" function (with the "Update metadata in saved copies" option enabled), "Send to device", or by the "calibredb embed_metadata" command line interface. Metadata plugboards can be used. (The "Polish books" function will not update KFX metadata since it supports only the AZW3 and EPUB formats.)

The supported fields are: title, author, language, publisher, publication date, description, cover, CDEType, and ASIN.

By default the language, CDEType, and ASIN fields will not be updated since doing so can cause problems once the KFX file is sideloaded to a Kindle. The plugin configuration option "Enable updating of all KFX metadata" can be set to enable the updating of those fields.

Each author name will be individually converted to sorted form. (The author_sort field is not used.)

Although KFX format supports multiple authors, only the first author name will be shown for books in KFX format on Kindle devices. If the cover size changes and the cover page uses a layout that cannot be modified then the new cover image will be rescaled to match the original cover.

A new cover page cannot be added to a book that does not already have one and an existing cover cannot be removed without replacement. Existing covers can be replaced except in rare cases when the cover page uses an unsupported format.

If "Create personal document instead of book" is selected in the default settings for conversion to KFX format the resulting content type will be personal document (PDOC). Otherwise ff the "kfx_output_ignore_asin_metadata" plugin tweak is not set then the ASIN will be set from a "mobi-asin", "amazon", or "asin" identifier that has 10 alphanumeric characters starting with "B" and the resulting content type will be book (EBOK).

Approximate page numbers can also be produced or updated based on the default settings for conversion to KFX format.

Updating of KFX metadata can be disabled by disabling the "Set KFX metadata" plugin in the "Metadata writer plugins" category of plugin preferences.

Warnings and Limitations:

Spoiler:

The KFX format is undocumented. There is a chance that this plugin could potentially produce a KFX file that could cause a slowdown or crash of your Kindle device or app when sideloaded. Use at your own risk!

Many books cannot be successfully converted to KFX using the Kindle Previewer, including those using fixed-layout. The Amazon Kindle Publishing Guidelines contains some information on what content is supported in KFX format. (See references to Enhanced Typesetting.)

Dictionaries cannot be created in KFX format using this plugin.

KFX files cannot be sent using Send to Kindle by E-mail or using Send to Kindle for PC/Mac. They must be sideloaded. Sideloaded books are not backed up to your Amazon account and will not sync reading position, notes and highlights with your account or between your Kindle apps and devices.

KFX files produced by this plugin are uncompressed and so will usually be larger than other e-book formats. (KFX files for books purchased from Amazon include data compression in conjunction with their DRM.) Files produced by this plugin may sometimes be too large for Kindles to handle. This can cause lock up and return to home screen during reading.

KFX files produced using this plugin do not encode word boundaries for languages that do not use spaces between words, such as Chinese. This will cause problems with highlighting and dictionary lookup for those languages.

The FONT_RAMP feature for setting custom font sizes on e-ink Kindle devices does not work with KFX format. However, user loaded custom fonts do work for KFX on devices that support that feature.

Books converted by the plugin may not function properly in all devices and firmware versions. KFX has been extended over time. Amazon checks capabilities and only delivers KFX format if the device supports all of the features used within the book. Sideloading bypasses this check and may lead to incorrect book rendering. Because of this, the use of the most recent firmware and app versions is strongly recommended for reading books in KFX format.

Firmware version 5.6.5 or later is required for Kindle devices. Some e-book features, such as HTML tables and Page Flip, require firmware 5.7.2 or later. Firmware 5.8.5 or later is required for manga. Arabic language books require firmware 5.9.6.1 or later. Traditional Chinese language books require firmware 5.12.2 or later.

This plugin requires calibre version 5.0 or later. Older versions that run under calibre 2.x through 4.x are available in this post.

The Metadata Writer can replace an existing cover in a KFX book, but cannot create a new cover in a book that does not already have one.

Version History:

Spoiler:

Version 2.13.0 - 29 Nov 2024

Detect Kindle Previewer versions up to 3.89.0.

By default the KFX metadata writer will no longer update the ASIN, CDEType, and Language fields of KFX books when they are exported from calibre since doing so can cause problems once the KFX file is sideloaded to a Kindle. Add plugin configuration option "Enable updating of all KFX metadata" that when checked will reenable the updating of those fields.

Use language code zh-hant in place of zh-TW when converting to KFX in order to enable Traditional Chinese language support on Kindles.

Version 2.12.0 - 08 Nov 2024

Detect Kindle Previewer versions up to 3.88.0.

Change the KFX metadata writer so that if "Create personal document instead of book" is selected in the default settings for conversion to KFX format the resulting content type will be personal document (PDOC).

Version 2.11.0 - 06 Oct 2024

Add "kfx_output_wineprefix" plugin tweak that will override the default WINEPREFIX when launching the Kindle Previewer under Linux.

Version 2.10.0 - 20 Sep 2024

Detect Kindle Previewer versions up to 3.87.0.

Report the minimum Kindle firmware version (min_kindle_version) required to render the file produced based on the KFX features it contains in the Metadata section of the conversion log.

Improve reporting in the conversion log when a conversion is terminated because it took to long to complete.

Look for both "wine64" and "wine" executables when running under Linux.

Version 2.9.0 - 05 Jul 2024

Detect Kindle Previewer versions up to 3.83.0.

Handle an occasional case where Kindle Previewer successfully converts but fails to include the KPF file name in summary log file produced. (Fixes 'KPF file is missing: ""')

Version 2.8.0 - 22 May 2024

Detect Kindle Previewer versions up to 3.81.0.

Remove unnecessary work around for conversion of Indian language books. For proper conversion the OPF and XHTML files must specify the language properly and the majority of text must be comprised of Unicode characters belonging to that language.

Version 2.7.0 - 02 Mar 2024

Detect Kindle Previewer versions up to 3.78.0.

Allow conversion of books using languages that are unsupported by Amazon on Kindles. There is no guarantee that books in unsupported languages will render properly on Kindle devices and apps. For a partial list of supported languages see: Book Supported Languages.

Version 2.6.1 - 29 Jan 2024

Fix plugin not working using calibre versions older than 6.0.

Version 2.6.0 - 25 Jan 2024

Detect Kindle Previewer versions up to 3.75.0.

When launching the Kindle Previewer include additional environment variables that be be needed for some non-standard Wine installations on Linux.

Version 2.5.0 - 30 Dec 2023

Reposition tfoot elements to the end of tables to prevent Kindle Previewer conversion failure. (Fixes "Conversion error: Invalid Table Structure found in html")

Improve the quality of cover images that need to be re-encoded into JFIF format for Kindle lock screen cover support.

Ignore the case of file extensions.

Version 2.4.0 - 28 Nov 2023

Detect Kindle Previewer versions up to 3.74.0.

Fix metadata jacket not being created when the conversion option "Insert metadata page at start of book" in the Structure detection tab is set.

Eliminate use of the deprecated Python imp module.

Version 2.3.1 - 12 Sep 2023

Fix bugs introduced in previous plugin release for some fixed-layout books. (Fixes "AttributeError: 'NoneType' object has no attribute 'PdfReader'" and "ERROR: Exception checking book consistency: KeyError('$564')")

Version 2.3.0 - 01 Sep 2023

Allow conversion of Hebrew (he) and Thai (th) language books. (There is no guarantee that books in languages that are unsupported by Amazon will render properly on Kindle devices and apps.)

Fix issue date metadata being ignored during conversion.

Version 2.2.0 - 07 Aug 2023

Allow conversion of Vietnamese language books.

Fix error when processing the cover of fixed layout books converted from KPF format. (Fixes "YJFragmentList item is missing: '$389'")

Version 2.1.0 - 25 Jul 2023

Add a cover entry to the landmarks metadata for fixed layout books produced from KPF format. This fixes a non-working "Cover" entry appearing in the table of contents on Kindle devices.

Version 2.0.0 - 01 Jun 2023

Detect Kindle Previewer versions up to 3.72.0.

Fix an incorrect number of '/' characters in a URL contained in an href of an EPUB in order to prevent an internal error in the Kindle Previewer from occurring during conversion.

Create a cover image for print replica books converted from a KPF produced by Kindle Create. Fixes "WARNING: The cover could not be set because the page uses an unsupported format: cover page uses a PDF image".

Remove support for calibre versions prior to 5.0. (Older versions of this plugin that run under calibre 2.x through 4.x are available in this post.)

Version 1.67.0 - 16 Apr 2023

Detect Kindle Previewer versions up to 3.71.1.

Support use of the 64-bit version of Wine under Linux. (Thanks to Honza Pokorny.)

Version 1.66.0 - 06 Feb 2023

Remove display:none style which is sometimes applied to <title> elements by calibre and causes conversion by the Kindle Previewer to fail.

Fix missing "src" attribute in "img" elements which causes conversion by the Kindle Previewer to fail.

Detect Kindle Previewer versions up to 3.71.0.

Version 1.65.0 - 16 Nov 2022

Update the conversion option documentation to reflect that Kindle firmware 5.15.1 will display cover thumbnail images for personal documents in KFX format.

Detect Kindle Previewer versions up to 3.69.0.

Version 1.64.0 - 30 Jul 2022

Allow conversion of Bengali language books.

Fix bug introduced in version 1.63.0 of this plugin that prevented the conversion of vertical Chinese language books.

Version 1.63.0 - 17 Jun 2022

Detect Kindle Previewer versions up to 3.66.0.

Retain the original language when converting books in languages that are unsupported by the Kindle Previewer. This will hopefully allow dictionary lookup if a dictionary for the proper language is present on the device.

Allow conversion of Romanian and Czech language books.

Version 1.62.0 - 30 May 2022

Detect Kindle Previewer versions up to 3.65.0.

Allow conversion of Turkish language books by changing their metadata to indicate that the primary language is English. (Turkish is not a supported language for the Kindle Previewer.)

Version 1.61.0 - 17 Apr 2022

Detect Kindle Previewer versions up to 3.63.1.

Version 1.60.0 - 09 Mar 2022

Detect Kindle Previewer versions up to 3.62.0.

Fix updating of the cover image for fixed layout comic or manga books. (Previous plugin versions produced a distorted or cropped cover page if the dimensions of the cover image were changed.)

Version 1.59.0 - 15 Feb 2022

Detect Kindle Previewer versions up to 3.61.0.

Fix the empty mime type for an image sometimes produced by the Kindle Previewer when a book contains a duplicate cover. (Fixes "ERROR: External resource e6 has unknown mime type".)

Version 1.58.0 - 27 Nov 2021

Detect Kindle Previewer versions up to 3.60.0. Version 3.60.0 adds support for additional list-style-type values.

Fix conversion to retain the creation date and multiple author names if present in the source EPUB. (Only the first author name will be shown on Kindle devices for books in KFX format.)

Fix embedding of metadata to maintain the order of author names when a book has multiple authors.

Version 1.57.0 - 08 Nov 2021

Detect Kindle Previewer versions up to 3.59.1. Version 3.59 and version 3.59.1 contain no significant changes to KFX conversion.

Add a fixup to force OPF ids to be unique to prevent various failures when converting books. The Kindle Previewer is improperly insensitive to case in OPF ids resulting in ids like "text" and "TEXT" being treated as identical.

Add fixup to remove an extra HTML file that is sometimes incorrectly left over when calibre replaces the cover of a book. This prevents the final page of the converted book from containing a missing image icon (camera with exclamation point).

Version 1.56.0 - 20 Sep 2021

Detect Kindle Previewer versions up to 3.58.0. Version 3.58.0 adds support for additional list-style-type values (reflow-style-14) and fixes a problem that prevented conversion of some Japanese language books.

Support new KFX feature. (Fixes "Unexpected Ion symbols used: $790".)

Version 1.55.0 - 25 Aug 2021

Detect Kindle Previewer versions up to 3.57. Version 3.57 adds support for text-shadow in books with vertical text and improves conversion of SVG images.

Remove links to non-existent targets in the NAV TOC that would otherwise cause conversion failures.

Allow conversion of Polish language books by changing their metadata to indicate that the primary language is English. (Polish is not a supported language for the Kindle Previewer.)

Version 1.54.0 - 06 Aug 2021

Detect Kindle Previewer versions up to 3.56.1. Version 3.55 contains no significant changes. Version 3.56 adds support for float and clear in vertical Japanese books. Conversion is unchanged in version 3.56.1.

Version 1.53.0 - 14 Jun 2021

Detect Kindle Previewer versions up to 3.54. Version 3.53 restores YJImageLayoutEnhancer and restores support for page-break-after:avoid and page-break-before:avoid. Version 3.54 includes support for vertical tables in horizontal books and vice versa.

Issue a warning recommending that the Kindle Previewer be updated if the most recent version (as of the date of the plugin release) is not installed.

Change cover images to use JPEG/JFIF format as needed in order to support the Kindle cover lock screen feature. (This is rarely needed since most cover images are already in this format.)

Version 1.52.0 - 17 May 2021

Detect Kindle Previewer versions up to 3.52.1. Version 3.52.1 removes YJImageLayoutEnhancer.

Better preserve the formatting of books from Standard Ebooks by allowing <br> elements with display:none styling. That styling was being removed by the plugin as part of the work around for a different problem.

Eliminate unnecessary Kindle Previewer conversion retries for unsupported book types such as comics.

Version 1.51.0 - 14 Apr 2021

Detect Kindle Previewer versions up to 3.52. Version 3.52 adds YJImageLayoutEnhancer.

Fix incorrect KFX style names sometimes produced by Kindle Previewer version 3.52.

Version 1.50.0 - 07 Mar 2021

Detect Kindle Previewer versions up to 3.51. Version 3.51 improves conversion of books with nested tables and lists.

Discard extraneous paths when reporting error messages related to EPUB internal files.

Version 1.49.0 - 09 Feb 2021

Improve the algorithm for generating page numbers to better handle books containing large paragraphs.

Always include the console output of the Kindle Previewer in the conversion log.

Fail with a specific error message if Wine is not accessible to calibre when running under Linux.

Version 1.48.0 - 11 Jan 2021

Detect Kindle Previewer versions up to 3.50.

Report an error if the TEMP folder path contains a "#" character. (Having that will prevent conversion by the Kindle Previewer.)

Fix error reporting for Kindle Previewer process launch failures.

Version 1.47.0 - 22 Dec 2020

Add support for the Linux platform. Requires that the Kindle Previewer be installed under Wine. See the "Installation" section of the plugin documentation for more information. (Thanks to mwaschbu.)

Add an option to include messages from the Kindle Previewer's quality report in the conversion log.

Version 1.46.0 - 18 Nov 2020

Detect Kindle Previewer versions up to 3.48.

Version 1.45.0 - 23 Oct 2020

Detect Kindle Previewer versions up to 3.47.

Support additional KFX features. (Fixes "Unknown com.amazon.yjconversion feature: reflow-style-13" and "Unknown com.amazon.yjconversion feature: yj_mixed_writing_mode-1")

Version 1.44.0 - 12 Sep 2020

Detect Kindle Previewer versions up to 3.44.

Internal code restructuring.

Version 1.43.0 - 02 Jul 2020

Detect Kindle Previewer versions up to 3.41. Version 3.41 includes some improvements to conversion.

Retry multiple times if the Kindle Previewer is unable to convert a book. This is a work around for a problem with the kindlegen component of the Previewer that causes conversion to occasionally fail unexpectedly.

Version 1.42.0 - 12 Jun 2020

Detect Kindle Previewer versions up to 3.40. (Version 3.40 is now a 64-bit application on Windows. On the PC platform it requires Windows 8.1 or later. It is no longer compatible with Windows 7.)

Allow Arabic-Indic numerals in page numbers.

Version 1.41.1 - 17 Apr 2020

Fix incorrect conversion error message if the Amazon Kindle Previewer is not installed. (Fixes "AttributeError: 'KindlePreviewer' object has no attribute 'program_name'")

Version 1.41.0 - 12 Apr 2020

Detect Kindle Previewer versions up to 3.38 and remove support for older versions. Version 3.38 handles additional formatting including page-break-after:avoid and page-break-before:avoid.

The Kindle Previewer's command-line interface is now used by this plugin because the undocumented conversion API previously used no longer functions properly. Because of this change the option to perform error tolerant conversion has been removed. Also fixed-layout books (comics and manga) can no longer be converted except when produced using Amazon Kindle Create.

Add an option to the plugin's command line interface (CLI) to display conversion logs for debugging.

Version 1.40.0 - 05 Mar 2020

Detect Kindle Previewer versions up to 3.37 and remove support for Previewer versions older than 3.35. Version 3.37 handles books with many SVG images, SVG images with viewBox having non-zero min-x or min-y co-ordinate, and tables with column widths specified in different units.

Handle different file layout used by Kindle Previewer 3.37 under MacOS. (Fixes "Conversion error:</b> Kindle Previewer 3 not installed as expected. (/Applications/Kindle Previewer 3.app/Contents/MacOS/lib/fc missing)")

Support additional KFX features. (Fixes "Unexpected Ion symbols used: $134")

Version 1.39.0 - 13 Feb 2020

Add experimental conversion of vertical Chinese language books to KFX. <meta name="primary-writing-mode" content="vertical-rl"/> must be present in the <metadata> section of the OPF to enable Chinese vertical text conversion. (Vertical Chinese is not officially supported in KFX by Amazon. Use at your own risk.)

Fix conversion of books containing the "background-clip" property. (Fixes "Unexpected Ion symbols used: $73")

Support additional KFX features. (Fixes "Unexpected Ion symbols used: $759")

Version 1.38.0 - 18 Jan 2020

Remove EPUB 3 switch elements. These sometimes cause the Kindle Previewer to become hung up and fail to complete conversion.

Version 1.37.0 - 10 Jan 2020

Detect Kindle Previewer versions up to 3.36.1.

Support additional KFX features. (Fixes "Invalid local symbol created: crop_bleed" and "Unexpected Ion symbols used: $35")

Replace the "-webkit-box-shadow" property with "box-shadow" in the source EPUB. This prevents conversion failure in the Kindle Previewer when "-webkit-box-shadow" is applied to inline elements.

Add an option in both GUI and CLI to stop conversion if a fifteen minute timeout is exceeded. This can help to debug cases where the Kindle Previewer becomes hung up during conversion.


Version 1.36.0 - 23 Dec 2019

Compatibility fixes for calibre beta versions using Python 3.

Detect Kindle Previewer versions up to 3.36 and remove support for Previewer versions older than 3.34. Version 3.36 provides better support for page-break-inside:avoid in CSS and for nested HTML tables.

Detect use of a non-standard installation directory for the Kindle Previewer under Windows. (Thanks to Silverbacknet.)

Reduce duplication of Kindle Previewer warning messages in the conversion log.

Version 1.35.0 - 07 Dec 2019

Support additional KFX features. (Fixes "Unexpected Ion symbols used: $46, $784")

Prevent incorrect date from being used if the publication date of a book to be converted is undefined.

Version 1.34.0 - 12 Nov 2019

Detect Kindle Previewer versions up to 3.35 and remove support for Previewer versions older than 3.32. Version 3.35 supports the widows/orphans CSS properties and vertical Japanese text.

Support new local symbol format produced by Kindle Previewer version 3.35. (Fixes "KFX creation error: Invalid local symbol created: rsrc7...")

Fix detection of missing or incorrect Kindle Previewer installation. (This has been broken in the KFX Output plugin since version 1.31.)

Version 1.33.0 - 03 Nov 2019

Ignore extraneous data in KPF files produced by Kindle Create version 1.32. (Fixes "Referenced fragment is missing from book")

Version 1.32.0 - 18 Oct 2019

Detect Kindle Previewer versions up to 3.34 and remove support for Previewer versions older than 3.31.

Remove the ".last" CLI function. (This feature is no longer needed since Kindle Previewer version 3.34 can now export KPF format for conversion to KFX.)

Add an option in both GUI and CLI to perform error tolerant conversion. This can sometimes allow conversion to proceed even if the book contains content that cannot be properly converted to KFX format. If this option is selected the result may not display as intended and may be missing content. (Kindle Previewer version 3.34 or later is required.)


Version 1.31.0 - 20 Aug 2019

Detect Kindle Previewer versions up to 3.32.

Internal restructuring.

Version 1.30.0 - 03 Jun 2019

Detect and support Kindle Previewer versions up to 3.31.0 and remove support for versions older than 3.29.2. Version 3.31.0 supports conversion of books with large HTML tables and additional languages: Afrikaans, Alsatian, Basque, Bokmal Norwegian, Breton, Catalan, Cornish, Corsican, Danish, Eastern Frisian, Finnish, Frisian, Galician, Icelandic, Irish, Luxembourgish, Manx, Northern Frisian, Norwegian, Nynorsk Norwegian, Provencal, Romansh, Russian, Scots, Scottish Gaelic, Swedish, Traditional Chinese, and Welsh.

Internal changes in preparation for the planned switch in calibre from Python 2 to Python 3.

Version 1.29.0 - 16 Apr 2019

Detect Previewer versions up to 3.30.

Version 1.28.0 - 02 Mar 2019

Add metadata (asset_id) required to allow Vocabulary Builder to work with sideloaded KFX books.

Preserve publication date metadata during conversion.

Detect Previewer versions up to 3.29.2.

Version 1.27.0 - 08 Feb 2019

Support Dutch language books. (Fixes "Unknown com.amazon.yjconversion feature: reflow-language-2")

Detect Previewer versions up to 3.29.1 and remove support for Previewer versions older than 3.27. (Newer Previewer versions produce better results.)

Allow the ".last" CLI function to work with Previewer version 3.29 and later.

Version 1.26.0 - 20 Dec 2018

Fix failure converting the most recent book from the Kindle Previewer GUI using the command line interface when file names containing non-ASCII characters are present in the user's TEMP directory.

Remove display:block styling added to <br> elements by calibre during conversion since it causes incorrect results in the Kindle Previewer.

Version 1.25.0 - 08 Dec 2018

Remove "data-AmznRemoved" and "data-AmznRemoved-M8" attributes sometimes left over in books obtained from Kindle sources.

Add "kfx_output_ignore_asin_metadata" plugin tweak that when to set to True will cause the plugin to always generate a new unique ASIN even if an ASIN is present in the book's identifiers or internal metadata. (This can be used to prevent a Kindle from downloading cover thumbnails that correspond to an ASIN that may happen to be present in the book's metadata, allowing a thumbnail set by calibre to remain unchanged.)

Detect Previewer versions up to 3.28.1. (Newer Previewer versions produce better results.)

Version 1.24.0 - 11 Nov 2018

Detect Previewer versions up to 3.28 and remove support for Previewer versions older than 3.24. (Newer Previewer versions produce better results.)

Support additional KFX features. (reflow-style-11)

Version 1.23.0 - 11 Oct 2018

Detect Previewer versions up to 3.27 and remove support for Previewer versions older than 3.23. (Newer Previewer versions produce better results.)

Support additional KFX features.

Version 1.22.0 - 13 Aug 2018

Detect Previewer versions up to 3.25 and remove support for Previewer versions older than 3.22. (Newer Previewer versions produce better results.)

The default conversion behavior has been changed to create a book (EBOK) instead of a personal document (PDOC). Removed the conversion option "Always create book instead of personal document" and added "Create personal document instead of book". Removed the command line option "--book" and added "--doc".

Fix conversion warnings for some missing files in the source EPUB not always being reported in the conversion log. (Some missing files may be reported multiple times as a side effect of this change.)

Fix incompatibility with calibre versions before 3.0 introduced in plugin version 1.17.0. (Fixes "AttributeError: 'apsw.Cursor' object has no attribute 'fetchone'")

Version 1.21.1 - 20 Jul 2018

Prevent conversion failure when a book contains an unexpected symbol count.

Version 1.21.0 - 20 Jul 2018

Detect Previewer versions up to 3.24. (Newer Previewer versions produce better results.)

Additional fixes applied to the source EPUB before conversion to work around the Previewer not handling URL escape in links. This mostly affects books whose internal file names contain spaces.

Extract additional conversion guidance from Previewer conversion logs.

Truncate the guidance report if it contains an excessive number of entries.

Version 1.20.0 - 25 Jun 2018

Add "kfx_output_previewer_path" plugin tweak to set the location where Kindle Previewer has been installed in cases where the default location was not used.

Detect Previewer versions up to 3.23 and remove support for Previewer versions older than 3.21. (Newer Previewer versions produce better results.)

Modify source file fix ups that are used when Kindle Previewer 3.23 or later is installed.

Version 1.19.0 - 21 May 2018

Allow conversion of comics with Guided View produced using Kindle Create version 1.6 in Early Access mode under Windows.

Fix error when converting KPF files produced by Kindle Create version 1.6: "CorruptError: malformed database schema (?)"

Improve location number generation.

Fix cover image metadata not being set correctly for comics.

Fix page numbers in a NAV page-list were being ignored if landmarks were also present.

Allow the ".last" CLI function to work with recent Previewer versions. (Fixes error: "No Kindle Previewer KDF database file found. No conversion results are available.")

Detect Previewer versions up to 3.22.

Version 1.18.0 - 09 Apr 2018

Set cover thumbnail to first page when converting from fixed layout KPF to KFX.

Version 1.17.0 - 02 Apr 2018

Detect Previewer versions up to 3.21.

Remove support for Previewer versions older than 3.17. (Newer Previewer versions produce better results.)

Internal restructuring and performance improvements.

Version 1.16.0 - 20 Feb 2018

Add support for Kindle Previewer version 3.20. (Fixes conversion error message detection.)

Allow repackaging of KFX-ZIP files into KFX containers using the command line interface. This works only for files that do not contain DRM.

Improve detection of unsupported KFX features.

Version 1.15.0 - 11 Jan 2018

Add support for Kindle Previewer version 3.17.1. (Fixes "Kindle Previewer error: Exception in thread "main" com.b.a.n: Unknown option: -allowYJConversionForJP")

Version 1.14.2 - 08 Jan 2018

Fix bug introduced in version 1.14.0. The ASIN value from book identifiers is not being used during conversion.

Version 1.14.1 - 05 Jan 2018

Fix error when updating to version 1.14.0: ImportError: cannot import name AUTO_PAGES

Version 1.14.0 - 05 Jan 2018

Allow the lookup name for a custom column holding the desired number of pages for each book to be specified when creating approximate page numbers.

Improve support for Kindle Previewer version 3.17. Handle change to the format of conversion guidance. Allow conversion of books containing MathML.

Remove support for Previewer versions older than 3.15. (Newer Previewer versions produce better results.)

Retry conversion with location map generation disabled if the first conversion fails with an accuracy threshold error. This allows more books to be successfully converted. (Previewer 3.17 or later is required.)

Additional fixes applied to the source EPUB before conversion.

Prevent plugin installation under Linux since Kindle Previewer 3 does not run under that OS.

Version 1.13.0 - 22 Nov 2017

Allow the optional creation of approximate page numbers in cases where real page numbers are not present in the source file of the book.

Added a Metadata Writer Plugin to allow the metadata and cover of existing KFX books to be updated.

Allow an EPUB file that has been cleaned of some potential problems to be saved using the CLI.

Fix occasional non-working links in the table of contents of books converted from AZW3 format.

Possible fix for reported conversion error: "Kindle Previewer error: Error(YJEpubAdapter):E00601: Internal error occured. java.lang.UnsatisfiedLinkError: ...\\shared.dll: Can't find dependent libraries"

Version 1.12.1 - 02 Nov 2017

Attempt to prevent error in Preferences -> Output Options.

Version 1.12.0 - 18 Oct 2017

Show conversion guidance produced by the Kindle Previewer and allow conversion of Arabic and Japanese language books when running Mac OS. (Accidentally left out of previous release.)

Added error logging to help detect the cause of Kindle Previewer failures.

Version 1.11.0 - 16 Oct 2017

Change the ".last" CLI function to work with recent Previewer versions. (Fixes error: "No Kindle Previewer KDF database file found. No conversion results are available.")

Remove the "kfx_output_force_cde_type_ebok" plugin tweak. This feature is now supported through plugin configuration.

List features and metadata of the KFX book in the conversion job log.

Show conversion guidance produced by the Kindle Previewer in the conversion job log. (Previewer version 3.15 or later is required.)

The full conversion log from the Kindle Previewer will no longer be included in the conversion job log. This can be overridden through plugin configuration.

Allow Arabic language books to be converted. (Previewer version 3.14 or later is required. Support for Arabic in Kindle apps/devices is currently incomplete.)

Allow Japanese language books to be converted. (Previewer version 3.15 or later is required. Only horizontal text is supported in Previewer 3.15.)

Handle some additional EPUB problems that would otherwise cause the Previewer to fail. (order of language declarations, incorrectly coded horizontal ellipsis entity)

Version 1.10.0 - 30 Aug 2017

Adjustments to output format to better match KFX files currently produced by Amazon. (Reading these files with the latest Kindle firmware/app version is recommended for best results.)

Fix occasional error during conversion: "TypeError: info() takes exactly 2 arguments (3 given)"

Attempt to work around occasional error during conversion caused by unexpected data produced by the Previewer: "yj.eidhash_eid_section_map has extra: ..."

Version 1.9.0 - 09 Aug 2017

Remove support for Previewer versions older than 3.13.

Allow English language MS Word DOC and DOCX files and MOBI files (created using kindlegen version 2.9 without the -dont_append_source option) to be converted to KFX using the Command Line Interface.

Allow Chinese language books to be converted.

Improve performance when converting large and complex books.

Improve reporting of conversion errors. Do not truncate (tail) Previewer conversion logs in the calibre conversion job log.

Handle more EPUB problems that would otherwise cause the Previewer to fail. (badly sized transparent GIFs, "onload" attribute)

Further internal changes based on the Amazon Ion specifications.

Version 1.8.1 - 31 Jul 2017

Remove the conversion time limit set by the plugin so that larger books can be converted. (A time limit can sill be set in calibre using Preferences, Miscellaneous, Abort jobs that take more than...)

Version 1.8.0 - 12 May 2017

Allow conversion of fixed layout comics and manga using Kindle Previewer version 3.10.1 or higher using the command line interface. See "Converting Comics and Manga" in the first post of this thread for more information.

Allow conversion of KPF files produced by the Amazon Kindle Create software using the command line interface.

Allow conversion of unzipped EPUBs in the command line interface by using an OPF as the input file.

Allow conversion of page numbers contained in an EPUB-3 NAV page-list within the source EPUB.

Include Previewer conversion logs in the calibre conversion job log even when conversion is successful.

Attempt to correct failures for some users when running 64-bit calibre under Windows Vista.

Internal changes to better match the Amazon Ion specifications. (KFX is based on Ion.)

Version 1.7.1 - 26 Mar 2017

Fix bug when running under MacOS introduced in version 1.7.0. (Fixes "TypeError: encode() argument 1 must be string, not None")

Version 1.7.0 - 22 Mar 2017

Fix incompatibility with Kindle Previewer 3.9 beta and improve handling of conversion error logs. (Fixes "KFX creation error: Unexpected conversion log: log_processEpub.txt")

Improve handling of non-ASCII system environments. (Untested under Mac OS.)

Remove support for Previewer versions older than 3.7 beta.

Minor changes and bug fixes.

Version 1.6.0 - 23 Dec 2016

Add support for Kindle Previewer 3.7 beta. (Previewer version 3.7 is recommended for use with this version of the plugin. It converts some books with unusual formatting that previous versions could not.)

Fix bug that caused some problems with the NCX TOC to not be corrected before conversion.

Version 1.5.3 - 12 Dec 2016

Fix conversion when using Kindle Previewer 3.6 beta under Mac OS.

Version 1.5.0 - 27 Nov 2016

Add support for Kindle Previewer 3.6 beta. (That is now the recommended version of the Previewer for use with this version of the plugin. It converts some books containing tables that previous versions could not.)

Capture log files during the first conversion attempt. This avoids the need to perform a second conversion to capture logs if the first one fails.

Automatically retry after conversion errors that occur inconsistently.

Version 1.4.0 - 24 Oct 2016

Allow a "mobi-asin" identifier to be used as the source of the book's ASIN.

The plugin tweak "kfx_output_force_cde_type_ebok = True" will cause converted books to no longer be marked as personal documents.

Version 1.3.0 - 20 Sep 2016

An invisible character will be added to empty table cells to work around a Previewer bug. (A visible character was used previously.)

If no ASIN is specified the converted book will be marked as a "personal document" and a unique ASIN will be generated. (An ASIN is required for the support of cover thumbnails on e-ink Kindles.)

Add support for Kindle Previewer 3.5 beta. (KFX generation from Previewer version 3.5 is unchanged from version 3.4.)

Version 1.2.0 - 15 Aug 2016

Add support for Kindle Previewer 3.4 beta. (That is now the recommended version of the Previewer for use with this version of the plugin.)

Allow conversion of page numbers contained in an NCX pageList or page-map.xml within the source EPUB. (Page numbers must be present in the EPUB. "Fake" page numbers will not be produced. EPUB 3 page-list and Amazon APNX are not supported.)

Correct some issues in the source EPUB that could prevent conversion by Previewer: character encoding, obfuscated fonts, background RECT in SVG, language "UND", missing/duplicated title, table cell with no visible text, and a few others.

Include the book title in pop-up conversion failure dialogs.

Save the Kindle Previewer version used within created KFX files to aid in future debugging.

Generate a unique content_id for books that do not have an ASIN.

Version 1.1.2 - 08 Apr 2016

Fix inability to highlight text in converted books on Kindle devices.

Assure author names are in the correct format for sorting.

Allow conversion using the plugin within calibre under Mac OS.

Version 1.1.1 - 30 Mar 2016

Fix error from calibre when the plugin is updated from an older version.

Version 1.1.0 - 30 Mar 2016

Add command line interface for advanced users. This provides a means for Mac users to produce KFX files since conversion within calibre is not currently working under Mac OS.

Version 1.0.0 - 26 Mar 2016

Initial release.

[jhowell]

Open KFX with Kindle Previewer 3

KFX files produced by the KFX Conversion Output plugin or imported using the KFX Input plugin can be viewed using Kindle Previewer 3. However, the Previewer supports the file extension .azw8 for opening KFX files instead of .kfx. In order to open a KFX file with the Previewer it must first be copied or renamed so that it has a .azw8 extension.

The "Open KFX with Kindle Previewer 3.bat" script can be installed in Windows to allow files with a .kfx extension to be viewed more easily.

Installation:

• Kindle Previewer 3 must already be installed for the current user.
• Download the .zip file attached to this post.
• Extract the enclosed "Open KFX with Kindle Previewer 3.bat" file.
• Place this .bat file in a permanent location of your choice on the PC.
• Right-click the .bat file and select "Run as administrator". The script will report success or failure. Press enter to close it. (This will associate the script with .kfx files. Repeating this step will remove the association.)

Once associated the script file will execute whenever .kfx files are to be opened.


Usage:

Once installed you can then select a converted book in calibre and in the "Formats" section of the book details panel and simply click on "KFX" to open it with the Previewer. The .kfx file will be copied to a temporary .azw8 file and opened with Kindle Preview 3.


Limitations:

This script uses a simple method to create the file type association, not the best possible method.

A Command window will briefly pop up whenever the script is activated.

It has only been tested under Windows 10.

It is not available for MacOS or Linux. (For a similar workaround under MacOS see this post.)

Version History:

Spoiler:

Version 1.0.0 - 24 Oct 2016

Initial release.

[cerem0ny]

Thank you! You're a genius and inspire me to search and regain faith and trust in humanity. God bless!

...

but what IS funny is that the okugin seems to have more success converting .kfx than the previewer itself! Go figure. Why is that?!?

[jhowell]

Originally Posted by cerem0ny

but what IS funny is that the okugin seems to have more success converting .kfx than the previewer itself! Go figure. Why is that?!?

The first step in the conversion process is to convert the source format to EPUB, even if the book is already in EPUB format. This process can fix some things that would otherwise cause the Previewer to fail.

For example, the Previewer fails if the source EPUB does not have UTF-8 character encoding. The initial conversion step automatically converts other encodings to UTF-8.

[Nate the great]

Here's the log from my failed attempt:

[jhowell]

Originally Posted by Nate the great

Here's the log from my failed attempt: ...

There isn't much I can tell from it. The Previewer's conversion routine, which runs under a Java installation included with the Previewer, somehow failed to launch. There is nothing in the log to indicate why. I can't tell if the problem is specific to Windows 7 or your particular PC.

I'll try to think of a way to have the plugin gather more information on this type of failure. In the mean time I have some questions to help diagnose the problem:

• Were there any other error messages displayed on your system when the conversion failed? If so, what?
  
• Have you used the Kindle Previewer to verify that it functions properly on your system? You could try opening this book and verifying that it displays with Enhanced Typesetting (hyphenation) in the Previewer. Press Ctrl-I after opening the book in the Previewer and make sure that the information dialog shows "Enhanced Typesetting: Supported".
  
• If you are running an anti-virus program could you try disabling it before launching a conversion to see if that helps?

[amordechai]

Hi. I registered only for this.

First: thank you SO much for doing this!

Sadly I tried using your plugin with the latest version of calibre and Kindle previewer 3 on my mac but i got an error message and the conversion failed.
here is the log: http://pastebin.com/uUhqQWny
I'm not using any antivirus that could interfere.

It crashed with the Frankenstein book you linked. Later I tried to import the book in kindle previewer and got the "Enhanced Typesetting: Supported" message, so this seems to work.

Thank you again for your work!
Antonio

[jhowell]

Originally Posted by amordechai

Sadly I tried using your plugin with the latest version of calibre and Kindle previewer 3 on my mac but i got an error message and the conversion failed.

I was not able to test the plugin under Mac OS so it is not surprising that it failed to work.

I had to make some guesses about where files are located in the Mac version of the Previewer and I guessed wrong. I will have a new version of the plugin ready in a day or two that may fix the problem. Please post a new log if the new version of the plugin still fails for you.

Thanks for your error report.

[Nate the great]

Originally Posted by jhowell

There isn't much I can tell from it. The Previewer's conversion routine, which runs under a Java installation included with the Previewer, somehow failed to launch. There is nothing in the log to indicate why. I can't tell if the problem is specific to Windows 7 or your particular PC.

I'll try to think of a way to have the plugin gather more information on this type of failure. In the mean time I have some questions to help diagnose the problem:

• Were there any other error messages displayed on your system when the conversion failed? If so, what?
  
• Have you used the Kindle Previewer to verify that it functions properly on your system? You could try opening this book and verifying that it displays with Enhanced Typesetting (hyphenation) in the Previewer. Press Ctrl-I after opening the book in the Previewer and make sure that the information dialog shows "Enhanced Typesetting: Supported".
  
• If you are running an anti-virus program could you try disabling it before launching a conversion to see if that helps?

The converter works, yes, and it did make a couple ebooks with the enhancements. I saw the hyphenation.

Then it asked me to update to 3.1, which I did.

After that I ran the plugin again in calibre, and this time it told me that KindleImageConverter failed (twice, on one job).

And then, on the next try, it converted the ebook which had failed 4 times already.

So now it is working - sorta.

[Alice Green]

How can I use the Amazon Kindle Previewer to convert from EPUB to KDF, when I open the EPUB via Kindle Previewer, it convert it to Mobi format. I have not seen any convert options to KDF.

[Nate the great]

Originally Posted by Alice Green

How can I use the Amazon Kindle Previewer to convert from EPUB to KDF, when I open the EPUB via Kindle Previewer, it convert it to Mobi format. I have not seen any convert options to KDF.

The easiest way is to do it via calibre.

But to be clear, that "Mobi" file you just made isn't just a Mobi file. Did you notice how it is several times the size of the Epub you started with? That's because it actually contains several different ebooks, including the original Epub, Mobi, and the new KFX.

[amordechai]

Originally Posted by jhowell

I was not able to test the plugin under Mac OS so it is not surprising that it failed to work.

I had to make some guesses about where files are located in the Mac version of the Previewer and I guessed wrong. I will have a new version of the plugin ready in a day or two that may fix the problem. Please post a new log if the new version of the plugin still fails for you.

Thanks for your error report.

I wil definitely try the new version of the plugin and report back.

Thanks for your work!

[cerem0ny]

Wish I kept my Aura H2O! Can't remember any problems with the typography but this conversion process is so hit and miss, it's annoying! Props for the plugin however

[enjambement]

if you use the book "Azw3", you can convert the book in KFX always. Sorry for my English, I'm Italian.

[jhowell]

Originally Posted by Nate the great

And then, on the next try, it converted the ebook which had failed 4 times already.
So now it is working - sorta.

Conversion by the plugin is dependent on Amazon's Kindle Previewer working properly and Amazon didn't do a very good job of with that software. For me it fails on more books than it works, but it does work or fail consistently on any particular book.

I don't know why it functions inconsistently for you and presumably others. It may be due to a bug in the plugin, but since I can't duplicate the problem I am unable to diagnose it further at the moment.

Originally Posted by Alice Green

How can I use the Amazon Kindle Previewer to convert from EPUB to KDF, when I open the EPUB via Kindle Previewer, it convert it to Mobi format. I have not seen any convert options to KDF.

You do not need to locate the KDF files created by the Kindle Previewer to make use of the KFX Output plugin. It invokes the conversion function of the Previewer and uses the resulting KDF file automatically. But for those interested, I will describe more of how it works.

After opening a book with the Kindle Previewer you will usually see a dialog box with the message "Your book successfully converted into Kindle format" with a link to a folder containing all of the MOBI files produced by the Previewer. This message is a bit misleading since it doesn't let you know whether or not allowing Enhanced Typesetting succeeded for that book.

The Previewer generates a KDF file for each book, but only if it succeeds at converting it for Enhanced Typesetting. To tell if this was successful you need to check the book information screen using Ctrl-I or by selecting View->Book Information via the program menu. If this shows "Enhanced Typesetting: Supported" then a KDF file was produced. If it show "Not Supported" then it failed to produced the KDF.

The KDF file will be in a recently created subdirectory of your TEMP directory. A different random subdirectory is used for each book. You need to locate the one created at the time that you opened your book in the Previewer. For example, on my Windows PC the TEMP directory is "C:\Users\John\AppData\Local\Temp" and I can find the most recently converted book within it named "145a-0754-be2f-1d6e\book\book.kdf".