# ChinaTextbookStudyFree: a free Chinese primary school platform on the web

> ChinaTextbookStudyFree is an MIT licensed web platform that teaches the Chinese primary school curriculum across maths, Chinese, English and science, with AI generated quizzes, text to speech narration and read along practice. The content is large, the progress record lives only in the browser, and the resource download is around 2 GB.

**wuwangzhang1216/ChinaTextbookStudyFree** — 给所有中国小学生打造的免费学习平台，从一年级到六年级所有的课本知识点全汇总。

- Repository: https://github.com/wuwangzhang1216/ChinaTextbookStudyFree
- Website: https://d3nmsqi4n72idj.cloudfront.net/
- Stars: 1,301 · Forks: 362
- Language: TypeScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/wuwangzhang1216-chinatextbookstudyfree

## A free, ad free platform for the Chinese primary curriculum

The project describes itself as a free, open source, purely public interest platform for primary school study, and the reasoning is stated in the README: educational resources in China are unevenly distributed, children in first tier cities can buy workbooks and attend expensive tutoring, while children in remote rural schools may struggle to get a practice book at all. The platform covers the whole primary curriculum in four subjects, Chinese, maths, English and science, sells no courses and shows no advertising, and generates unit quizzes and knowledge explanations with AI, subject to teacher review. A hosted version is available online and works in desktop and mobile browsers with nothing to install. The audience is teachers and families who want supplementary practice rather than a replacement for a teacher.

## Starting the web app from a clone

Running the current main branch locally needs Node.js 20 or later, Python 3.9 or later and FFmpeg built with libmp3lame, with Python and FFmpeg on the system PATH. The clone is straightforward:

```bash
git clone --branch main https://github.com/wuwangzhang1216/ChinaTextbookStudyFree.git
cd ChinaTextbookStudyFree
```

The assets are not in the repository, so they are installed separately with the installer script, which downloads and verifies the release archives:

```bash
# macOS / Linux：在仓库根目录执行
python3 scripts/install-release.py --tag v1.2.0-assets

# Windows PowerShell
py -3 scripts/install-release.py --tag v1.2.0-assets
```

Then the web app itself starts with the workspace scripts:

```bash
npm ci
npm run dev
```

After that the app is served at http://localhost:3000. The first start builds the data and generates the web compatible MP3 audio from the release audio files.

## The resource download is 2.06 GB and lives outside Git

Audio, illustrations, textbook page images and the question bank are distributed through GitHub Releases rather than the Git repository, and the sizes explain why. The installer checks the SHA-256 of five packages before unpacking them, and the release assets are large: audio.tar.gz holds 81,017 original audio files, mostly Opus, at 1.29 GB, unpacked into apps/web/public/audio/. story-images.zip carries 472 images, 284 original and 188 new, at 550.7 MB. textbook-pages.zip adds 1,562 textbook page images plus 20 page number mapping JSON files at 211.6 MB, data.zip holds the front end build data at 4.9 MB and data-source.zip the passages and stories source JSON at 833 KB. The README states the total download is about 2.06 GB and that unpacking, dependencies and the MP3 transcoding need extra disk space on top of that. The old download-assets.sh and .ps1 scripts skip directories that already exist, so they are unsuitable for a resource upgrade.

## Docker and compose put it on 8080 behind nginx

The Docker path is the recommended one for a family deployment, because it pulls the resources and builds without you installing Node.js, Python or FFmpeg:

```bash
docker compose up -d --build
```

The compose file defines a single web service, and the port binding defaults to loopback only, which is a sensible default for a service holding a child's learning record:

```yaml
services:
  web:
    image: china-textbook-study-free:local
    build:
      context: .
      args:
        ASSETS_RELEASE: ${ASSETS_RELEASE:-v1.2.0-assets}
    ports:
      - "${WEB_BIND_ADDRESS:-127.0.0.1}:${WEB_PORT:-8080}:8080"
    restart: unless-stopped
```

The Dockerfile builds on node:22-bookworm-slim with python3, ffmpeg and ca-certificates, runs the same install-release.py during the image build so the asset download is cached across UI changes, then serves the built site from nginx:stable-alpine as the nginx user, exposes port 8080 and has a health check against http://127.0.0.1:8080/healthz every 30 seconds.

## What the learner actually does in the app

