QUESTIONS, WITH CONTEXT
Clear answers
before you start.
What is Immersive Reader and who is it for?
It is SJT-bright’s local ebook-reading project, intended for reading your own EPUB / TXT with atmospheric backgrounds, annotations, music and reading-habit records. Download the source and run it locally.
Which formats are supported? What about scanned PDF, MOBI or DRM?
Reflowable EPUB, TXT and PDF with a text layer are supported. PDF import extracts text rather than preserving page images and layout. Scans need external OCR first. Fixed-layout or DRM books and MOBI / AZW3 are not supported claims.
How do I run it on Mac, Windows or Linux?
Extract the complete source. On Mac run sh start.sh or start.command; on Windows double-click start.bat, which prefers Node.js and otherwise uses Python; on Linux run python3 scripts/serve.py --port 8940. Keep the service running and open http://127.0.0.1:8940/. A modern Chrome / Edge browser and Node.js or Python are required; npm installation is unnecessary. macOS has been tested. The Windows launcher and library directory are adapted, but have not been run on a Windows computer.
Does no account mean no network activity at all?
The reader has no reader account. Local parsing, your library, built-in tracks and ambient sound do not require an external reading service. Official music embeds and external links need internet and involve their respective services. The public project site provides information and does not accept personal books.
Where do books and notes live? Is there automatic cloud sync?
They live in browser IndexedDB and a local SQLite mirror. macOS uses Library/Application Support/immersive-reader-app/library in the home directory. Windows uses %APPDATA%\immersive-reader-app\library. Linux uses the XDG data directory or ~/.local/share/immersive-reader-app/library. Browser and address changes produce separate caches. Export backups for migration; account-based cross-device cloud sync is not provided.
Can I still select, search and annotate the two-page text?
Yes. The visual book uses DOM text, perspective and paper lighting as a 2.5D approximation; text is not flattened into images. Selection, search, highlighting and source-location navigation remain available.
Does manual navigation stop automatic reading?
In 1.9.3 manual navigation resets the wait and continues. Switching books, returning home, backgrounding the page, Escape or reaching the end pauses it. Refreshing does not start automatic reading by itself.
Can I use my own background and disable weather?
Upload local images or browser-supported videos, which loop muted. Fixed, time-of-day and interval modes are available. Clear weather, disabled effects or the focus preset reduce visual motion, with system reduced-motion settings honored.
What ambient sounds are included and where does the music come from?
Ten modes are synthesized in the browser: rain, snow, waves, wind, stream, fire, insects and three colors of noise. The six music tracks are generated by this project’s script without third-party sampled recordings. You can also import local music.
Will every NetEase or QQ Music song play?
No guarantee is made. Official embeds or opening links are subject to platform availability, track rights and browser behavior. The project provides no membership bypass, audio proxy or unofficial account API. Local playback is independent.
How do progress and reading time differ?
Progress tracks page ranges actually displayed rather than treating a jump to the last page as a completed book. Chapter coverage is visible in the contents. Time records active timed reading for goals, heatmaps and achievements; it does not measure comprehension.
How do backup, migration and note export work?
Export a complete JSON backup with books and media from the shelf panel. Restore by merging or replacing after a pre-restore snapshot. The notes panel separately exports each book’s highlights, comments and bookmarks as Markdown.
What is the license? Can the full rain-glass bundle be used commercially?
Original code is open-sourced under MIT; third-party components retain their licenses. js/rain-shaders.js includes a Heartfelt-derived effect under CC BY-NC-SA 3.0. That non-commercial restriction means the full rain bundle is not entirely OSI-licensed or unrestricted for commercial use. See LICENSE-NOTES.md.
Is this Microsoft Immersive Reader?
No. Its complete identity is SJT-bright/immersive-reader, also named 沉浸阅读器. It is an independent local ebook reader, with no affiliation to Microsoft / Azure Immersive Reader.