Readwyn 0.1.0

Bring your Kindle Vocabulary Builder words to your Mac

The words that a Kindle collects in its Vocabulary Builder come across to your Mac in one Device → Readwyn sync over a USB cable, for each book that is both on the Kindle and in your library. They land in Readwyn’s My Words, each with the book you met it in and the date you first looked it up. The book’s file on the Kindle has to be a MOBI or AZW3 file: words from a book in Amazon’s KFX format stay on the Kindle. Readwyn reads a Kindle only as a drive that the Mac has mounted. Amazon’s help page on USB transfers says the Kindle Scribe and the Kindles released in 2024 need a separate app, such as Amazon’s Send to Kindle, for a cable transfer on a Mac, so Readwyn can’t reach those. Models released before 2024, other than the Scribe, need no such app. If you don’t know which model you have, this is how to find out.

A list the Kindle writes by itself

Amazon’s Kindle Paperwhite User’s Guide (2nd edition) puts it in one line: “Words you look up in the dictionary are automatically added to Vocabulary Builder.” The same guide has the switch for it under All Settings, Reading Options, Language Learning, and says that no word is added while it’s off. A Kobo works the other way round and keeps only the words you choose to save. On a Kindle the list is a record of your lookups, not a selection.

On the Kindle’s drive the whole list is one file, system/vocabulary/vocab.db, an SQLite database. Readwyn opens it with a connection that can’t write. One of Readwyn’s tests runs on a real vocab.db from a Kindle with firmware 5: all 410 words come out with the time of their first lookup, and the database and its folder are unchanged afterwards.

Look a word up again in another book a year later and it still arrives once, under the first book and the first date. Nothing else is read: not the usage example that the Kindle shows with a word, and not whether you’re still learning the word or have mastered it.

Which words come across

A sync covers a word only when its book is both on the Kindle and in your library, the same rule as for Kindle highlights and notes. That takes two matches.

First, Readwyn finds the word’s book among the files on the Kindle: by the unique ID in the header of the file, else by its ASIN, else by its title. A MOBI or an AZW3 file has that header. A book in Amazon’s KFX format, a file whose name ends in .kfx, doesn’t, so a word you looked up in such a book gets no book and stays on the Kindle. Only the book of the first lookup counts. If it’s no longer on the Kindle, the word is left out, even when a later book is still there.

Second, that file has to match a book in your library. Readwyn tries the path it recorded when it sent the book, then the list that calibre leaves on a device, then the title.

Nothing is dropped silently. Under “Left out”, the review names each word that stays behind and gives the reason: “Its book is not on the device.”, or a sentence that names the book and ends “is not in this library.” A word from a KFX book gets the first reason too, although its file is on the Kindle, because Readwyn can’t read that file. In the real database of that test, four words belonged to What If?, the one book that was on the test Kindle. The words of the other 31 books got no book, and in a sync they would all be left out.

Run the sync

Plug the Kindle in and click “Sync” in the sidebar. Connecting only reads the device. For a Kindle with a Vocabulary Builder, the “Device → Readwyn” card says “Bring progress, highlights, notes and My Words from the Kindle into the library.”, and its button counts the changes (“Review 8 changes”). In the review, each new word is a row under its book, marked “Add · Word”. Every change has its own checkbox, so you can untick the progress and the highlights and apply the words alone. A word that My Words already has, in any capitalisation, isn’t added a second time.

Leave “Merge highlights, notes and words instead of replacing them” ticked at the top of the review, as it is by default. With it off, My Words is made to match the Kindle for each synced book: a word that you saved on the Mac from one of those books, and that the Kindle doesn’t have, shows as “Delete · Word”.

The other card is short on such a Kindle: “Nothing goes from the library to this Kindle. The list below tells why.” That list, “Not available on this Kindle”, has the entry “My Words to the device” with the reason “The Vocabulary Builder of the Kindle has no public description of how to add a word.”

On a Kindle with firmware 1 to 4, the list has “My Words” and “Kindle firmware 1 to 4 has no Vocabulary Builder.” Amazon announced the feature as new in September 2013, with that year’s Kindle Paperwhite. By The eBook Reader’s list of the last software version of each model, the Kindles that stopped at software 1 to 4 are the first Kindle, the Kindle 2, the Kindle DX, the Kindle Keyboard, and the basic Kindle of the 4th and 5th generation. Software 5 by itself doesn’t promise the feature. The Kindle Touch of the 4th generation stopped at 5.3.7.3 in that list. The first Kindle Paperwhite, the 5th generation in that list, got the Vocabulary Builder with software 5.4.4, in March 2014, a higher version than the Touch’s last. Whatever the model, a Kindle without system/vocabulary/vocab.db gives a sync no words.

The words on your Mac

Click “Notebook” in the sidebar, then “My Words”. The words are grouped by headword, newest first, each with its book and its date. Readwyn stores no definitions. It looks every word up in the dictionaries on your Mac when it shows the list, in the order you’ve set for them, so the entry you read comes from the Mac’s dictionaries, not the Kindle’s. A word that none of them knows says “No entry in the dictionaries on this Mac.”

My Words in the Notebook: All books with 103 words and four books at the left, and at the right the headword forlorn with its full entry open and the saved words forlornness in Middlemarch and forlorn in Persuasion
My Words in the Notebook: one group for each headword, with the book and the date of each word

Readwyn has no export of words to a file. What it has is “Copy all”, which puts the list on the clipboard as plain text, one block for each headword with its first sense, and under it each of your words with its book:

forlorn — adjective. sad and lonely, as if left behind by everyone.
  forlornness, in Middlemarch
  forlorn, in Persuasion

Searching the list, narrowing it to one book and removing words are covered in Save the words you look up and review them later.