View Single Post
Old 09-04-2014, 05:00 PM   #1
Ephemerality ought to be getting tired of karma fortunes by now.Ephemerality ought to be getting tired of karma fortunes by now.Ephemerality ought to be getting tired of karma fortunes by now.Ephemerality ought to be getting tired of karma fortunes by now.Ephemerality ought to be getting tired of karma fortunes by now.Ephemerality ought to be getting tired of karma fortunes by now.Ephemerality ought to be getting tired of karma fortunes by now.Ephemerality ought to be getting tired of karma fortunes by now.Ephemerality ought to be getting tired of karma fortunes by now.Ephemerality ought to be getting tired of karma fortunes by now.Ephemerality ought to be getting tired of karma fortunes by now.
Posts: 313
Karma: 800103
Join Date: Feb 2013
Device: PW1
X-Ray Builder - Windows Application

For those who don't already know, X-Ray is a reference feature available on any Kindle product with a touch screen (Touch, PW, PW2, etc), provided the book has 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.

Unfortunately, Shelfari has shut down so only Goodreads data is used. Options for using Wikipedia as a source may come in the future, but for now terms can be saved to an XML file and edited locally if desired.
It's also worth noting that creating a good X-Ray is not a 1-step process. Goodreads often contains very few characters, aliases usually need to be used to match more locations within the book, and chapters aren't always automatically inserted. This defeats the purpose of the X-Ray a bit but it's better than nothing!

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.

Alias Files:

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.
  • Download aliases - This will attempt to download a pre-built alias file from the internet, if one exists. If overwriting aliases is enabled, downloaded aliases will overwrite ones you have made yourself.

After downloading the terms from Goodreads, 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.


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.

Chapter format:

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++.


Book does not open at all:
  • If you converted your book into 'new' mobi format you may want to try AZW3 instead. If you absolutely want it to be a MOBI and not AZW3, try the 'both' option.
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:
  • You are probably on firmware version 5.6 or higher, you must use the "new format" option when you build your X-Ray file.
Firmware versions <5.6 only:

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)

Thanks to:
  • darrenmcg for completely overhauling the interface and adding many new features
  • shinew for the original X-Ray creation site and source
  • twobob for testing under Linux
  • jhowell for the KFX Input/Output plugins
  • Everyone who has used the program so far, especially those who have reported any errors or suggested new features

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).
Version 2.1.108 and higher includes a connection to the Sentry error management tool which reports on fatal errors in the application. Data sent does not include any PII but you can opt-out by removing the sentry value from the .config file for the app.

Notes on Kindle firmware 5.6+
If you have a Kindle Voyage or Paperwhite with firmware v5.6+, you must select "Use New X-Ray Format" (this is the default now). The "Notable Clips" section will be populated with some quotes from Amazon and up to 20 random excerpts.

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/" folder on your Android device.
You can then copy the entire BXXXXXXXXX folder to that same spot.

Calibre Plugin
This plugin ( 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 itself gives no feedback, 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.
Attached Files
File Type: zip (2.4 KB, 516 views)
File Type: zip (5.26 MB, 134 views)
File Type: zip (5.54 MB, 0 views)

Last edited by Ephemerality; Today at 01:58 PM.
Ephemerality is offline   Reply With Quote