DreamReader is a local-first desktop ebook reader for macOS, Linux, and Windows. It combines a full reading experience with offline text-to-speech, expressive narration, local voice management, and incremental M4B audiobook creation.
Books, annotations, generated audio, voices, and model settings stay on the user's computer by default.
- Imports EPUB, PDF, TXT, Markdown, and HTML files through the native file picker.
- Stores imported books in an internal local library and detects duplicates by content hash.
- Extracts EPUB metadata, authors, language, table of contents, reading order, and cover artwork.
- Supports EPUB navigation based on NCX, anchors, nested navigation, and multiple chapters stored in one HTML resource.
- Uses Readium CLI metadata when available and falls back to the built-in importer.
- Extracts readable PDF text with PDF.js and detects chapter boundaries with heuristics or the optional local Qwen prosody model.
- Provides grid and list library views, metadata search, reading status, progress indicators, and book removal.
- Removes associated annotations, generated audio, and audiobook data when a book is deleted.
- Integrated Thorium/Readium publication reader for EPUB content.
- Continuous and paginated reading, including one- or two-column layouts.
- Persistent Readium locators and automatic resume from the last saved position.
- Table-of-contents navigation, previous/next chapter controls, page navigation, overall progress, and chapter progress.
- Reader themes, font family and size, column width, line height, paragraph spacing, margins, alignment, and hyphenation controls.
- Clean reading mode, collapsible/resizable inspector, and return-to-previous-position navigation.
- Inline footnote popups and support for publication images and rich EPUB resources.
- Colored highlights, notes, and favorite passages anchored by paragraph and character offset.
- Annotation filtering, editing, deletion, direct navigation, and Markdown/JSON export.
- English and Brazilian Portuguese interface localization.
- Dedicated Audio Center with per-book audio status and a persistent generation queue.
- Generates audio for an entire book, selected chapters, one chapter, or individual text segments.
- Chapter and segment search, selection, regeneration, deletion, retry, pause, resume, and cancellation controls.
- Persistent TTS jobs and segments that recover after the application restarts.
- Local audio cache with reuse when the same chapter and settings are requested again.
- Built-in chapter playback and generation progress at book, chapter, job, and segment levels.
- Engine, voice, model language, quality, seed, and expressive-narration settings.
- Locked or randomized seeds for reproducible voice generation.
- Automatic cache and M4B invalidation when the engine, voice, prosody, pronunciation dictionary, or generated chapter changes.
- Qwen3-TTS 0.6B, Qwen3-TTS 1.7B Base, Qwen3-TTS 1.7B VoiceDesign, Chatterbox Multilingual, MOSS-TTS-v1.5, and F5-TTS PT-BR engine definitions.
- Supervised local sidecars for Qwen3-TTS MLX, Chatterbox MLX, MOSS-TTS-v1.5 MLX, and F5-TTS PT-BR.
- Standalone local Python runtime setup for sidecars without modifying the system Python installation.
- MLX/MPS support on Apple Silicon, including the native
mlx-audiopath for MOSS-TTS-v1.5, and CUDA or Vulkan setup paths on Windows and Linux. - Local model catalog, readiness diagnostics, storage usage, download/install progress, retries, folder-based installation, and removal.
- Optional Qwen3 4B GGUF prosody model through
node-llama-cpp, with a deterministic local fallback. - Sidecar output validation and Electron main-process supervision.
- Canonical
NarrationPlanpipeline shared by every TTS adapter. - Brazilian Portuguese normalization for abbreviations, dates, times, currency, percentages, and sentence segmentation.
- Structured prosody instructions for emotion, pace, pitch, intensity, pauses, and voice role.
- Persistent segment-level prosody cache.
- Neutral fallback for missing, invalid, or incomplete model output.
- Neutral-versus-expressive audio comparison when both versions are available.
- Per-job metadata for prosody mode, cache hits, generated analyses, and fallbacks.
- Local voice profiles with engine-specific compatibility bindings.
- Voice cloning from authorized reference audio and transcript, with explicit consent required.
- Qwen VoiceDesign prompt-based voice creation with preview before saving.
- Voice preview, rename, export, import, and deletion.
- Imports one or more
DreamReader VoiceZIP packages. - Bundled voice packages are imported automatically on first launch and reconciled when compatible engines are installed.
- Global and per-book pronunciation dictionaries included in the TTS cache key.
- Chatterbox multilingual language selection and optional reference-voice cloning.
- MOSS-TTS-v1.5 Portuguese language tagging, direct synthesis, optional zero-shot voice cloning, and explicit
[pause X.Ys]markers.
- Real AAC/M4B generation through the bundled
ffmpeg-staticbinary. - Incremental partial M4B output as chapters become available.
- Automatic or manual M4B rebuild.
- Save/export and removal controls for generated audiobook files.
- Persistent audiobook manifest and chapter metadata.
- A failed M4B rebuild never invalidates already generated chapter audio.
- Electron sandbox, context isolation, disabled renderer Node integration, and a narrow preload bridge.
- Shared Zod contracts validate IPC requests across renderer/main boundaries.
- PGlite and Drizzle provide the persistent local database.
- Registered assets are exposed through controlled
dreamreader://protocols instead of unrestrictedfile://URLs. - Models, Python runtimes, generated audio, cloned voices, and books remain local unless the user explicitly exports a file.
- No cloud synchronization, online bookstore, social layer, or DRM removal.
Paginated EPUB reader |
Two-column reading and highlights |
Audio Center overview |
Chapter audio generation |
Voice manager |
Engine and model management |
M4B export and generation queue |
Version 0.1.0 bundles are stored in this repository with Git LFS:
| Platform | Architecture | Download |
|---|---|---|
| macOS | Apple Silicon (arm64) |
DreamReader-0.1.0-mac-arm64.dmg |
| Linux | Intel/AMD (x86_64) |
DreamReader-0.1.0-linux-x86_64.AppImage |
| Windows | Intel/AMD (x64) |
DreamReader-0.1.0-win-x64.exe |
Integrity hashes are available in bundles/SHA256SUMS.
These local builds are not code-signed or notarized; macOS Gatekeeper and Windows SmartScreen may display a warning on first launch.
- macOS: Open the DMG and drag DreamReader into Applications. This build requires Apple Silicon. If Gatekeeper blocks the first launch, right-click the app and choose Open, or authorize it under System Settings > Privacy & Security.
- Linux: Run
chmod +x DreamReader-0.1.0-linux-x86_64.AppImage, then launch the AppImage. - Windows: Run
DreamReader-0.1.0-win-x64.exeand follow the NSIS installer.
Every bundle includes the ZIP packages at the root of voices/.
- Git
- A recent Node.js LTS release and npm
- Python 3 for the bundle orchestrator
- Git LFS if you want the prebuilt bundles
- Additional disk space for optional local TTS runtimes and models
git clone https://github.com/mbellezi/dreamreader.git
cd dreamreader
npm run setup:dev
npm run devnpm run setup:dev installs Node dependencies, downloads the Readium CLI for the current platform, prepares the standalone Python runtime and TTS sidecars, and downloads/configures the supported local TTS models.
Preview the setup steps without installing or downloading anything:
npm run setup:dev -- --dry-runnpm ci
npm run download:readium-cli
npm run devnpm run dev starts Electron with automatic recompilation. The minimal setup is enough for the library and reader; local neural TTS requires the full setup or manual engine installation.
The default clone also downloads approximately 2.1 GB of Git LFS bundles. To clone only the source:
GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/mbellezi/dreamreader.git
cd dreamreaderIn PowerShell, set $env:GIT_LFS_SKIP_SMUDGE = "1" before cloning. Run git lfs pull later to download the bundles.
Apple Silicon uses MLX/MPS by default. On Windows and Linux, select CUDA or Vulkan:
npm run setup:python-tts -- --backend=cuda --install-sidecars
npm run setup:python-tts -- --backend=vulkan --install-sidecars
npm run download:tts-models -- --backend=cudanpm run lint
npm test
npm run buildCross-platform packaging is orchestrated by scripts/build-bundle.py. It checks host dependencies, downloads all Readium CLI targets, installs target-specific optional dependencies, rebuilds ffmpeg-static, runs electron-builder, and reports the artifact path and SHA-256 hash.
python3 scripts/build-bundle.py --target linux-appimage
python3 scripts/build-bundle.py --target windows-msi
python3 scripts/build-bundle.py --target mac-dmg
python3 scripts/build-bundle.py --target allHost requirements:
- Linux AppImage builds natively on Linux; macOS and Windows require Docker or WSL2.
- Windows installer builds natively on Windows; Linux and macOS require Wine.
- macOS DMG builds require macOS.
--target allbuilds Linux and Windows targets and also includes macOS when running on a Mac.
Useful examples:
python3 scripts/build-bundle.py --target linux-appimage --arch x64 --linux-runner docker
python3 scripts/build-bundle.py --target linux-appimage --arch arm64 --linux-runner docker
python3 scripts/build-bundle.py --target windows-msi --check-only
python3 scripts/build-bundle.py --target windows-msi --keep-intermediate
python3 scripts/build-bundle.py --target mac-dmg --arch arm64
python3 scripts/build-bundle.py --target mac-dmg --signed-macCross-builds can leave node_modules/ prepared for the target platform. Run npm ci afterward to restore dependencies for the current host. See docs/11-build-bundles.md for Wine, Docker, WSL2, and Wrapped MSI details.
DreamReader imports ZIP archives that follow the DreamReader Voice package format:
- Start the app and open Studio > Voices.
- Choose Import voices.
- Select one or more compatible ZIP packages.
- Install a compatible engine under Studio > Engines to enable preview and generation.
Packages with reference audio create bindings for installed voice-cloning engines. Prompt-based packages become available to Qwen VoiceDesign when that engine is installed.
npm install
npm run setup:dev
npm run dev
npm test
npm run test:tts-models
npm run lint
npm run build
npm run download:readium-cli
npm run setup:python-tts
npm run download:tts-models
npm run db:generate
npm run db:migrateUse --install-sidecars to install Python sidecar dependencies. The CUDA backend uses the official PyTorch CUDA wheel index by default; override it with DREAMREADER_TORCH_CUDA_INDEX_URL.