tchMaterial-parser: A Download Tool for China's National Smart Education Platform Textbooks

What Problem This Tool Solves

tchMaterial-parser addresses a specific annoyance: getting a PDF copy of an electronic textbook from the National Smart Education Platform for Primary and Secondary Schools (basic.smartedu.cn). The platform hosts textbooks for browsing, but the README implies that saving them for offline use is not straightforward. This tool parses the preview page URL to find the underlying PDF file and downloads it. It is aimed at teachers, students, and parents who want to read textbooks without a live connection or who want to annotate them in a PDF reader. The tool also batch-processes multiple URLs, so a teacher preparing a semester's materials can queue up several textbooks at once. The developer positions it as a convenience utility, not a content host, and the README explicitly states that all resources come directly from the platform.

How the Parsing and Download Mechanism Works

The core workflow starts with a textbook preview page URL, which looks like `https://basic.smartedu.cn/tchMaterial/detail?contentType=assets_document&contentId=XXXXXX&catalogType=tchMaterial&subCatalog=tchMaterial`. The tool extracts the resource ID from that URL, then requests the actual PDF file from the platform's backend. The README does not reveal the exact API endpoints or the parsing logic, so the internal data flow is not fully documented. What is clear is that the tool can operate in two modes. Without an Access Token, it uses an undocumented method that the README warns is not long-term stable. With an Access Token, it authenticates requests using credentials extracted from the user's browser session. After download, the tool can add PDF bookmarks, presumably by reading the textbook's table of contents and inserting outline entries. The naming is automatic, using the textbook title as the filename. This design means the tool is tightly coupled to the platform's current web structure; any change on the platform side can break the parser.

Installation and First Run: Real Commands

The README offers four installation paths. For Windows 10, 11, or Server 2025, you can run `winget install happycola233.tchMaterial-parser`. Arch Linux users can install from the AUR with `yay -S tchmaterial-parser`. Prebuilt binaries for Windows, Linux, and macOS (both x86_64 and Arm64) are available from the GitHub Releases page, and they need no extra installation steps. For source code, you need Python 3.10 or newer, and the README points to the contributing guide for local development commands. A notable macOS quirk: because the app is unsigned, macOS may report it as damaged. The README instructs you to run `xattr -cr /path/to/tchMaterial-parser.app` to remove the quarantine attribute, and it recommends moving the app to `/Applications` to keep the Access Token persistent. This is a real friction point for macOS users, and it shows that the tool is not a polished, signed application.

Access Token: The Optional but Fragile Authentication Path

Since version 3.1, the tool no longer requires an Access Token. The README says that when no token is set, the tool uses an alternative method to download resources, but it also warns that this method is not reliable in the long term. If you do set a token, you must extract it from your browser after logging into the platform. The README gives a JavaScript snippet to run in the console, which reads a localStorage key starting with `ND_UC_AUTH`, parses the JSON, and prints a credentials object containing `access_token`, `mac_key`, and `diff`. You then paste that JSON into the tool. The token has a validity of about seven days, so you will need to refresh it periodically. The token is stored locally: in the Windows registry under `HKEY_CURRENT_USER\Software\tchMaterial-parser`, in `~/.config/tchMaterial-parser/data.json` on Linux, and in `~/Library/Application Support/tchMaterial-parser/data.json` on macOS. The README insists the token is never uploaded, but it is a credential that can be abused if you share it, so treat it like a password.

Real Limitations and Failure Modes

The most obvious limitation is the token's short lifespan. If you rely on the token method and it expires, downloads fail until you repeat the console extraction. If you rely on the no-token method, the README admits it may stop working at any time because the platform changes. Network instability is another cited cause of failure. The README also notes that some old resources may have been removed, so a valid-looking URL might not resolve. The tool requires a graphical interface; it is not a headless CLI, which limits its use in server environments or automation pipelines. The README does not document any command-line flags or batch scripting interface. Also, the tool is specifically for the Chinese platform, so it is useless outside that context. The macOS signing issue is a minor but persistent annoyance. These failure modes mean you cannot treat the tool as a set-and-forget utility; you must monitor for token expiry and platform changes.

Comparing with ChinaTextbook: A Different Distribution Model

The README's link section points to ChinaTextbook (github.com/TapXWorld/ChinaTextbook), which is a different approach to the same problem. Instead of parsing the live platform, ChinaTextbook archives electronic textbook PDFs and offers them for direct download. That means no token extraction, no parsing logic that can break, and no dependency on the platform's current API. The trade-off is that the archive may be incomplete or outdated, and you are relying on a third party to maintain the copies. tchMaterial-parser gives you the current version straight from the source, but with the operational overhead of tokens and the risk of breakage. If you need a specific edition that is not in the archive, the parser is the better bet. If you want a stable, no-fuss download, the archive is simpler. The two tools are complementary rather than competing, and the README even links to ChinaTextbook as a friendly resource.

Maintenance, Licensing, and Legal Boundaries

The project is under the MIT License, which permits free use and modification, and it also uses Microsoft Fluent Emoji images under their MIT license. The repository is active, with recent releases v4.0, v4.1, and v4.2 in August 2026, suggesting ongoing maintenance. However, the README's disclaimer is important: the tool does not store or distribute content, and all resources are fetched directly from the platform. Copyright remains with the original platform and rights holders. The tool is meant for personal learning and teaching reference, not commercial use or redistribution. The project has no affiliation with the platform. This means you are responsible for complying with the platform's terms of service and local laws. The maintenance cost for you is moderate: you need to update the tool when new releases come out, re-extract tokens every week, and verify that the parsing method still works after platform changes. The MIT license gives you the freedom to fork and patch, but the underlying API instability is something you cannot fix alone.

Editorial conclusion

Adopt tchMaterial-parser if you are a teacher, student, or parent in China who regularly needs offline copies of the official electronic textbooks from basic.smartedu.cn and you are comfortable with a GUI tool that may require manual token extraction. Do not use it if you expect a fully automated, maintenance-free solution, because the no-token method can break and tokens expire roughly every seven days. Before relying on it, verify that the platform's terms of service permit downloading, test a single textbook first, and check the latest release notes for any changes to the parsing method. The tool is useful for personal study and teaching reference, but you must respect copyright and avoid commercial redistribution.

Official sources

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