Skip to content

About

Open-source RAZ reader with pronunciation scoring, PDF narration, translation and multi-user progress. 开源 RAZ 分级阅读、英语跟读评分。 Bring your own books.

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

RAZ Reader — Open-source RAZ Reading & Pronunciation Practice

Read RAZ-style graded books. Listen, practice, and track your progress.

Self-hosted graded reading · Personal progress · Offline speech models · Optional Mac acceleration

Live Demo · English · 简体中文

Checks License: Apache-2.0

RAZ Reader is an unofficial, open-source RAZ reading app for English learners. It turns your own PDF books into a graded reading library that works on phones, tablets, and computers. Read a page, listen to its available narration, look up a word, and record yourself for pronunciation feedback. A compact interface keeps the book in focus.

Try it online: raz.aotefan.com — open the hosted reader in your phone, tablet, or desktop browser without installing anything.

This repository contains application source code, not a RAZ book collection. No commercial books, book audio, user recordings, account databases, model weights, production configuration, or API credentials are included. The screenshots below use original example stories and vector artwork generated by this project.

RAZ Reader bookshelf with six original example stories

A closer look

Reading an original example book on a phone
Focus on the page
A compact reading and practice toolbar.
Grade selection in a mobile bottom sheet
Choose a level
A touch-friendly bottom sheet.

These are captures of the running application, not design mockups. The current application UI is primarily Simplified Chinese, for English learners; documentation is available in English and Chinese. Full English UI localization is not yet implemented.

What it does

  • Read your own books. PDF.js renders the original PDF, including text layers and supported embedded audio. Pinch to zoom; resume where you left off.
  • Keep a simple bookshelf. Search, filter by grade or reading status, remember the selected level, and put unfinished books before completed books. Today’s completed-book count uses Beijing time (Asia/Shanghai) on every device; each book counts once per day.
  • Keep readers separate. In HTTPS/cloud mode, use usernames, passwords and nicknames, switch between up to eight remembered accounts, and synchronize each account's progress across devices.
  • Understand a page. Translation and scoring share a page-bound reading reference. OCR checks the body text across multiple passes and searches caption strips when full-page layout detection fails. Uncertain text keeps the recording available without issuing a misleading score. Short article-and-noun captions use ECDICT noun meanings when available.
  • Practice pronunciation. Save the latest recording per page and compare recognized phonemes with the target text. View word-level feedback and expected/heard sounds.
  • Read locally and sync privately. Optionally connect the localhost reader to your own HTTPS deployment: score on the local machine, then synchronize progress, saved recordings and results in the background. The default installation does not connect to any cloud.
  • Use a Mac when available. An optional Mac worker pulls scoring jobs over HTTPS. An unavailable, busy or timed-out worker falls back to the server's scorer.

Narration requires audio already embedded in a book or a verified audio mapping. Having an audiobook does not automatically provide accurate page or sentence timing. Commercial encouragement voice files from the private deployment are omitted; visual rewards still work.

Try the original demo

The demo generates six small, original books locally. One includes locally generated test narration. It does not scan another directory, download books, or contact the author's deployment.

Prerequisites

Python 3.9+ and Poppler, qpdf, FFmpeg. Optional speech/translation environments require Python 3.11. Node is only needed for browser tests, not for serving the app.

macOS (with Homebrew installed):

brew install python@3.11 poppler qpdf ffmpeg tesseract espeak-ng

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install python3 python3-venv poppler-utils qpdf ffmpeg espeak-ng tesseract-ocr tesseract-ocr-eng

Start

git clone https://github.com/aotefan/raz-reader.git
cd raz-reader
./scripts/bootstrap.sh
./scripts/start.sh

Open http://127.0.0.1:8765. Stop with Ctrl+C. To select another port: RAZ_PORT=8875 ./scripts/start.sh.

The default service is local-only and uses one local reading profile. Multi-account login and cross-device synchronization require your own HTTPS/cloud deployment, either opened directly or linked through the optional localhost bridge; see deployment. Microphone access requires localhost or a secure HTTPS context and a supported browser.

Optional language and scoring tools

# Dictionary + English-to-Chinese translation
./scripts/setup_language.sh

# Pronunciation scoring — substantial model/dependency download
./scripts/setup_assessment.sh

Install these only when you need them, then restart the reader. Model installers pin upstream versions/revisions and store downloads in ignored data/ directories. Initial installation needs the internet; normal model inference runs locally. Reading works without these optional models; unavailable tools report that they are not installed.

On a computer, Space starts/stops recording or starts a new take. ← / → change pages even while the feedback dialog is open. The dialog also provides page narration and a compact next-page button. Embedded PDF media widgets are hidden to keep text clear; narration remains in the bottom toolbar. Shortcuts do not intercept typing in input fields.

