[Plugin] AddKindleMediaQueries

[slowsmile]

Optimally dual-formats all epub image entries both for KF7 devices(in pixels) and KF8 devices(as a %)

Requirements
Plugin Type: Edit
MIT Licence(OSI)
Minimum Sigil requirement: v0.9.3 or higher
Python Requirements: Python 3.4+ (Bundled or External)
OS Requirements: Windows, Linux or OSX
*** Tested on Windows 7, 8 & 10 only ***
Current Version: "0.1.9"

Installation
* Select Manage Plugins from the Plugins menu. In the dialog box, select either the Bundled Python or the External Python(Python 3.4+ should be installed on your computer to run this plugin externally).
* Click Add Plugin and select AddKindleMediaQueries_vXXX.zip. This will load and install the plugin into Sigil, which you can then select and run the plugin by selecting Plugins > Edit > AddKindleMediaQueries.

Description
This simple plugin is an edit plugin that automatically dual formats all ebook image entries in your epub and also adds the appropriate media queries to the main stylesheet for optimal rendering of all images on both KF7 devices(in pixels) and KF8 devices(as percentages). At runtime on Kindle ereaders the media queries in the CSS will then select the appropriate image line to display according to whether your ebook is running on a Kindle KF7 device or KF8 device.

This plugin will now automatically dual format svg images for Kindle epubs. KF8 ebook images will be displayed in svg format whereas KF7 ebook images will be added and displayed in html style using pixel values.See Caveat below.(added in v0.1.8)

User Options(via dialog):

*Add media queries to this stylesheet
This is an option dropdown list that allows you to select the right stylesheet from your epub to add the media queries. The stylesheet that you choose should be the main stylesheet that is used to style all text files and images in your epub.

* Type preferred base pixel width value
This text entry option allows you to type in your own preferred base width value in pixels for the % calculation. This value is used to calculate the percentage width of the images for KF8 devices only. The calculation is shown below.

image-width-in-pixels/630 x 100

The 630px value is the default base width option(or default screen width option). So the user has the option of either typing in a larger or smaller base width value for all ebook images which allows the user to increase or decrease the dimensions of all ebook images or the user can just use the default -- 630px. If you are unsure about how to use this option then you should just use the default base pixel width value.

Plugin Run
First load your epub into Sigil and then just run this plugin.

Please also be aware that the above percentage calculation for all Kindle KF8 image dimensions will not be exact but will instead be a best-average or ballpark percentage width because I've only used a single, default base width value(average screen width value) for all Kindle KF8 devices in my percentage calculation above. This will inevitably give small variances in displayed image size across the many different KF8 devices and legacy KF8s(with slightly different screen widths) because I have only used a single, best-average screen width value for all calculations.

Updates
* The plugin can now handle all forms of div with image tag formatting(changed in v0.1.5)

Changes

Spoiler:

v0.1.9

-- Added error warning dialog if any image filenames contain spaces.

v0.1.8

-- This plugin will now automatically dual format svg images for Kindle epubs. KF8 ebook images will be displayed in svg format whereas KF7 ebook images will be added and displayed using their original pixel values.
-- Improved logging

v0.1.7

-- Added MIT SW Licence

v0.1.6

-- Fixed bug causing SVG errors. You can now load an epub containing SVG image wrappers and there should be no Epubcheck errors.

v0.1.5

-- The plugin can now handle all forms of div with image tag formatting

v0.1.4

-- Fixed a bug causing lower case font name errors and duplication errors in the css and the html repectively. Thanks to Doitsu.

v0.1.3

-- Initial release

[slowsmile]

Updates

* Having SVG image wrappers in your epub will no longer cause Epubcheck errors after running this plugin.(changed in v0.1.6)

* The plugin can now handle all forms of div with image tag formatting(changed in v0.1.5)

[JSWolf]

You you use an SVG image wrapper, are you specifying the exact resolution for the images in the SVG wrapper? If not, that can cause a display issue.

