Daffy's Mods
← All buildsApps & tools

Grimmic

The audiobook that reads itself, and a good e-reader too. Grimmic is a Windows desktop app for your ebooks (EPUB, PDF, TXT, Markdown) that works two ways. Read it yourself, like on a Nook or a Kindle: a quiet paged reader with your own font, size, spacing and colours, plus a comic and manga viewer.

  • Updated Oct 4, 2026
  • 3 pictures
  • 10 updates
Grimmic, first picture

Or press play and it reads the book aloud with Kokoro text-to-speech running on your own PC (on the GPU when there is an NVIDIA card), lighting up the sentence being read. Either way it remembers your place to the sentence, and it has a built-in catalog of free Project Gutenberg books. The name is a mimic of a book: feed it text, it speaks.

Status: version 0.3.0 (build 2026.08.20.2), used daily on one Windows 11 PC with an NVIDIA RTX 4070 Ti; Windows only · Visibility: public · Last updated: 2026-10-04

Contents

Screenshots

The Library: Currently Reading and Want to Read shelves of covers, each with how far you have read

The Library on a Windows PC: your shelves of covers in rows, each with how far you have read.

A manga shown two pages at a time, read right to left

The comic viewer showing a manga two pages at a time, read right to left.

The Library scrolled down to the Completed shelf, with rank badges on the covers

Further down the Library: the Completed shelf, with the optional rank badges on the covers.

Features

Library

Discover

Reading and listening

Comics and picture books

Read anything, anywhere

Engine

Requirements

What Version
OS Windows 10 or 11, 64-bit (it uses Win32 APIs for hotkeys, the tray, the window and the single-instance lock)
Python 3.10, 64-bit, with tkinter (the python.org installer includes it). Developed on 3.10.6
Python packages pinned in requirements.txt; the main ones: kokoro-onnx==0.5.0, onnxruntime-gpu==1.23.2, edge-tts==7.2.8, EbookLib==0.20, pypdf==6.14.2, pillow==12.3.0, numpy==2.2.6, sounddevice==0.5.5, lameenc==1.8.4, keyboard==0.13.5, pystray==0.19.5
Not in requirements.txt yet pymupdf==1.28.0 (PDF covers and scanned-PDF comics) and tkinterdnd2==0.6.2 (drag and drop); both optional, but install them
GPU (optional) An NVIDIA card with a recent driver. CUDA 12.9 and cuDNN come as pip wheels (nvidia-*-cu12, a few GB), not a system install
Voice models kokoro-v1.0.onnx (about 310 MB) and voices-v1.0.bin from the kokoro-onnx releases
Disk About 3.5 GB for the GPU venv and models; much less for CPU-only
Internet Only for Discover, the dictionary and the edge-tts fallback. Reading and Kokoro voices work offline

Keep nvidia-cudnn-cu12 at 9.10.x: newer cuDNN releases (9.24) break the convolution graph builder in onnxruntime 1.23.

Install

These steps match the scripts and code in this repo, but they have only ever been run on the author’s own PC, never on a fresh one. Run them in PowerShell.

  1. Install Python 3.10 (64-bit) from https://www.python.org/downloads/windows/. Keep “py launcher” ticked.

  2. Get the code:

    git clone https://github.com/DaffyDabz/grimmic.git
    cd grimmic
  3. Create the virtual environment. It must be called venv and sit in the repo folder, because run.bat, run_debug.bat and Grimmic.spec look for it there:

    py -3.10 -m venv venv
  4. Install the packages (with an NVIDIA GPU):

    .\venv\Scripts\python.exe -m pip install -r requirements.txt
    .\venv\Scripts\python.exe -m pip install pymupdf==1.28.0 tkinterdnd2==0.6.2

    No NVIDIA GPU? Skip the multi-GB CUDA wheels and use the plain CPU build of ONNX Runtime instead (untested, but the engine already falls back to the CPU when CUDA is not there):

    Get-Content requirements.txt | Where-Object { $_ -notmatch '^(nvidia-|onnxruntime-gpu)' } | Set-Content requirements-cpu.txt
    .\venv\Scripts\python.exe -m pip install -r requirements-cpu.txt onnxruntime==1.23.2 pymupdf==1.28.0 tkinterdnd2==0.6.2
  5. Download the Kokoro voice models into a models folder next to main.py (they are not in this repo):

    New-Item -ItemType Directory -Force models
    $ProgressPreference = 'SilentlyContinue'   # makes Invoke-WebRequest much faster
    Invoke-WebRequest https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/kokoro-v1.0.onnx -OutFile models\kokoro-v1.0.onnx
    Invoke-WebRequest https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/voices-v1.0.bin -OutFile models\voices-v1.0.bin

    Without these two files Grimmic still starts, but reads with the online edge-tts voices instead.

Run

Only one Grimmic runs at a time; launching it again brings the open window forward. The first launch takes a few seconds while the voice model loads; the engine in use (CUDA, CPU or edge-tts) is shown at the bottom of the settings panel.

First steps:

  1. On the Library, press Add Book (or drag files onto the window), or open Discover and pick a free classic.
  2. Click a cover to open it. The bottom bar’s mode button switches between Mimic (read aloud) and Grimoire (paged).
  3. Press Space to start reading aloud.