The scorer uses a CPU phoneme model, not a paid speech API. Long recordings and concurrent requests can be slow on small servers. The UI limits takes to 10–55 seconds according to page length; the engine accepts at most 60 seconds and 120 reference words.

Bring your own library

Organize material you are entitled to use in grade directories:

library/
├── AA.PDF/
│   └── My first book.pdf
├── A.PDF/
│   └── Another story.pdf
└── B.PDF/
    └── ...
python3 scripts/import_library.py --root ./library
./scripts/start.sh

The importer replaces the active book manifest, retains existing private progress, and leaves source PDFs unchanged. It accepts an explicit library directory and does not upload it. Generated manifests contain local paths and must stay private. Restart after changing the manifest.

Standalone narration must have verified content and edition/page mappings; it is never attached by filename alone. The importer does not promise automatic alignment of an entire audio collection. Publishing a reading service is a separate action: only serve material you have permission to make available.

How it works

flowchart LR
    Browser[Phone / tablet / computer] -->|HTTPS| Gateway[Caddy]
    Gateway --> Web[Static web app + PDF.js]
    Gateway --> API[Python API]
    API --> State[Private SQLite state]
    API --> Tools[OCR / dictionary / translation]
    API --> Jobs[Scoring dispatcher]
    Jobs -->|fallback| CPU[Server phoneme model]
    Mac[Optional Mac worker] -->|outbound HTTPS poll + result| Gateway
Loading
Component Implementation
Frontend Native HTML/CSS/JavaScript modules; Mozilla PDF.js
Backend Python standard-library threaded HTTP server
State SQLite for accounts, progress, latest recordings and assessment results
Pronunciation OpenPronounce phoneme APIs + PyTorch CPU; project-specific weighted phoneme-edit score
Language tools Tesseract, Poppler, ECDICT, CTranslate2/SentencePiece, eSpeak NG or macOS system voice
Hosting Same-origin HTTPS reverse proxy; optional Mac worker managed by launchd

Scoring compares the actual recognized sounds against the expected sounds in the page text. It is a practice aid, not a certified pronunciation exam or comprehension score. OCR errors can affect the reference sentence. The 80-point pass threshold and reward stars are presentation rules, not score inflation.

The Mac worker opens no inbound port and requires no shared Wi-Fi or public tunnel. It receives the current recording and reference text, computes a report, and returns it to the server. Recordings and results remain bound to an account and recording version. The server remains necessary for the website and data even when the Mac is online.

Read the architecture, deployment guide, and security boundaries.

Development

python3 -m unittest discover -s tests -p 'test_*.py' -v
npm ci --ignore-scripts
npx playwright install chromium
npm run test:e2e
python3 scripts/audit_public.py

On macOS with Google Chrome already installed, use PW_CHANNEL=chrome npm run test:e2e instead of downloading a browser. The browser suite exercises original books: bookshelf, search, PDF rendering, page persistence, the mobile picker, feedback navigation, recording shortcuts and Beijing-day rollover in three device time zones. The backend suite covers account isolation, audio handling, version guards and scoring failover; many model-bound unit tests use controlled substitutes and do not establish real-world model accuracy.

Directory Purpose
web/ Reader, bookshelf, account center and vendored browser dependencies
engine/ API, private state, audio processing and assessment coordination
scripts/ Demo generation, explicit imports, optional model setup and Mac worker
tests/ Source-only regression tests using temporary/generated data
docs/ Architecture, deployment and reviewed example screenshots
data/, library/, fixtures/generated/ Local-only runtime/material directories; never committed

See CONTRIBUTING.md before submitting screenshots, fixtures, or logs.

Scope and license

This project is a self-hosted web app. See recent changes. An Android package, complete offline-book download manager, on-phone model inference, parent/child account hierarchy, and multi-server high availability are not included. The private deployment's Android shell, operational scripts and production settings were intentionally left out of the public source package.

Original application code and original example text/art are under Apache-2.0. Third-party components retain their own licenses; the repository is not a claim that every dependency is Apache-2.0. See THIRD_PARTY_NOTICES.md and UPSTREAM.json. Optional model weights, dictionaries and external tools have their own terms and are not bundled here.

RAZ Reader is an independent project. It is not affiliated with or endorsed by Learning A–Z, Raz-Kids, or Reading A–Z. No RAZ learning materials are distributed in this repository.

About

Open-source RAZ reader with pronunciation scoring, PDF narration, translation and multi-user progress. 开源 RAZ 分级阅读、英语跟读评分。 Bring your own books.

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages