tchMaterial-parser: a GUI downloader for National Smart Education Platform textbooks

The gap tchMaterial-parser fills between a textbook preview page and a usable PDF

The National Smart Education Platform publishes electronic textbooks as preview pages, one URL per book, for example `https://basic.smartedu.cn/tchMaterial/detail?contentType=assets_document&contentId=XXXXXX&catalogType=tchMaterial&subCatalog=tchMaterial`. The README describes the tool as a downloader for exactly those pages. You paste preview URLs, one per line, and it resolves them to the underlying PDF and saves the file.

The audience is narrow and concrete: teachers, parents and students who want a local copy of a textbook they can open offline, and who are willing to run a desktop application to get it. The README's feature list is written for that person rather than for a developer. Batch input, automatic file naming after the textbook title, and optional PDF bookmarks are the three things that separate this from saving a file out of a browser tab. The project does not host or mirror content. According to the disclaimer, it only provides downloading convenience and all resources come directly from the platform.

How the download actually works, and where the Access Token fits

The tool is a Python application with a graphical interface, packaged from `src/` with a PyInstaller spec file (`tchMaterial-parser.spec`). Dependencies in `pyproject.toml` are small and readable: `requests` for HTTP, `pypdf` for the bookmark step, `pillow`, `psutil`, `sv-ttk` for theming, and `pywin32` only on Windows.

The authentication story is the part worth understanding before you install anything. Since v3.1, the README states that setting an Access Token is no longer required, because the tool falls back to another download method when no token is present. The same note says that fallback method is not effective long term, and still recommends setting a token. So there are two paths: an authenticated one that depends on your own account credentials, and a fallback that the maintainers themselves describe as temporary in nature.

You obtain the token from the platform's own web session. The README's procedure is to log in at the platform, open the browser console, and paste a snippet that reads the `ND_UC_AUTH` key out of `localStorage` and prints a JSON object containing `access_token`, `mac_key` and `diff`. That JSON goes into the tool's "设置 Token" dialog. The README warns that the token expires, generally within about seven days, and that an expired token is the most likely cause of a failed download. It also states the token is never uploaded and is used only for local authorization requests.

Installing tchMaterial-parser and downloading one textbook

There are four documented routes. Prebuilt binaries for Windows, Linux and macOS on x86_64 and Arm64 come from the GitHub Releases page and need no installation step. Windows 10, Windows 11 and Windows Server 2025 users can install through WinGet:

winget install happycola233.tchMaterial-parser

Arch Linux users can install from the AUR, which the README credits to a contributor:

yay -S tchmaterial-parser

On macOS the README warns that the unsigned app is reported as damaged, and gives the command to clear the quarantine attribute before running it. It also suggests moving the app to `/Applications` so the token can persist:

xattr -cr /path/to/tchMaterial-parser.app

Running from source requires Python 3.10 or newer, per `requires-python = ">=3.10"` in `pyproject.toml`; the README points to `CONTRIBUTING.md` for local development rather than repeating the steps.

Once the window is open, paste one or more preview URLs into the text box, one per line. Optionally click "设置 Token" and paste the JSON from the browser console. Then click "下载". The README says files are saved into the directory you select and named after the textbook, and that enabling "设置 PDF 书签" adds bookmarks to each downloaded PDF after the download completes. There is also a search panel that filters resources by name or by a combination of stage, subject and grade.

Where tchMaterial-parser stops being the right tool

The most obvious limit is stated in the README itself: a graphical interface is required. Every supported platform is listed as needing one, so a headless server, a container without a display, or a cron job is out of scope. If your goal is to pull a set of textbooks into a build pipeline, this is the wrong shape of tool and you would be scripting against the platform directly.

The second limit is token lifetime. The README puts a typical Access Token lifetime at about seven days and lists expiry first among the causes of a failed download. That makes the tool a periodic manual task rather than something you configure once. The fallback path exists, but the README's own tip calls it not long-term effective, so treating it as a permanent substitute contradicts the project's advice.

Persistence is uneven. The README documents token storage in the Windows registry under `HKEY_CURRENT_USER\Software\tchMaterial-parser` as the `AccessToken` value, in `~/.config/tchMaterial-parser/data.json` on Linux, and in `~/Library/Application Support/tchMaterial-parser/data.json` on macOS. For other operating systems it states plainly that persistence is not supported and that a general solution is being sought. A BSD or niche desktop user gets a working downloader that forgets the token on every launch.

Finally there is the legal boundary. The disclaimer says downloaded resources remain with the original platform and rights holders, asks that they be used only for personal study and teaching reference, and prohibits commercial use or redistribution. The project also states it has no affiliation with the platform. A tool that automates fetching is not a licence to publish what it fetches.

How tchMaterial-parser compares with an archived PDF collection

The README's own links section names the closest alternative: ChinaTextbook, described there as a project where you can download archived electronic textbook PDFs. The difference in approach is the whole decision. ChinaTextbook is a collection: someone else has already fetched the files, and you download from that archive. tchMaterial-parser is a client: nothing is stored or hosted by the project, and every file is pulled live from the National Smart Education Platform at the moment you ask for it.

That distinction decides which one you want. A live client gives you whatever the platform currently serves, including editions added after any archive was frozen, but it inherits every fragility of the platform: URL formats, authentication, token expiry, and resources that have been removed. The README notes that some older resources may already have been taken down, which is a failure mode an archive does not share. An archive is stable and offline-friendly but only as current as its last update. If you need one specific textbook today and it is still on the platform, the client is the direct route. If you need a predictable set of files that will not change under you, a collection is the better fit.

Maintenance, releases and what the MIT licence does and does not cover

The repository is not archived, and the last push was on 2026-08-18. Releases v4.0, v4.1 and v4.2 all landed in August 2026, so the project is moving, but the maintenance burden it imposes on you is not zero: the token you paste expires, and the fallback path the README describes as not long-term effective can stop working at any time without a new release. Upgrading is cheap when you use WinGet or the AUR, and manual when you use the release binaries, since those are downloaded and run directly.

The code is MIT licensed, and `pyproject.toml` declares `license = "MIT"` with `license-files = ["LICENSE", "licenses/*.txt"]`. MIT covers the tool's source. It does not cover the textbooks, which the disclaimer assigns to the platform and the relevant rights holders, and it does not override the platform's terms of service. The project also bundles Microsoft Fluent Emoji image assets under a separate MIT licence file in `licenses/`, which is why the licence-files glob exists. If you fork this for internal use, the MIT terms travel with the code but say nothing about the content you download with it.

Editorial conclusion

Adopt tchMaterial-parser if you already have a logged-in account on the National Smart Education Platform and you want a batch of 电子课本 PDFs named and bookmarked on a desktop machine; the WinGet and AUR packages make that a short job. Do not adopt it for headless servers, for unattended pipelines, or as a way to redistribute textbook files, because the README describes a GUI-only tool and the disclaimer restricts use to personal study and teaching reference. Before relying on it, verify two things yourself: that a single preview URL downloads end to end on your machine, and where your platform stores the token, since the README lists the Windows registry key, the Linux and macOS JSON files, and states that other operating systems have no persistence at all.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes