v0.4.0

New: macOS app

So far, using the Reading Log app is some very passive experience: you read, the Kindle OS records the reading data , then the app parsed and visualized the reading data. The very minimal active part is you highlighting and jotting down some notes here and there while you read. But admittedly, writing / typing / touching on the e-ink screen is such a painful experience that no one really does it for long. Even with a bluetooth keyboard, it's not much better (I know it because I built a whole writing app for Kindle but rarely use it myself).

Personally, I think, reading will never be complete without writing, and the macOS app is built for this purpose (it also serves as an alternative visualization frontend and backup for the recorded data, but they are not the main points): all I want to do with the desktop app is to add (more than one) notes to highlights, or write notes without a highlight (to capture random thoughts on the fly), or write a longer post at the end. The Kindle app is also updated to work with these features. Notes written on the desktop app will be synced back to the Kindle when you mount the Kindle with Macs via USB (should work with both mass storage and MTP).

There's no plan to distribute a compiled version of the mac app (as it's not signed, it will be the pain in the ass for both you and me any way). The best way to get it is to build it from source, the build script should already handle everything (assuming you have Rust properly set up). Run:

./build.sh desktop

and the app will be in /Applications automatically after compiled.

Full Changelog: v0.3.9...v0.4.0

v0.3.9

Fixes/Changes

• fixed #12. now every sleep/wake will be properly (probably) treated as a distinct sitting.
• fixed the "continue" and "restart" on older firmwares (such as 5.12, which lacks the licp calls to do these behavior) which crash the launcher (related to #13 but not exactly). I don't think I will provide more support for pw2 or any firmwares before 5.18, I don't really enjoy doing so.
• fixed a "restart" bug. previously after a restart or a clear, the progress will be stuck at 0% until reaching the previous location.
• changed the book graphs gap breaks style again, now without a floor or median stride, every gap (1 day) will be marked. I want this now because I notice the previous implementation has some psyops on me, that I don't like the explicit multi-days gaps, and in order to avoid them, I can't have a 1 or 2 days breaks, but will have to wait at least 3. An UI having such a psychological effect on me is unexpected and bad.
• changed some UI labels here and there, such as (most notably) "use stats from" now has "Kindle|App" chips instead of "Device|App", and this one defaults to App (because it's more accurate)
• also used this opportunity to tidy up some terminology used throughout the codebase, unifying the variable names under similar concepts etc. nothing really changed visibly for users, but should be easier for coding agents to understand the code.

Full Changelog: v0.3.8...v0.3.9

v0.3.8

So, I practice book polygamy and hop between books every day and I am not going to apologize for it. But it also means sometimes there will be a long break in between for certain books, because what I read depends on the mood of the situation.

And I am going on a mostly internet free 3 weeks vacation (with my Kindle loaded with books, of course), and it will change my usual reading plan (like, I will certainly not read Infinite Jest during my vacation). That will create gaps here and there and I don't want they screw up my book graphs.

So, v0.3.8 adds our favourite data visualization trick "gap breaks" to x-axis:

Before

After

The gap is decided by the floor = max(3, 3 × median stride). If you read every day then a 3 days break will become a gap, if you read a book one day per week then you need a 21 days break to see a gap. But other than reading the holy bible in a sunday school, who will have such reading habit btw?

---

this also means v0.3.8 will be the last update until mid October. There are still bugs here and there, especially for firmware >= 5.19.*, but we don't have enough data to do anything yet. What you can do in the meantime is just read normally (if it doesn't work for you then you are not really losing anything you don't have already), time your reading with a stopwatch, then make a diagnostics dump and post it in an issue.

Full Changelog: v0.3.7...v0.3.8

v0.3.7

Changes/Fixes

The WHERE YOU SAT row changed from scatters to bars, for better visualizing the length of each sitting. It still assumes each sittings to be mostly linearly progressed, so if ones read completely out of order, it can surely break (I can't even imagine how it can happen but I guess it can. I never doubt the diversity of human behavior).

Old data only record the end of each sitting so they will not have a bar by default. Only new sittings from this release will record both the beginning and end and be visualized as a bar/stretch. Unless, you heal your data in the config page, which brings us to a bug fix.

The heal button was actually broken and fixed and broken again multiple times in the last few releases and I hope no one really used it but again, sorry about that. At least in the last release it may double counts some time, and it was always broken for highlights and notes, for those have a habit of removing the finished books from the device (that's me). The most accurate source for finding aligning highlights and notes is the .sdr folder, when it's available, they will be mostly (if not definitely) correct. And if the data were written by the sourcing the .sdr, it should stay that way. That's what it is now after the fix. But it wasn't before, and once we deleted the .sdr folder, it would use the clippings.txt only and resulted in desync of the highights and notes.

I hope it's fixed.

There are other bugs, such as notes written in zh-hans for zh-hant books might have tofu blocks (missing font for some characters). This is because zh-hant fonts might not always include typefaces for zh-hans, but zh-hans always include most of the zh-hant. TIL.

Full Changelog: v0.3.6...v0.3.7

v0.3.6

New and Changes

Read through counts and their graph

So I finally get the book infographics "right", I think. And what was missing was a reread count.

This is the first app only stats that's not in the system logs, so it can only be marked within the app. When we finish reading a book (either by reaching 99.5% of the book or through manually setting it as finished), now you can use the "Restart" button within the app to start the next read through.

Each read through will have their own graphs, the per day and hourly breakdowns and also the progression. The Progression graph introduced in v0.3.3 was terrible, it didn't take into consideration that the reading order can be nonlinear (such as reading a short story collection, you might want to jump around and read in random order), or a book with half of the pages are index or notes, your "progression" might not even reach 100% but likely end at 50~60% and the numbers do not really mean a lot here. I told myself that it was a placeholder awaiting for a better visualization and today we have it (I hope).

Whenever there's a new feature, expect bugs, as I also haven't had my first reread to test it on the real data :)

Sorting

The books list view and also highlights can be sorted by ascending or descending order. It should be obvious how, just look for the up / down carets.

Full Changelog: v0.3.5...v0.3.6

v0.3.5

Gave yet another shot at fixing reading time calculation for 5.19.* logs which uses a different pattern (ref. #10) with limited data and came out fixing also the some deformed logs in other firmware versions in genera and also the fixed-layout books. Estimates for remaining time also got more realistic.

Full Changelog: v0.3.4...v0.3.5

v0.3.4

Changes/Fixes

Reset, Back up and Restore.

Reset was broken due to some changes in v0.3.2, I hope no one used it, otherwise you can't reopen the app again. Now fixed. I also take the opportunity to refactor the backup and restore logic to make it more streamlined:

• If you reset the record, you can choose to backup first or no backup, this is the same as before.
• You can also just make a backup without reseting anything (previously you can't).
• You can restore from a backup, either the one from the same device, or you manually copy it from anther device (previously you can only copy the covers/ folder and sessions.tsv over and it won't handle any merging).

Others

• more stats inconsistencies fixes across pages. I pulled off a 十角館の殺人 level bug and now I am convinced that the trick in the book will work. I am sorry I doubted it before.
• UI/rearranged things here and there in Config.

Full Changelog: v0.3.3...v0.3.4

v0.3.3

New

Book Graphs

Moved the journey histogram to the dedicated graph tab so that the stats tab has more breathing room, then added a per sitting location histogram (which record the location at a sitting's end, for seeing overall progression, but it can be regressed if you jump around the books, it can happen, such as reading a short story collection in random order) and also the clock histogram (same idea as the average day in rhythm trends, but for a book only, so that you can tell easily which books you read during commute and which books you read on bed).

Changes/Fixes

Screen size scaling

Previously different screen sizes got different scaling, for the sake of readability that I can't really verify myself, and it resulted in some uncontrollable UI shifts. So in this release I simply decided to keep the UI consistent for all screen sizes (I hope) and just scale them accordingly (using the Oasis/Colorsoft size as base). Now the UI will likely look too large on Scribes... maybe it will get a dedicated design later, but no promise.

Time Zone again

Added a dedicated lines to the sessions.tsv for recording time zone, so that we can be sure from when to when a time zone shifted and the statistics can be adjusted accordingly. What I don't want see my stats got messed up due to spending a month traveling in a different time zone and then back home seeing I now reads mostly at 3am in the morning :)

That said, there's no way to verify it yet. Tests are done with simulation (although they are really good guess), without any real data recorded on device. The first test will be a month later after I am back from vacation, and the next test is Oct 25 (the end of daylight saving time this year).

Some stats inconsistencies across pages

Here and there are some same stats with a minute difference due to being rounded differently. I hope that now most of them will be the same.

Full Changelog: v0.3.2...v0.3.3

v0.3.2

Changes/Fixes

This release note is gonna be an essay. I just need a place to vent.

How do you count your total reading time, seriously?

In v0.2.6/7, we gained a toggle to switch between the stats from read directly from the device or the ones the app computed itself. The motivation was from #11, which showed the device stats can be seriously undercounted. A "fix" I introduced is to use the difference between the book opened and closed, within an Awake/Sleep window. It turns out to overcount time quite often.

So what we have until now is a toggle for either undercounting or overcounting your reading time.

Thinking about this sent me into a rabbit hole of what should be counted at all, and we need to know what Amazon counts and does not count and why first. It turns out that Amazon has some opinionated (but reasonable) criteria for timekeeping:

First of all, reading speed needs to be within the range of [40, 900] Words per Minute (WPM). Being too fast or too slow, you are not really reading, you are skimming, or you are idling. Both are reasonable, for English, maybe also for German (not really sure about others, but I guess they will be close).

An average proficient English reader reads 250 WPM, 900 is in fact very generous. Infinite Jest has a total word count around 577k, read at 900 WPM, you can finish it in less than 11 hours. The audiobook version takes ~65 hours, which translates into 150 WPM. Reading English or other western languages, you will likely never be undercounted.

But what if you read CJK? I haven't found any recent papers on this topic with definite figures yet (likely not looking hard enough, or they are not published in English...). According to one older paper (Trauzettel-Klosinski, 2012), the speed of reading Japanese and Chinese is actually not much different from other languages if counting by syllables per minute. According to an even older paper (Sun, 1985), the average Chinese reading speed can be ~580 characters per minute (CPM). According to this paper (Miyata, 2012), trained Japanese readers reach 2600 CPM on average, even untrained readers can do 1200 CPM.

Which is equivalent to what WPM, btw? Well, it doesn't really matter. Because your Kindle treats CPM as WPM. What's wrong is the unit. Your Kindle counts every character as a word for CJK. If we give the same generous factor to Chinese and Japanese (900/250=3.6), the upper bound should be at least 2088 for Chinese and 4320 for Japanese. But no, you got 900. The time of every page you read faster than 900 WPM will not be counted at all, so is the word counts, and the WPM will be capped at 900, not your actually WPM, and this will further affect the remaing time estimate for a book.

Having such a bound is actually not a bad idea, I have to admit. At least the lower bound is good to have. If we don't have it, we will definitely overcount (like what I did in v0.2.7). Sometimes reading will be interrupted, maybe you want a tea, or go to the toilet, or just need to pause and think about what you just read, and the Kindle might just stay opened the whole time, and you will not want to count those time in (or do you?). There's no sensor on Kindle for detecting this kind of interruption, and if it had, I probably don't want to use such privacy invasive device...

The point is, having a lower bound is good, having a upper bound is not. For english, roughly 4 mins of idleness will discard the time of that page, for CJK, 7 mins. So again CJK will be overcounted a bit here, but compare to throwing all the time that you read but read too fast, this definitely will happen less often and have less severe effect.

So what we do in this release is to count how much time were discarded due to crossing the upper bound and add them back to the total count, but leave the ones below the lower bound uncounted.

This note is long enough already, but I am not done yet.

There are two more (albeit minor) rules Amazon used to throw away your reading time:

1. The last page of a sitting is not counted. It won't nudge the count a lot for one sitting, but over a longer period time (mine, roughly over 2 months and 100 books and 556 sittings), it can amount to 2.14 hours... I guess the reason is the same as the WPM lower bound, that you will likely not in your normal speed. This is negotiable, but in this release I added it back to the count too.

2. If you ever turn back a page, for whatever reasons, the page that you turned back from will not be counted. That's 1.74 hours of mine. I actually like flipping back and forth. Those are added back too.

Ultimately, the question is what should be counted as reading. Amazon has some opinions, and I have mine, and they might not be the same as yours.

(The end of venting)

P.S. If you ever update to this release, you will need to tap the "Heal" button in the config page to correct some stale data for the last 30 days for the App Stats. Those days the backlogs no longer hold will stay stale forever and be either under- or overcounted.

Others

But still not the end of this release note yet.

There are other improvements but I won't go into much details (this release note is long enough and I don't think anyone will read it):

1. Rewrote the readinglog.log. It grew faster than the sessions.tsv in size, and records a lot of useless info. This release will replace the old one automatically.

2. Some premature performance improvment. Given my own sessions.tsv grow rate, it will start having load time problem in roughly 5 years on a 1GB RAM colorsoft, and will be around 8Mb in size, if I read and highlight a lot. FYI, the last 3 Paperwhite I owned all died within 2 years under 2 hours daily use on average. Colorsoft is just a Paperwhite with a fancier color screen, I doubt it will survive longer than that (but I do hope so). I saw faster load time on Oasis 2 already, but likely because I am not using it much now that I read mostly on the Colorsoft... I do love the form factor of the Oasis and its buttons, but colors really make me happier.

The end, truly.

Full Changelog: v0.3.1...v0.3.2

v0.3.1

New

Two new features: search and setting a minimal length for a sitting.

Search

In hindsight, searching by keywords to match book title or author or highlights or notes is very essential and should be done in the beginning. It's actually easy to be done for English, or other western languages, but figuring out the Input Method for CJK is a pain in the ass. I have tried tackling it in my other projects but without success, until now. Yeah, I've learned a lot in this session and figured out how to invoke the system OS' virtual keyboard and bind it to homebrew X11-based apps.

Now on Books tab or within a book's own page, there will be a search icon at the upper left corner. It should be obvious how to use it.

Sitting floor

Previously, any seconds recorded is counted as a "sitting". So even opening a book and closing it immediately, or skimming it for a few pages and not really reading it, will be counted as a sitting, and will show that book in the Today tab, and bump its recency in the Book tab. I am annoyed by it and think a sitting less than a minutes should not be counted at all. Now you can set what should be counted as a sitting.

Changes/Fixes

Mostly just UI/aesthetics, such as standardizing buttons size, white space adjustment, typesettings for CJK, etc.

Full Changelog: v0.3.0...v0.3.1