For those who don't already know,
X-Ray is a reference feature available on any Kindle product with a touch screen (Touch, Paperwhite, Kindle for Android, etc), provided the book has an X-Ray available for it.
X-Ray Builder gives users the ability to create fully-functional X-Rays for both retail books that Amazon has not X-Ray-enabled yet as well as side-loaded books that have been purchased elsewhere.
It will also build some extra metadata files:
- Author Profile - Enables "About the author" button
- Start Actions - "About this book" info which usually has a description of the book, author, and some recommendations
- End Actions - Pops up when you're done reading the book to provide recommendations on what to read next
Goodreads is used as the main datasource, but does not always contain rich character information. A new source called Roentgen is now available that may have more data available depending on the book.
Requirements:
Instructions:
See camelx's step-by-step guide and the
Quality Check plugin.
You can also check out the
basic video demo that gives you a 5min rundown of how to use the program.
May 2020 Note
These instructions are outdated and may not be entirely accurate anymore.
I'll try to update them at some point...
In general you should be able to:
- Open the book (ideally fix the ASIN if it prompts & successfully finds the book on Amazon)
- Click the search button to get the Goodreads link
- Click the checkmark "1-click" button to start building all files
- Answer the prompts during the build process
- Either everything worked or the log will show what went wrong (depending on how many terms were found you may want to switch sources)
Terms Builder (useful for users creating translated X-Rays)
There is a button for downloading all terms to an XML file as well as a simple interface for adding/modifying them.
When available, terms can also be imported into the terms builder directly from Roentgen.
Creating the perfect X-Ray
Creating a perfect X-Ray is not a 1-step process, but a decent one is usually just a few clicks away.
The default options will usually give you a reasonable result but getting the best results may require a bit of effort.
Character aliases usually need to be used to match more locations within the book, for example if the character name is "Harry Potter", the builder won't know that you also want to match the word "Harry" as well.
For some books, a last name might be exclusive to a character and used on its own - making "Potter" a valid alias. In most cases this isn't possible, as it would also match any other spot where the last name shows up - "James Potter."
This requires knowing how the names are used throughout the book, which mostly defeats the purpose of having the X-Ray in the first place.
Alias Files:
Spoiler:
Special options:- Automatically split aliases - This will match first and last names as well as common titles like "Captain" and "Mr." Use this feature carefully as it can cause incorrect matches in some cases.
After downloading the terms, they will be exported to a .aliases file in the ext folder, named after the book's ASIN.
Characters do not usually show up by their full name throughout the text. The alias file allows you to define aliases for characters/topics manually to maximize the number of excerpts found within the book.
Aliases follow the format:
Character Name|Alias1,Alias2,Etc
John Smith|Mr. Smith,Johnny,John
Ensure that any aliases that are very basic, eg John, are at the end. Otherwise, if you have a setup like "John Smith|John,Johnny", "John" will always match before "Johnny" does and it will look weird when you're viewing the X-Ray.
X-Ray Builder will tell you if no excerpts were found when processing. If you have never read the book before, you can ignore this if you wish; the X-Ray will not be ideal but it will work. For characters with a first and last name, you can usually assume that their first name will be used and can add an alias for it (John Smith|John).
There are a number of switches that can be used to change the matching behavior for that character only:
- /c - Searches will be case-sensitive
- /d - Delete this character (not all terms on Shelfari may be desired)
- /n - Will not match any excerpts but will leave character in X-Ray
- /r - Aliases will be processed as regular expressions (case-sensitive unless specified). ONLY the aliases will be used in this case; the character's original name (to the left of the | symbol) WILL NOT BE USED.
Only one switch can be used per character and should be used like this:
Character Name|/c,Alias1,Alias2
For more information on regular expressions for .NET check out
this page.
For creating and testing expressions,
RegExr is a great resource.
Troubleshooting
Spoiler:
X-Ray is overwritten when not using airplane mode
If your book has X-Ray enabled by Amazon, your Kindle may try to download theirs.
If you want to keep your own, you will need to set the file to read-only when you copy it to the Kindle.
X-Ray button does not show up:- File was not placed in the correct location. Should be in the .sdr folder for your book.
- If you converted your book using Calibre, ensure the converted copy of the book is copied back to your Kindle (from the Calibre Library).
- Book is tagged as a personal document. Copy your book from the Calibre Library *after* building the X-Ray.
X-Ray button shows up but does not open and the X-Ray file you copied is deleted:- Ensure the "use new format" option is enabled in the settings.
Acknowledgements
Thanks to:
- jhowell for the KFX Input/Output plugins
- darrenmcg for completely overhauling the interface and adding many new features
- shinew for the original X-Ray creation site and source
- Everyone who has used the program so far, especially those who have reported any errors or suggested new features
Source:
GUI Version:
Ephemerality/xray-builder.gui
Error Reporting:
Any issues with the program can be posted here (if you paste any logs, please put them in a spoiler tag), PMed directly to me, or posted as an issue on GitHub.
A copy of the book can be very helpful as well and can be sent to me if you want. Books are used for testing purposes only and deleted afterwards (must be DRM-free).
Kindle app for Android
There is now an option in Settings to turn on building for Android. These files will be placed in the "out\Android\BXXXXXXXXX" folder, where the name is the book's ASIN.
Your book needs to go in the "sdcard/Android/data/com.amazon.kindle/files/" folder on your Android device.
You can then copy the entire BXXXXXXXXX folder to that same spot.
Calibre Plugin
This plugin (plugin-kindlexray-0.0.3.zip) allows Calibre to automatically find and copy the files built by X-Ray Builder to your Kindle when you use the 'send to device' feature.
To install, load the plugin from the zip file from Preferences -> Plugins as per usual.
Once installed, it will show up under 'Device Interface plugins'.
You should disable the original 'Kindle 2/3/4/Touch/etc' plugin to ensure it uses the new one.
Select the KindleXRay plugin and hit 'Customize plugin'. You will need to hit browse and point it to your X-Ray Builder's /out folder so it knows where to look. You can choose whether or not to overwrite existing X-Ray/extras files as well.
The plugin gives no feedback on success, but if all goes well, when you send a book to your Kindle, the files you created in X-Ray Builder will copy over as well.
If not, you can try starting Calibre in debug mode, copy the book to your device, then close Calibre to view the log to check for any exceptions.
Note regarding Kindle firmware < 5.6
If you have a Kindle Paperwhite with firmware version lower than v5.6, you will have to uncheck "Use New X-Ray Format" in the settings page.
The following section is retained for legacy purposes in case anyone actually needs it.
Spoiler:
Chapters:
In many cases, chapters are automatically detected. If chapters were found, they are exported to a .chapters file in the ext folder.
You will be prompted to edit the chapters in Notepad. This allows you to remove any random chapters you may not want included, like copyright pages, acknowledgements, etc. You can also set up 'parts' in case the book is divided into parts/sections that include multiple chapters.
If chapters are not detected, you can build them yourself. You need to open the raw markup and use a text editor that allows you to see the file locations, such as Notepad++.
Chapter format:
Name|start|end
Troubleshooting:
X-Ray file does not load, shows a 2-character code at the bottom of the page:- SX = X-Ray file not valid
- VS/VN/VO = Version number is anything but "1"
- WA = Issue with ASIN
- WG = Issue with GUID (make sure it isn't too long, X-Ray builder will usually warn you)