The feature list is the product. Unit quizzes follow the textbook chapters, so a child can practise a lesson right after learning it, and there are knowledge explanations for concepts, formulas and common mistakes, though the README admits some courses are still incomplete. Chinese and English texts are read aloud sentence by sentence next to the original textbook page, with shadowing practice, and a recording feature captures audio in the browser for playback without uploading it, which needs HTTPS and microphone permission and has no speech recognition scoring. Each unit carries two AI generated graded stories with comprehension questions and children's illustrations, and everything from questions and options to explanations and story text can be read aloud with text to speech. A first listen gate means the next step only unlocks after the explanation has been played, with the button ring following real playback progress.

## The learning record lives in one browser, with no account

The most consequential design decision is where the data goes. Progress is kept in the current browser: completion, accuracy and reading stars, and the wrong answer book, the daily goal and the weekly report all live there. There is no cloud account and no cross device sync, and clearing browser data destroys the local record. The README is direct about this and about the browser constraints around it: browsers may block the first automatic playback, a small speaker button next to the title restores it, and a read and continue option appears when playback is muted or fails. The parent controls include a daily study time limit and a weekly report, so the design does think about supervision, but only inside one browser profile. For a classroom, that is a constraint worth settling before the first lesson, not after.

## Coverage numbers, review status and the Android client

The coverage table lists which textbook editions are supported: maths and science from grade one to six in the 人教版 and 教科版 editions, Chinese from grade one to six in the 统编版 edition with 188 graded stories, and English in the 人教版 PEP edition from grade three to six with 96 stories. The stated scale is 44 textbooks, 2,166 lessons, 6,545 unit exercises, 779 texts, 284 stories and 1,226 story comprehension questions, 936 in Chinese and 290 in English. The README adds the caveat that this counts resources and does not mean every question has been reviewed by a teacher, which is the sentence to keep in mind when judging the content quality. On the platform side there is also an Android client, opened in Android Studio from apps/android or downloaded as a debug APK from GitHub Actions, which is currently an online client loading the HTTPS classroom, and the iOS screenshots in the README are described as historical assets that were not regenerated in the latest round.

## Conclusion

Adopt this project if you are a teacher, school or parent in China who needs a free, ad free primary school practice tool that works in a browser on a phone or a low end machine, and install it with docker compose up -d --build so the two gigabytes of assets are fetched and transcoded for you. Do not adopt it as a system of record for student progress, because the record lives in the browser with no account and no cross device sync, and do not assume the questions have been vetted, since the README states the coverage figures are not a sign that every item has been reviewed by a teacher. Verify first that the release tag you install, v1.2.0-assets, matches the web build you plan to run, and that the disk space covers both the download and the transcoded MP3 output.

## FAQ

### How do I run ChinaTextbookStudyFree locally?

Clone the main branch, install the assets with python3 scripts/install-release.py --tag v1.2.0-assets, then run npm ci and npm run dev and open http://localhost:3000. You need Node.js 20 or later, Python 3.9 or later and FFmpeg with libmp3lame on the PATH, or you can use docker compose up -d --build instead.

### How much data does the ChinaTextbookStudyFree resource download need?

The README states a total download of about 2.06 GB across five archives, with audio.tar.gz at 1.29 GB, story-images.zip at 550.7 MB and textbook-pages.zip at 211.6 MB, and extra disk space needed for unpacking, dependencies and the MP3 transcoding.

### Does ChinaTextbookStudyFree save progress to the cloud?

No. The learning record, including completion, accuracy and reading stars, is kept in the current browser, and the README states there is no cloud account and no cross device sync. Clearing browser data affects the local learning record.

### Which subjects and textbook editions does ChinaTextbookStudyFree cover?

Maths and science from grade one to six in the 人教版 and 教科版 editions, Chinese from grade one to six in the 统编版 edition, and English in the 人教版 PEP edition from grade three to six. The stated scale is 44 textbooks, 2,166 lessons and 6,545 unit exercises.

### Is the recording feature scored by speech recognition?

No. Recording and playback happen in the browser and the recording is not uploaded, but the README states that there is currently no speech recognition scoring. The feature needs HTTPS and microphone permission.

## Sources

- [License: MIT](https://github.com/wuwangzhang1216/ChinaTextbookStudyFree/blob/main/LICENSE)
- [Project website](https://d3nmsqi4n72idj.cloudfront.net/)
- [README](https://github.com/wuwangzhang1216/ChinaTextbookStudyFree/blob/main/README.md)
- [Releases](https://github.com/wuwangzhang1216/ChinaTextbookStudyFree/releases)
- [wuwangzhang1216/ChinaTextbookStudyFree on GitHub](https://github.com/wuwangzhang1216/ChinaTextbookStudyFree)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wuwangzhang1216-chinatextbookstudyfree