Action Control
Play / pause Space
Seek back / forward 10 s Left / Right (tap twice for 30 s, hold to scrub)
Jump to a sentence Click it
Highlight, note, bookmark, read from here, define, copy Press and hold a sentence, or right-click it
Set the progress marker (bookmark) here Ctrl+B
Search in the book Ctrl+F
Chapter list ☰ on the reader bar
Font, size, spacing, margins, two-page spread Aa on the reader bar
Volume, speed, voice, MP3 export The speaker button on the reader bar
Back to the shelf Esc, or ‹ on the bar
Read the selected text in any app Ctrl+Shift+R
Stop Ctrl+Shift+S

Notes:

Configuration

Everything is set from inside the app (the Library’s gear, the reader’s Aa and speaker buttons). Files, for reference:

Path What it holds
%APPDATA%\Grimmic\settings.json Settings: voice (default af_heart), speed (0.92), volume, theme (midnight, paper, ink, nord), reader_mode (mimic or grimoire), Grimoire font/size/spacing/margin, two_page, word_follow, follow_reading, page_anim, skip_frontmatter, trim_boilerplate, trim_publisher, captions and its size/opacity/position, resume_on_launch, calibre_dir, window position
%APPDATA%\Grimmic\data\library.json Books, shelves, positions, bookmarks, highlights and notes
%APPDATA%\Grimmic\data\library\, covers\ Copies of your books and their covers
%APPDATA%\Grimmic\data\progress\ One small progress file per book, a safety net that is merged back at launch
%APPDATA%\Grimmic\data\downloads\, catalog_* Discover downloads, cover thumbnails and the cached Gutenberg catalog
%APPDATA%\Grimmic\grimmic_debug.log Best-effort diagnostic log
models\ next to main.py (or next to Grimmic.exe) The Kokoro model and voices

Environment variable: AIREADER_DATA moves the whole data folder somewhere else, for example $env:AIREADER_DATA = "$env:TEMP\grimmic-test". The tests use it so they never touch your real library.

Settings files written by an older version are upgraded in place when a default changes.

How it works

Project layout

Path What lives there
main.py Entry point: single instance, data migration, window and tray setup
reader/ The app: UI, engine, player, loaders, text pipeline, library store, catalog, comics, captions
reader/version.py Version and build id, kept in step with the phone app
assets/ The Grimmic icon in every size (grimmic.ico, grimmic_*.png)
tests/ Plain-script tests, one per area, plus small fixture books
tools/make_icon.py An older procedural icon generator (not used for the current icon)
tools/serve_packages.py A tiny HTTP server with byte-range support for baked book packages (see above)
installer/Grimmic.iss Inno Setup script for a Windows installer (written, never built)
Grimmic.spec PyInstaller build of Grimmic.exe
run.bat, run_debug.bat Launchers (no console / with console)
models/ Kokoro model files (you download them; git ignores the folder)

Development

Tests are plain Python scripts, each printing pass or fail. Point them at a throwaway data folder first, because tests\test_core.py does not set one itself and would otherwise read your real settings:

$env:AIREADER_DATA = "$env:TEMP\grimmic-test"
.\venv\Scripts\python.exe tests\make_fixtures.py
.\venv\Scripts\python.exe tests\test_core.py           # parsing, engine, player, export
.\venv\Scripts\python.exe tests\test_store.py          # library storage
.\venv\Scripts\python.exe tests\test_gui.py            # scripted GUI session (plays audio)

There are 27 tests\test_*.py scripts; run the one for the area you touched. tests\drive_hotkey_e2e.py sends real keystrokes to Notepad, so run it only with Grimmic open and nothing else in focus.

Build the Windows app (a PyInstaller “onedir” folder, about 2.8 GB with the CUDA runtime). The models folder must exist first, because the build copies it in:

.\venv\Scripts\python.exe -m pip install pyinstaller==6.21.0
.\venv\Scripts\python.exe -m PyInstaller Grimmic.spec --noconfirm
# result: dist\Grimmic\Grimmic.exe ; add --clean after changing the icon

Optional installer, with Inno Setup 6 (never built so far): ISCC.exe installer\Grimmic.iss.

Releases: there are none; the app is built and used locally. When you bump the build, change reader/version.py here and lib/core/version.dart in grimmic-mobile together; the phone app’s tests check that they match.

Coming soon

Keep this list current: when an item ships, move it to Recent changes with the date, then add what is next.

Recent changes

Credits and license

License: Grimmic’s own code is released under the MIT License. The packages above keep their own licenses. Note that a packaged Grimmic.exe bundles GPL-3.0 (espeak-ng, phonemizer-fork) and AGPL-3.0 (EbookLib, PyMuPDF) components, so anyone handing out a build has to meet those licenses too (offer the source under compatible terms).

More builds

Apps & toolsTrackBoardTrackBoard is a personal "life OS": tasks, projects, habits, school, practice, money and a journal in one web app, drawn in a hand-sketched notebook style.Updated Oct 4, 20263 picturesApps & toolsAuto ClickerA standalone Windows auto clicker in the style of OP Auto Clicker.New1 pictureApps & toolsGrimmic MobileThe phone and tablet version of Grimmic: an e-reader and an audiobook in one.New6 pictures