[slowsmile]

@JSWolf...The above update simply means that if you have any SVG image wrappers in your epub then, after using the plugin, this would cause SVG errors on Epubcheck. With the above update, this bug has been fixed. The plugin should only dual format ordinary html images only -- it will not dual format svg image wrappers.

[slowsmile]

Update: The following changes have been made to the plugin in v0.1.8:

* The plugin will now automatically dual format svg images for Kindle epubs. KF8 ebook images will be displayed in svg format whereas KF7 ebook images will be added and displayed in html style using simple pixel values.

* Improved logging

[Gregg Bell]

Wow, thank you for this great plugin! I get most of it, but I do have some quetions. Perhaps it's just a semantics thing but when you say

This plugin will now automatically dual format svg images for Kindle epubs. KF8 ebook images will be displayed in svg format

are you saying the KF8 images will be displayed in percentages? (Because there are no svg files.) Or were you referring to the cover image that's a jpg in an SVG wrapper?

And how does KFX figure into all of this?

And 630 seems to be a great number for the base width, but what is the reasoning behind it (especially considering specific devices)?

[slowsmile]

Gregg...This plugin does two things:

1. If an svg image is detected in your epub then the image will be dual formatted to display an svg image for KF8 devices and will also be formatted as a jpeg image(in pixels) for display on older KF7 devices. The svg formatting is also not changed at all.

2. If a jpeg image is detected in your epub then the image will be dual formatted to display a jpeg image for a KF8 device with height/width as a % of current screen width and will also be formatted to display as a jpeg image(in pixels) for older KF7 devices.

The above image selection is wholly dependant on which Kindle device is currently running your ebook -- whether its a KF8 or KF7 device. The identification of the device -- whether KF8 or KF7 -- is completely handled by the media queries in your stylesheet. This means that the media queries can also automatically turn on and turn off these device-dependant html image displays as required.

"And how does KFX figure into all of this?"
It doesn't. This plugin is only for epub 2. KFX essentially means that every page in your ebook becomes a jpeg image that is always 100% max page size. This plugin is only really useful for smaller images that are less than max page size.

"And 630 seems to be a great number for the base width, but what is the reasoning behind it (especially considering specific devices)?"
This only applies to % h/w image sizing for KF8 devices. The base width is just a ballpark value because of the large variance of different-sized KF8 device screens out there now -- on both past and present devices. The whole thing -- using simple maths -- is described in my release notes for this plugin. Basically if you increase the base width(i.e. > 630px) then all KF8 image sizes will get smaller throughout your epub and if you decrease the base width(i.e. < 630px) then all your KF8 images will get larger. That's all you really have to know. If you want to increase/decrease individual % h/w sizes(for KF8 only) for a particular image then you will have to do that manually within the relevant image tag in the html.

The pixel h/w values used above for older KF7 devices are fixed or absolute values. So you must get those pixel image dimensions right for the KF7 screen when you initially size the original image because there is no safe way of adjusting absolute pixel values in situ for such images without problems.

[Gregg Bell]

Originally Posted by slowsmile

"And how does KFX figure into all of this?"
It doesn't. This plugin is only for epub 2. KFX essentially means that every page in your ebook becomes a jpeg image that is always 100% max page size. This plugin is only really useful for smaller images that are less than max page size.

Thanks Bill. Great explanation. But about KFX I thought KDP was "rolling it out" for all devices. I only do epub 2 so I'm sure your plug-in is for me, but I'm still wondering how KFX figures into things. (I did find the MR link and it said "very little is known" about it.)

Originally Posted by slowsmile

The pixel h/w values used above for older KF7 devices are fixed or absolute values. So you must get those pixel image dimensions right for the KF7 screen when you initially size the original image because there is no safe way of adjusting absolute pixel values in situ for such images without problems.

I have the Kindle Touch 7 ereader and a Fire HD8 Tablet. I'm pretty sure they're both KF8. Is there any way I can see what my files look like on KF7 devices without having the actual devices? Any previewers out there that you know of?

[slowsmile]

Gregg...

"I only do epub 2 so I'm sure your plug-in is for me, but I'm still wondering how KFX figures into things. (I did find the MR link and it said "very little is known" about it.)"

Creating a KFX or Kindle fixed format ebook does have some advantages. But it also has many disadvantages plus one huge monetary disadvantage. Best that you download and read my free pdf ebook -- Using Kindle Create -- if you want the full story. The advantages/disadvantages of KFX conversion are all fully explained in the pros and cons section in the first chapter(All About Kindle Create). And, as you'll see, the cons far outweigh the pros whenever you convert to KFX, which is why I would never consider using KFX for my ebooks because there are just too many painful downsides as far as I'm concerned. The download link to my free ebook is here:
https://drive.google.com/file/d/1GPM5zEybRlOdFyY3vE05cRGRFpsSvFqo/view?usp=sharing

"Is there any way I can see what my files look like on KF7 devices without having the actual devices? Any previewers out there that you know of?"

I still use the older version of Kindle Previewer (not Kindle Previewer 3) to check how my epubs behave on older KF7 devices. The KF7 display emulation on the older KP version is quite good. Unfortunately I think Amazon has removed the download link for this older version, so that's probably not going to help you. I can't think of any other prog that would help you, sorry.

[Gregg Bell]

Hi Bill, I downloaded the book. Thanks. As far as I can tell though, when I upload to KDP, it distributes whatever file format will work on the devices, including KFX.

Like in this post from https://fileinfo.com/extension/kfx :

eBooks may be saved in one of several formats. The format of an eBook downloaded from the Amazon store depends on the device being used to download and read the eBook. It may be saved in the KFX format or in the .MOBI, .AZW, or .AZW3 formats.

So is it the kind of thing that you (as a professional) can choose whether to use KFX but I (as a writer just uploading to KDP) can not?

[slowsmile]

Gregg...

"Hi Bill, I downloaded the book. Thanks. As far as I can tell though, when I upload to KDP, it distributes whatever file format will work on the devices, including KFX."

No, KDP will not automatically convert your reflowable ebook to KFX format on conversion, if that's what you're saying above. You have to upload your ebook specifically in KFX format and this will result in only KFX distribution on Kindle devices that can handle it.

You should also consider that KFX format(as a .kpf file) will NOT work on mobile phones or older Kindle E-ink devices(i.e.KF7). So, do you really want to upload your ebook in KFX format with those somewhat severe customer restrictions? And if your KFX ebook is over 20 pages in length, do you really want to lose ALL your ebook profit while using Amazon's 70% profit option?

"So is it the kind of thing that you (as a professional) can choose whether to use KFX but I (as a writer just uploading to KDP) can not?"

Whether you decide to use KFX format is really up to you as the indie publisher. Converting to KFX using KC is very easy -- you don't need any html knowledge to convert your book to KFX format using Kindle Create. All you do is just choose the KFX book type, then load a pdf version of your ebook into Kindle Create and it will automatically be converted to KFX format(as a .kpf file) for you to upload. But you should really take heed of all the many KFX downsides that I've mentioned in my book before you consider publishing a KFX ebook. If you already write and publish mainly text heavy reflowable epub 2 ebooks, there should really be no reason or need for you to publish in KFX format.

In my book, if you go to Chapter 1 > Pros and cons of loading a PDF in Kindle Create this section should help to dissuade you from ever using KFX format.

[Doitsu]

Originally Posted by slowsmile

No, KDP will not automatically convert your reflowable ebook to KFX format on conversion, if that's what you're saying above. You have to upload your ebook specifically in KFX format and this will result in only KFX distribution on Kindle devices that can handle it.

You're mistaken. If you generate a valid reflowable epub and open it with Kindle Previewer, it'll clearly indicate whether Amazon KDP will be able to convert it to an Enhanced Typesetting (KFX) file for all devices that support them.



