Bilgames Reader

Turn your DRM-free EPUBs into full-cast audiobooks, on your own PC.

Bilgames Reader reads a book, works out who says each line, gives every character their own voice, performs each line in the right tone, and generates a chapter-by-chapter audiobook you can listen to straight away. Everything happens on your device: after a one-time voice download, no internet connection is needed and nothing from your books ever leaves your computer.

The same introduction with sound, read by the app's own voices, and as a video.

Contents

• Highlights
• Install
• Quick start
• Features
• Keyboard shortcuts
• System requirements
• Privacy
• Your data
• Troubleshooting
• Roadmap
• For developers
• Contributing
• License and credits

Highlights

• A voice for every character. Speakers are found automatically; you can review uncertain lines, add, merge and rename characters, and choose from 28 natural English voices.
• An optional review assistant for powerful PCs: a large language model, running offline on your own machine, that settles uncertain lines, re-reads whole books to fix who speaks, and suggests voices.
• Lines performed in tone. Whispers, shouts, sad or amused lines are read with matching pace, loudness and pauses.
• Listen in seconds, not hours. The first chapter is ready almost immediately, and any chapter plays while it's still being generated.
• A real audiobook file. Export an .m4b with chapters, cover art, title and author for any audiobook player.
• Bookmarks, highlights and notes, across all your books, exportable as Markdown, text or CSV.
• Private and offline. No account, no cloud, no analytics.
• Uses your graphics card when it can, and carries on on the processor when it can't.

Install

1. Download BilgamesReader-win-Setup.exe from the latest release.
2. Run it. It installs for your user account only (no administrator rights needed) and adds a Start menu entry.
3. The installer isn't code-signed yet, so Windows SmartScreen may say "Windows protected your PC". Choose More info → Run anyway. (Signing is on the roadmap.)

Updates are one click: Settings → Check for updates. Automatic checking at start-up is available but off by default. Your library, voices and audio are kept across updates.

Quick start

1. Import a book. Click Import EPUB (or press Ctrl+K to jump to the library) and pick a DRM-free .epub. Project Gutenberg books are a good place to start.
2. Choose what to read. On the Structure tab, decide whether to include front matter, chapter headings, back matter and footnotes.
3. Find speakers. Click Find speakers. The first chapter is done in about a second; the rest of the book follows in the background.
4. Check the cast and voices. On Cast, give characters the voices you like (▶ previews a voice with the character's own line). On Review, confirm the lines the app wasn't sure about.
5. Generate and listen. On Generate, click Generate audio. The first time, the app downloads its voice model (about 156 MB). Press Listen now whenever you like: unfinished chapters play as they're made.

Features

Books and structure

• Imports DRM-free EPUB 2 and EPUB 3 files. DRM-protected books are refused.
• EPUBs are treated as untrusted files: nothing is extracted to disk, sizes are capped, and XML is read without external entities.
• Finds chapters, parts and headings automatically, and separates front matter, the main text and back matter (including Project Gutenberg's header and licence).
• Choose whether to read the front matter, chapter headings ("Chapter 4. The Rabbit Sends in a Little Bill") and back matter.
• Footnotes can be read inline, at the end of each chapter, or skipped.
• Preview extracted text to see exactly what will be read.
• Shows estimated listening time, storage and word count for every book.

Speakers

• Automatic speaker attribution from dialogue tags ("said Alice"), pronouns, alternation in conversations, and action beats.
• Cast tab: every character with their line count, colour and voice, sorted by how much they speak.
  • Add a character the analysis missed, merge names that are the same person, rename (⋯ → Rename…), remove, or keep two characters apart when a merge is suggested.
  • Show lines lists everything a character says, with the context expandable step by step.
• Review tab: a queue of the lines the app wasn't sure about ("Chapter 4 · 5 of 929 · 924 left").
  • Pick the speaker from the suggestions or recent choices, type a new name to add a character on the spot, or skip a line.
  • More context expands the surrounding text up to about a dozen paragraphs either side.
  • Hear it plays the line with the chosen speaker and tone.
• Your corrections are kept when you run Find speakers again: added speakers, merges, renames and confirmed lines all survive.

Review assistant (optional)

For desktops and laptops with plenty of memory, Bilgames Reader can use a large language model, Qwen3.5-35B-A3B, running entirely on your PC through llama.cpp. It's off by default: turn it on in Settings → Review assistant and download it there (22 GB, resumable).

• Ask the assistant on any line in Review. It reads the passage, the cast and the app's current guess, and if the passage isn't enough it asks for more of the surrounding text, up to three times.
• Let the assistant review all goes through every line waiting in Review, a passage at a time, then looks closer at the ones it's still unsure about.
• Read the whole book with the assistant (book page → ⋯) reads the book again with the first analysis as suggestions, correcting who speaks wherever it's sure, then suggests a voice for each main character. Long books take a while; it shows its progress and can be paused and continued.
• You stay in charge. It changes a line only when it's at least as sure as you choose (90%, 80% or 70%); otherwise it leaves its suggestion, with its reason, in Review. It never changes a line you've confirmed, voice suggestions are applied only when you tick them, and every change it makes can be undone from the ⋯ menu.
• Uses your hardware sensibly. It puts as much of the model as fits on the graphics card and keeps the rest in RAM, starts only when it's needed, and frees the memory again after a few idle minutes.

Voices

• 28 English voices (Kokoro-82M): American and British, female and male.
• Voice menus are grouped by gender → nationality; typing searches all voices ("brit fem" finds British female voices).
• Voices already used in the book are marked In use, with who has them.
• ▶ Preview any voice before choosing it.
• Pick the default narrator for new books in Settings → Narration.

Tone

Every dialogue line can carry one of ten tones: whispered, soft, sad, hesitant, amused, excited, urgent, stern, angry or shouting.

• Tones come from the dialogue tag ("she whispered", "he said coldly"), from context (capitals and "!!" for shouting, stammers and trailing ellipses for hesitation, action beats like "glared" or "grinned"), or from you: change any line's tone in Review or a character's line list.
• Each tone is performed with its own pace, loudness and pauses.

Generating audio

• Quality: Fast, Balanced (recommended) or High quality, per book.
• Graphics card or processor: with Prefer the GPU on, generation uses your DirectX 12 graphics card when it has free memory, moves to the processor if memory runs short, and moves back when it frees up, without stopping. If the GPU is too full, the app shows which apps are using its memory.
• Listen while it generates: any chapter plays immediately; the one you're listening to is made first.
• Only what changed is redone: fixing a speaker or a voice regenerates just the affected lines.
• Resumes where it left off if the app closes.
• Battery-aware: slows down on battery or with energy saver on, to keep the device cool.

Listening

• Live transcript that follows the reading; tap any line to jump there.
• Now speaking shows who is talking, with a Fix button to correct the speaker on the spot.
• Speed from 0.8× to 2×, skip back 15 s and forward 30 s, chapter list, and a sleep timer (15, 30, 45 or 60 minutes, or the end of the chapter).
• Works with Windows media controls: keyboard media keys, the Windows media overlay and lock screen, and Bluetooth headphones, with the book's title, chapter and cover.
• Remembers where you were in every book, anchored to the words, so it lands on the same sentence even after the audio is regenerated.

Bookmarks, highlights and notes

• B bookmarks the moment you're hearing; H highlights the line being read.
• Select text in the transcript to highlight it in one of four colours, add a note, or copy it.
• The bookmarks panel lists everything in the book; play from any item, edit notes, or delete.
• The Notes page gathers bookmarks, highlights and notes from all your books, with search, filters and sorting.
• Export as Markdown, plain text or CSV, for one book or everything.

Exporting audiobooks

• Export saves the book as an .m4b audiobook with:
  • a chapter list that Apple Books, iOS and most audiobook players show;
  • the cover art, title, author and genre.
• A progress bar shows how far along it is, and you can stop at any time.
• Export the chapters that are ready now, or wait until the whole book is done.

Library, backup and moving books

• Search books and characters (Ctrl+K); Continue listening picks up where you left off.
• Delete just a book's audio (to save space, keeping speakers and voices) or the whole book.
• Back up your library to one file (Settings → Backup), with or without audio, and restore it on this or another PC. Restoring never leaves a half-written book, and your current edits are saved first.
• Book files: export a single book as a .bilgames file (book page → ⋯ → Export book file…) and import it on another PC with Import. Audio that still matches is reused.

Storage

• Keep finished audio: all chapters (default), recent chapters (the one you're on, one before and three ahead), or until listened. Removed chapters are made again when you reach them; an export makes them first.
• Keep segment cache lets a speaker fix regenerate only the changed lines (about 170 MB per hour of audio); turn it off or clear it to save space.
• Settings shows how much space voice models and audio use, and opens the data folder.

Appearance and accessibility

• Light, dark, or same as Windows, switching instantly. Windows contrast themes are followed automatically with the system's own colours.

• Reading text size for all book text, on top of Windows' own text size setting.

• Adapts from phone-width to full-screen windows: bottom navigation when narrow, a side rail at tablet width, and a three-pane layout on wide screens.

  

• Full keyboard support and screen reader labels throughout.

Reliability

• Every save is atomic, and edits made while generating can't overwrite each other.
• Updates that change how your library is stored back it up first, then upgrade it.
• A damaged file is copied aside and reported, never silently lost.
• Diagnostics go to a small local log, which never includes book text.

Keyboard shortcuts

Key	Action
Space	Play / pause
← / →	Back 15 seconds / forward 30 seconds
[ / ]	Slower / faster
B	Bookmark this moment
H	Highlight the line being read
Ctrl+K	Search the library
Media keys	Play/pause, next and previous chapter (previous first restarts the chapter)

System requirements

	Minimum	Recommended
Windows	Windows 10 version 1809 (64-bit)	Windows 11
Processor	Any 64-bit x64 CPU	4 cores or more
Graphics	Not required	DirectX 12 GPU with about 1.5 GB of free video memory
Disk	About 500 MB for the app and standard voice model	Plus about 30 MB per hour of finished audio (and about 170 MB per hour while the segment cache is on)
Internet	Only to download the app, its voice model (156 MB, or 310 MB for High quality) and updates
Review assistant (optional)	About 26 GB of memory in all (RAM plus graphics memory) and 23 GB of disk	32 GB+ RAM and a graphics card with 8 GB+

Generation is much faster on a GPU, but every feature works on the processor alone. The review assistant also works without a graphics card, only more slowly; on a laptop with a 6 GB card it takes about two and a half minutes per passage of a book.

Privacy

• Books, their text, speaker analysis, voices, audio, bookmarks and listening history stay on your device.
• The app goes online only when you click something that needs it: downloading a voice model or the review assistant, checking for or installing an update (or if you turn on update checks at start-up).
• The review assistant runs on your PC. Its server listens only on this computer, with a key made for each session, so nothing else (not even a web page) can use it.
• No accounts, analytics, telemetry or crash reports.
• Only import books you're entitled to use; DRM-protected EPUBs are refused.

Your data

Everything lives in %LOCALAPPDATA%\BilgamesReader:

library.json            library format version
settings.json           your settings
books/{id}/             one folder per book: the original EPUB, text, analysis, cast,
                        bookmarks and highlights, finished audio and the segment cache
backups/                automatic backups taken before a format upgrade or a restore
models/                 voice models
assistant/              the review assistant's model and llama.cpp (if downloaded)
logs/app.log            diagnostics (no book text)

Uninstalling removes the voice models, the review assistant, caches and logs but keeps your library, so reinstalling picks up where you left off. Delete the folder above to remove everything.

Troubleshooting

Windows says "Windows protected your PC"

The installer isn't code-signed yet. Choose More info → Run anyway.

It says "Processing on CPU" although I have a graphics card

Generation moves to the processor when the GPU doesn't have enough free memory, and moves back when it does. The Generate tab and Settings → Processing list the apps using your GPU's memory; closing a game or another GPU-heavy app usually helps. Check that Prefer the GPU is on in Settings → Processing.

"This book is DRM-protected"

Bilgames Reader can only read DRM-free EPUBs. Many stores sell DRM-free books, and Project Gutenberg has tens of thousands of free ones.

A line is read by the wrong character

Press Fix while it's playing, use the Review tab, or reassign it from the character's lines on the Cast tab. Only the changed lines are regenerated. Merging duplicate characters (for example "Bingley" and "Mr. Bingley") fixes many lines at once.

My exported audiobook has no chapters

Make sure you're on version 0.5.2 or later; earlier versions wrote chapters in an older format that most players ignore. Export the book again after updating.

The review assistant is slow, or says the model didn't fit

The model needs about 26 GB of memory between RAM and the graphics card. Close other large programs (games, browsers with many tabs) and avoid generating audio at the same time. It keeps going on the processor if there's no suitable graphics card, but much more slowly. Its server log is logs\assistant-server.log.

Where are the logs?

%LOCALAPPDATA%\BilgamesReader\logs\app.log. They never contain book text, so they're safe to attach to a bug report.

Roadmap

Planned work, roughly in order. Nothing here is available yet.

Toward 1.0 (Windows)

• Signed installer, so Windows no longer warns about an unknown publisher.
• File associations: double-click an .epub or .bilgames file to open it in Bilgames Reader.
• Better speaker detection: characters introduced only by description ("the March Hare", "the captain"), nicknames in address ("…, Lizzy"), and speaker labels in plays ("ROMEO.").
• Fewer lines to review, by linking names such as "Bingley" and "Mr. Bingley" automatically.

After 1.0

• Bilgames Reader for Apple devices: one app for iPhone, iPad and Mac that opens the same library and .bilgames book files, starts playing within seconds with a fast voice, and generates the rest in the background.
• Syncing listening positions, bookmarks and notes between devices.
• Expressive voices (on hold): an optional, slower engine with genuine emotional delivery, under evaluation.

Known limitations today: English only; plays and poetry are read by the narrator; the installer is unsigned.

For developers

Build and run

Requires the .NET 10 SDK (pinned in global.json) on Windows 10 1809 or later.

dotnet test tests/Bilgames.Core.Tests
dotnet build src/Bilgames.App -p:Platform=x64
src/Bilgames.App/bin/x64/Debug/net10.0-windows10.0.19041.0/win-x64/BilgamesReader.exe

Set BILGAMES_DATA to another folder to run against a scratch library without touching your own. .epub and .bilgames paths passed on the command line are imported (a second launch hands them to the running window).

Project layout

Path	What it is
src/Bilgames.Core	Platform-free engine (plain net10.0): EPUB import, chapter detection, speaker and tone analysis, synthesis planning, the generation job, chapter streaming, audio retention, storage, format migrations, backups and M4B writing.
src/Bilgames.Tts.Kokoro	Kokoro-82M text-to-speech on ONNX Runtime with DirectML (via KokoroSharp), GPU memory monitoring, and the model downloader.
src/Bilgames.Assist.Llama	The review assistant's runtime: downloads and verifies the model and llama.cpp, runs llama-server as a child process (local-only, per-session key, ended with the app), and talks to it with JSON-schema-constrained requests.
src/Bilgames.App	WinUI 3 app (Windows App SDK 1.8): adaptive layout, player, settings, updates (Velopack).
tests/Bilgames.Core.Tests	xUnit tests, including golden-file conformance tests.
tests/corpus	Public-domain Project Gutenberg books used by the tests.
tools/Bilgames.Inspect	Developer command-line tool (below).
build/release.ps1	Builds, tests, packages and publishes the installer.
design/	Design handoff: tokens, product spec and screen prototypes.

How it works

flowchart LR
    A[EPUB] --> B[Import<br/>chapters, blocks,<br/>footnotes]
    B --> C[Analysis<br/>speakers, tones]
    C --> D[Cast & Review<br/>your corrections]
    D --> E[Planner<br/>segments, voices,<br/>speed, gain, pauses]
    E --> F[Kokoro TTS<br/>GPU or CPU]
    F --> G[Chapter audio<br/>AAC + timings]
    G --> H[Player<br/>live transcript]
    G --> I[M4B export]

Loading

• Plans are content-addressed. Every segment is hashed from its model, voice, speed and text, so only segments whose inputs change are re-synthesized; a chapter whose plan hash changes is reassembled from cached segments.
• Listening while generating packs finished segments into small chunks on the same timeline as the final chapter (ChapterStream), so the player can switch to the finished file without a jump.
• The GPU path rewrites Kokoro's depthwise ConvTranspose layers for DirectML on first use (ModelPatcher, numerically equivalent) and runs at full precision; any GPU error or memory shortage falls back to the CPU segment by segment.
• The review assistant (Core/Assist) is engine-independent: ReviewAssistant talks to any IChatModel, every request carries a JSON schema that only allows real cast ids, and BookService.ApplyAssistant applies answers by confidence and logs each change for undo (books/{id}/assistant.json). Voices are matched by VoiceCaster from the model's descriptions of each character, not chosen by the model directly.
• Text anchors: positions and bookmarks are stored as a line plus a fraction through it (TextAnchors); seconds are only a cache.
• Voices come from the engine (ITtsEngine.Voices); a saved voice another engine lacks is played by the closest one (VoiceResolver). Voice IDs never change because they're part of every segment hash.

Data format and compatibility

• library.json holds a format version. Changes go through a migration in LibraryFormat, which backs up every edit first (backups/pre-upgrade-*.zip). Format 2 (0.5.0) added text anchors.
• Fields written by a newer version survive a save ([JsonExtensionData]); unknown enum values read as defaults (LenientEnumConverter); damaged files are copied aside (*.unreadable-*).
• Backups and .bilgames book files share one zip format (LibraryBackup), and restoring treats them as untrusted.
• This format will be shared with the planned Apple app, so changes must stay backward-compatible.

Tests

dotnet test tests/Bilgames.Core.Tests

The golden-file tests import the four books in tests/corpus/, analyse and plan them, and compare the structure, cast, per-line analysis, per-segment plan and hashes with tests/Bilgames.Core.Tests/Golden/, under three cultures (the machine's, de-DE and tr-TR). They are the conformance spec for any port of the engine. After an intended change, regenerate and review the diff:

$env:BILGAMES_UPDATE_GOLDEN = "1"; dotnet test tests/Bilgames.Core.Tests --filter GoldenFile
Remove-Item Env:BILGAMES_UPDATE_GOLDEN

A changed segment hash means users' audio for that text is regenerated, so treat it as a breaking change.

Developer tool

dotnet run --project tools/Bilgames.Inspect -- book.epub structure      # chapters and their kinds
dotnet run --project tools/Bilgames.Inspect -- book.epub text 5         # extracted text of chapter 5
dotnet run --project tools/Bilgames.Inspect -- book.epub analyze 5      # speakers and lines
dotnet run --project tools/Bilgames.Inspect -- x m4b book.m4b           # chapters in an exported file
dotnet run --project tools/Bilgames.Inspect -- x gpu                    # apps using GPU memory
dotnet run --project tools/Bilgames.Inspect -- x phonemes "text"        # what the speech front end hears
dotnet run --project tools/Bilgames.Inspect -- x tokens "text" bm_george --out t.json  # Kokoro inputs as JSON

Releasing

./build/release.ps1 -Version 0.5.2            # build artifacts/releases/BilgamesReader-win-Setup.exe
./build/release.ps1 -Version 0.5.2 -Publish   # also publish a GitHub release (uses `gh auth token`)

Bump <Version> in Directory.Build.props with each release. Installed copies update from this repository's GitHub Releases via Velopack, with small delta updates.

Contributing

Bug reports and ideas are welcome as GitHub issues. Please include your Windows version, whether generation runs on the GPU or CPU, and the relevant part of logs\app.log.

• Never commit copyrighted books. Only public-domain Project Gutenberg EPUBs belong in tests/corpus/; .gitignore blocks every other .epub.
• Keep Bilgames.Core free of Windows dependencies and deterministic: culture-invariant formatting, no GUIDs or timestamps in anything hashed.
• Run the tests before opening a pull request, and regenerate golden files only for intended changes.

By contributing, you agree that your contributions are licensed under the MIT License.

License and credits

Bilgames Reader is open source under the MIT License: you're free to use, copy, modify and distribute it, provided the copyright and license notice are kept.

The MIT License covers Bilgames Reader's own code and documentation. Components it uses keep their own licenses: the voice model, libraries and fonts below (all permissive: MIT, Apache-2.0, BSD-3-Clause, the SIL Open Font License, or Microsoft's redistributable runtime terms), and the public-domain test books in tests/corpus/, which also carry Project Gutenberg's terms.

Bilgames Reader is built on:

• Kokoro-82M voice model and voices (Apache-2.0)
• KokoroSharp (MIT) and MisakiSharp (Apache-2.0)
• ONNX Runtime with DirectML (MIT)
• Windows App SDK / WinUI 3, .NET, CommunityToolkit.Mvvm, Velopack and AngleSharp (MIT)
• Manrope and Literata fonts (SIL Open Font License)

The full list is in THIRD-PARTY-NOTICES.txt, which the app also opens from Settings → Privacy. The screenshots show public-domain books from Project Gutenberg. The product spec is in ReadMe.html and the design handoff in design/README.md.