If the epub/mobi file supports Enhanced Typesetting, Amazon will convert it to a KFX file, if the device/app supports it. If the green check mark is missing, users will get at most AZW3 files.


@Gregg Bell The command line version of the jhowell's KFX converter can fix some common issues that would otherwise prevent books from being converted to KFX files, if you add the --clean parameter.

[jhowell]

There seems to be a bit of confusion about KFX format. Here is an overview.

KFX (Kindle Format 10) is the successor to KF8 (Kindle format 8) for the delivery of content to newer Kindle apps and devices. KF8 and the even older MOBI7 are based on HTML. KFX is instead based on Amazon Ion, a proprietary data representation created by Amazon.

KFX format is produced by Amazon based on the source format provided by the publisher. Some books cannot be converted to KFX. Those that contain content that cannot be yet represented in KFX format will be delivered to customers in KF8 or MOBI7 format instead as a fallback.

KFX is capable of handling several different types of content: reflowable layout e-books (features similar to EPUB), illustrated layout with video (Kindle in Motion), fixed layout (comics and manga), print replica (similar to PDF), magazines, and dictionaries. Books available in reflowable KFX format are indicated by "Enhanced Typesetting: Enabled" on the product page. For other types of content there is no obvious indicator of KFX format.

KPF (Kindle Package Format) is produced by the Kindle Create application. KPF carries the same content as KFX, packaged differently. Based on the type of book the publisher selects to be created, Kindle Create will produce either the reflowable, fixed layout or print replica variant of KPF/KFX. When possible, a fallback MOBI7 format is produced by Amazon from the KPF for delivery to older Kindle devices that are not capable of handling KFX.

Unlike KF8, which has had essentially the same capabilities as when it was first released, Amazon is continuously extending the feature set of KFX to handle more cases. Amazon periodically re-processes already published books to try to convert them to the latest version of KFX format.

[slowsmile]

Doitsu...I'm not sure why you brought in reflowable epubs and Enhanced Typsetting. I've specifically been talking about KFX generated from Kindle Create.

When you generate a KFX file from Kindle Create, what you will always get is a KFX ebook where every single page is a jpeg image. And when you load that KFX file into KP3 for test, yes Enhanced Typsetting will be enabled. But what does that mean?? If there is no text in your KFX then there is no text that needs checking or enabling by ET. That's why a KC-derived KFX ebook always passes ET. Right? That's also why Enhanced Typsetting is completely irrelevant for KFX ebooks currently generated by Kindle Create.

"If the epub/mobi file supports Enhanced Typesetting, Amazon will convert it to a KFX file, if the device/app supports it. If the green check mark is missing, users will get at most AZW3 files."

If I submit a KFX file that has been entirely generated by Kindle Create software where every page is a jpeg image, you're saying that if it fails KP3's Enhanced Typsetting then Amazon will automatically convert my KFX -- consisting of nothing but page sized jpeg images -- to reflowable KF8?? Are you kidding? Why would Kindle Previewer fail ET on a KFX file that was successfully generated from a pdf file by it's own Kindle software??

[Doitsu]

Originally Posted by slowsmile

Doitsu...I'm not sure why you brought in reflowable epubs and Enhanced Typsetting. I've specifically been talking about KFX generated from Kindle Create.

You yourself specifically mentioned reflowable epubs:

Originally Posted by slowsmile

No, KDP will not automatically convert your reflowable ebook to KFX format on conversion [...]

(Emphasis mine.) Besides Gregg Bell never mentioned that he uses Kindle Create. (AFAIK, he mostly uses Sigil.)

Originally Posted by slowsmile

What? If I submit a KFX file, entirely created by Kindle software where every page is a jpeg image, you're saying that if it fails Enhanced Typsetting then Amazon will automatically convert my KFX

I've never said this. You might want to re-read my post.