nnnotes 0.1.3__tar.gz → 0.2.0__tar.gz

nnnotes-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+nnnotes.toml
+*.local.toml
+.env
+out/
+cache/

nnnotes-0.2.0/CHANGELOG.md

@@ -0,0 +1,191 @@
+# Changelog
+
+All notable changes to this project are listed here. Versions follow [Semantic Versioning](https://semver.org/).
+
+## [0.2.0](https://github.com/MetaSekaiLab/nnnotes/compare/v0.1.4...v0.2.0) - 2026-10-13
+
+### Features
+
+- **music-data:** Reuse cached chart statistics of unchanged model sources ([1bdbd64](https://github.com/MetaSekaiLab/nnnotes/commit/1bdbd640755e4f49e0ab302c74c1ed871aef7f70))
+- **music-data:** Measure chart statistics with nominal lottery and skill probabilities ([303b850](https://github.com/MetaSekaiLab/nnnotes/commit/303b8503621180a016c41c574a41864ac67f7b1f))
+- **fonts:** Read the game font settings from a built-in table in open-font exports ([dfe3c86](https://github.com/MetaSekaiLab/nnnotes/commit/dfe3c86524ef193361eee751983d8d3b60dddecd))
+- **music-data:** Keep native simulation programs and export Snap labels ([096361a](https://github.com/MetaSekaiLab/nnnotes/commit/096361a5f0f585aa5ee332c5d4997958f3064254))
+- **schemas:** Ship the JSON Schemas with the package as nnnotes.schemas ([7b66c09](https://github.com/MetaSekaiLab/nnnotes/commit/7b66c0923ad7c581ba7cf4ff7318f54bc9c80fb1))
+
+### Documentation
+
+- Describe the atoms and the PNG level without measurements ([babe470](https://github.com/MetaSekaiLab/nnnotes/commit/babe4706bb862bb7235b25d6bde1c5e7dec72dc1))
+
+### Build
+
+- **deck:** Ournotes-deck v0.0.3 ([c71e8f5](https://github.com/MetaSekaiLab/nnnotes/commit/c71e8f55b2713b9f394f27867f682cc8aecbaffe))
+- **deck:** Ournotes-deck v0.0.4 ([6139e40](https://github.com/MetaSekaiLab/nnnotes/commit/6139e40c189f653e53180f39a3137a1327085e7d))
+- **deck:** Ournotes-deck v0.0.5 ([7f2c950](https://github.com/MetaSekaiLab/nnnotes/commit/7f2c950d4c6008a91be2cbe32f409dc5cddbff82))
+- **deck:** Ournotes-deck v0.0.6 ([a4b9c4e](https://github.com/MetaSekaiLab/nnnotes/commit/a4b9c4ea7c03ce569155ed389a0a2df744b5b849))
+- Ship nnnotes as a pure Python package with the deck model as the extra deck ([5c1e9c6](https://github.com/MetaSekaiLab/nnnotes/commit/5c1e9c6613234418c5b7ece2b2750708f6633d1c))
+
+### CI
+
+- **release:** Verify wheels and reuse quality checks ([46cf165](https://github.com/MetaSekaiLab/nnnotes/commit/46cf165d28a4d3dfb44e232c7831a47acb3ba184))
+
+### Miscellaneous
+
+- **rust:** Order chartstats imports ([12672e8](https://github.com/MetaSekaiLab/nnnotes/commit/12672e891ca1c06df6d838681325edc9694fe45e))
+
+## [0.1.4](https://github.com/MetaSekaiLab/nnnotes/compare/v0.1.3...v0.1.4) - 2026-10-06
+
+### Features
+
+- **deck-data:** Export character rank experience thresholds ([3abe101](https://github.com/MetaSekaiLab/nnnotes/commit/3abe1017e47d267f77822af949500789c1831ee4))
+- **music-data:** Publish the recommendation engine in the replay manifest ([42098d7](https://github.com/MetaSekaiLab/nnnotes/commit/42098d7bfa538912bbc350beaebfe78f3b04f202))
+- **catalogs:** Record the resource version of an imported catalog ([a9d0bbd](https://github.com/MetaSekaiLab/nnnotes/commit/a9d0bbd034aee00c696979eba3b1f33754b8a237))
+- **music-data:** Take the deck model's WASM release packages as engines ([de34ee2](https://github.com/MetaSekaiLab/nnnotes/commit/de34ee28ec181cac16237aa2751ff38e3bccfd91))
+
+### Bug fixes
+
+- **deck-data:** Export represented VIP rank identities ([c5d0514](https://github.com/MetaSekaiLab/nnnotes/commit/c5d051454f90c2afc7fb0063485f7dcf5d5a7669))
+- **music-data:** Name the mismatch when an engine package is rejected ([e7fdacd](https://github.com/MetaSekaiLab/nnnotes/commit/e7fdacdd34b80fdf391614f08fd5d7480d33904e))
+
+### Documentation
+
+- Add a changelog generated by git-cliff ([d601820](https://github.com/MetaSekaiLab/nnnotes/commit/d60182018911d3f1fc236d355185592b2b6ec8ad))
+
+### Build
+
+- **deck:** Build the deck model from the ournotes-sim crate ([946fb33](https://github.com/MetaSekaiLab/nnnotes/commit/946fb335aef234837c461dfa960f3ce28dc946da))
+- **deck:** Ournotes-deck ddf212b601731f9ab74245119d4408d2746a370c ([9f0ba0e](https://github.com/MetaSekaiLab/nnnotes/commit/9f0ba0e234cc4119682b3be4ebcd85344e618b02))
+- **deck:** Ournotes-deck v0.0.2 ([8a088f4](https://github.com/MetaSekaiLab/nnnotes/commit/8a088f4b7e40a79b3bc111e88c25d0abce397f36))
+
+### CI
+
+- **commitlint:** Lift the line length limit of bodies and footers ([b9eecd9](https://github.com/MetaSekaiLab/nnnotes/commit/b9eecd91c682011748a3877e311d6ddcfb88000b))
+- Test on Python 3.14 ([5c845eb](https://github.com/MetaSekaiLab/nnnotes/commit/5c845eb365fcc23c36bf724f336ed747ba198057))
+- **deck:** Move create-pull-request to v8, which runs on Node.js 24 ([1e1bb17](https://github.com/MetaSekaiLab/nnnotes/commit/1e1bb179f98dddecb72465949276cbc4fb4e8fd7))
+- **deck:** Dispatch CI and the commit message check on the pin pull request ([3a6bdfc](https://github.com/MetaSekaiLab/nnnotes/commit/3a6bdfc95dd80171724ac313e2aeb5278859a843))
+
+## [0.1.3](https://github.com/MetaSekaiLab/nnnotes/compare/v0.1.2...v0.1.3) - 2026-09-30
+
+### Features
+
+- **songs:** Export every song's metadata and chart facts ([3dae671](https://github.com/MetaSekaiLab/nnnotes/commit/3dae671302ca843c2ce573802e1309b4b85893a2))
+- [**breaking**] One music-data command with the deck model built in ([197b436](https://github.com/MetaSekaiLab/nnnotes/commit/197b436dfccbefa5296fd40fcf5167458ab1406e))
+- **music-data:** Play scenarios: Gekisou off, every rank, the Perfect play ([a03591e](https://github.com/MetaSekaiLab/nnnotes/commit/a03591e7fd4f186df7ddbe161c787c7cad138b41))
+- **music-data:** Read decoded master data with its manifest (--decoded-master) ([12df2a6](https://github.com/MetaSekaiLab/nnnotes/commit/12df2a67b71ade5e41b51e6602d97d6b5733bd99))
+- **jp:** Support Japanese release assets and split APKs ([9bd4452](https://github.com/MetaSekaiLab/nnnotes/commit/9bd4452b262b349cf4ae7b20b4110f532f2ba8d4))
+- **music-data:** The Gekisou catalog, range luck points and the seed set check ([ffaa1bc](https://github.com/MetaSekaiLab/nnnotes/commit/ffaa1bc10eecc2269ffcffb5fa952e166dc1053f))
+- **music-data:** Export and validate single-skill Gekisou aptitude ([35ae7a0](https://github.com/MetaSekaiLab/nnnotes/commit/35ae7a0727934f9f12a8a0b1b650b3a42c6f9a5f))
+- Export versioned Rust replay data with chart statistics ([46b5b09](https://github.com/MetaSekaiLab/nnnotes/commit/46b5b09c7356c27874ee01c610dc295f60b48765))
+- **ui:** Export offline serialized prefab libraries ([0a7344d](https://github.com/MetaSekaiLab/nnnotes/commit/0a7344d09dbeddde36237b8bf63e83bee2159885))
+
+### Bug fixes
+
+- **jp:** Address review regressions ([5f40d3e](https://github.com/MetaSekaiLab/nnnotes/commit/5f40d3ee2b195b802a97bf4a861e3f64d223d1f6))
+- **catalog:** Select international catalogs by resource version ([15cb3bf](https://github.com/MetaSekaiLab/nnnotes/commit/15cb3bfe079282f2624c5a0eeba757566c7eb5f6))
+- **release:** Preflight wheels and preserve reviewed notes ([b1e12c4](https://github.com/MetaSekaiLab/nnnotes/commit/b1e12c4ab31cfed6cd453e562aeeb66c3821af83))
+
+### Build
+
+- **deck:** Pin the final Gekisou aptitude implementation ([4881a21](https://github.com/MetaSekaiLab/nnnotes/commit/4881a2183a1d1cef9ecc799f0bf293dbc58469d7))
+
+### CI
+
+- Move the GitHub Actions to their current majors ([f0038c1](https://github.com/MetaSekaiLab/nnnotes/commit/f0038c15887b2ad8b61ddde320560837dbab1b5f))
+- Run commitlint on Node.js 24, the active LTS ([48b6557](https://github.com/MetaSekaiLab/nnnotes/commit/48b6557490f638f2b37b73dabb8fa175f0cce788))
+
+## [0.1.2](https://github.com/MetaSekaiLab/nnnotes/compare/v0.1.1...v0.1.2) - 2026-09-28
+
+### Bug fixes
+
+- **unity:** Treat a MonoBehaviour with a missing script as classless ([83dd161](https://github.com/MetaSekaiLab/nnnotes/commit/83dd161e7a2af6953e97c56548341ab6839def0c))
+- **room:** Write a valid glTF for a room without geometry ([8465dd5](https://github.com/MetaSekaiLab/nnnotes/commit/8465dd5d89d3a1857d4dcb80b9f5ff8a36895473))
+- **story:** Share a models directory between concurrent story runs ([2051001](https://github.com/MetaSekaiLab/nnnotes/commit/2051001924ecdbb39d6bc6c5d011a9b52d43a188))
+
+### Documentation
+
+- **readme:** Completion after verifying every story, spot and region ([c4d6740](https://github.com/MetaSekaiLab/nnnotes/commit/c4d67403b434a05f011a247a5c5bf48f52ebb9d1))
+
+## [0.1.1](https://github.com/MetaSekaiLab/nnnotes/compare/v0.1.0...v0.1.1) - 2026-09-27
+
+### Features
+
+- **config:** Write, edit and check the config file ([1f9b1a2](https://github.com/MetaSekaiLab/nnnotes/commit/1f9b1a2ab9ecb1a29a328a88c8dbf351e010597e))
+- **web:** [**breaking**] Store site assets compressed, gzip by default ([e90a46b](https://github.com/MetaSekaiLab/nnnotes/commit/e90a46b19f332e137b0fa49316651e2fb014a464))
+- **story:** [**breaking**] Stories reference their Live2D models instead of embedding them ([510ff98](https://github.com/MetaSekaiLab/nnnotes/commit/510ff98d90d19bee91e6f87f555c5fbb4104e08b))
+
+### Bug fixes
+
+- **room:** Share equal images and key objects by their file ([a8af00a](https://github.com/MetaSekaiLab/nnnotes/commit/a8af00a5f89afa11f0cdb0caf032afe38e6e1b18))
+
+## [0.1.0](https://github.com/MetaSekaiLab/nnnotes/releases/tag/v0.1.0) - 2026-09-27
+
+### Features
+
+- Add the nnnotes data toolkit ([073c60c](https://github.com/MetaSekaiLab/nnnotes/commit/073c60cc029b067e2b5db9a8c5772f7dbdcc58d4))
+- Read the APK boot data with bundled type trees ([fb1739e](https://github.com/MetaSekaiLab/nnnotes/commit/fb1739ebe5b898dcf5c6a4c02b4eb88f6f59ec28))
+- Build Live2D models into the web site ([03e3831](https://github.com/MetaSekaiLab/nnnotes/commit/03e38314eebf7d6a9bb62b5905778056b73d33c3))
+- Fetch the current master data version from the game's API ([bcd7f20](https://github.com/MetaSekaiLab/nnnotes/commit/bcd7f20d9bb1e3bfeb89dd72f49f5d360b8da2ae))
+- Serve every region and language from one web site ([8160121](https://github.com/MetaSekaiLab/nnnotes/commit/81601210452e3b40f195e115beaae0dccf10f7cc))
+- Add open and game text styles for exported text (--fonts) ([da41edf](https://github.com/MetaSekaiLab/nnnotes/commit/da41edf7fe17fff125f56d9a5d5ab2afa5e3f8f6))
+- Export frames, effects, stills, chat and videos of story episodes ([2bacea1](https://github.com/MetaSekaiLab/nnnotes/commit/2bacea1e02054393b4d8bc09d7325c3fa2be06da))
+- Add the asset export: export, plan, run-stage, catalogs ([d04423c](https://github.com/MetaSekaiLab/nnnotes/commit/d04423c2db72eb8d350c8271aaf2c9ea4bf64b88))
+- **live:** Offer the Live options that select files ([dc4f1e7](https://github.com/MetaSekaiLab/nnnotes/commit/dc4f1e704ccdebba878f179f24aa2157d6186c88))
+- **web:** Export story episodes for the story player ([197af04](https://github.com/MetaSekaiLab/nnnotes/commit/197af04954c4f5bd4dc6932140f57c0b7f937452))
+- **export:** FLAC level 8 by default and explicit layout placement ([11bf5d8](https://github.com/MetaSekaiLab/nnnotes/commit/11bf5d87f6decd8b0d465661c8d41f48b227945e))
+- **story:** Chat texts, emoji sprites, frame particles, lit rooms and CRI Lips data ([5eb4f6c](https://github.com/MetaSekaiLab/nnnotes/commit/5eb4f6cfa1978eab6846ff6cc99b48a997b90efc))
+- **deck-data:** One JSON of charts and master tables for deck-building tools ([06e6943](https://github.com/MetaSekaiLab/nnnotes/commit/06e6943e4a2ad977d6684871906f7d90a282a227))
+- **voices:** Voice index view and query command; one ACB table reader ([6bb748a](https://github.com/MetaSekaiLab/nnnotes/commit/6bb748aaa7e24942f5cee6ebb704e7c016e9a8c7))
+- **cri.movie:** All USM streams (MPEG-1, H.264, alpha, subtitles, HCA) and bundle-held movies ([ff97da8](https://github.com/MetaSekaiLab/nnnotes/commit/ff97da8b2cb01721041522f69d8c42c978b5150c))
+- **voices:** Story episode voices with their lines, speakers and cues ([e65d84d](https://github.com/MetaSekaiLab/nnnotes/commit/e65d84d9733e039bf046c3bfd56a5cda06eba118))
+- **story:** Missing glyphs and frame texts in the story font data ([476dff0](https://github.com/MetaSekaiLab/nnnotes/commit/476dff0c02f47017f26260997fb2b8bce0d2078e))
+- **story:** Open font assets follow the game's TMP fallback chains ([b5cd68e](https://github.com/MetaSekaiLab/nnnotes/commit/b5cd68ee7bbd3dc2dc58c9fb8858a20b34e7179c))
+
+### Bug fixes
+
+- Correct the ADV resource closure for chat stamps and IgnoreData rows ([9f03fb9](https://github.com/MetaSekaiLab/nnnotes/commit/9f03fb97784ecdfbeb0e576c8e257c0e6123b05c))
+- Stop with a usage error on unknown keys, ids and charts ([1fa6958](https://github.com/MetaSekaiLab/nnnotes/commit/1fa69589a68246ffa2cbd5a96bda8c1646be37b1))
+- Read the region, CDN and bundle key only when a download needs them ([da1d47c](https://github.com/MetaSekaiLab/nnnotes/commit/da1d47c918d7895e2f83390cf69f888817d0fcb9))
+- Handle more mesh, texture and reference forms in room and spot ([4ddc76c](https://github.com/MetaSekaiLab/nnnotes/commit/4ddc76ca667d5458a77928560e562060a331cf6b))
+- Generate MonoBehaviour typetrees in Unity's own node layout ([d0efb2c](https://github.com/MetaSekaiLab/nnnotes/commit/d0efb2cbbe17a2749fdb7f8f6b2370d25de95917))
+- Story UI language, model names, master JSON and external AWB ([29aada6](https://github.com/MetaSekaiLab/nnnotes/commit/29aada69e763dde8c2fd51fe287dfea118314766))
+- **export:** Read the APK's raw files from the APK ([3d9f79c](https://github.com/MetaSekaiLab/nnnotes/commit/3d9f79c135afb232a12ed3661584f780187a9b4b))
+- Size default worker counts by the CPUs the process may use ([a65eaf8](https://github.com/MetaSekaiLab/nnnotes/commit/a65eaf89d9726dcd3200166c3483cded94b30633))
+- **web:** Name --story when the fonts extra is missing ([8cb0f66](https://github.com/MetaSekaiLab/nnnotes/commit/8cb0f66f8e2ffcbc0171bbd0fc1bfbac9be09baa))
+
+### Performance
+
+- Reuse decoded textures, shader dumps and cue sheets by content ([1f7c166](https://github.com/MetaSekaiLab/nnnotes/commit/1f7c166d008eb06b0ac6f193ad7958fb88dbf7b4))
+- Pipeline the web build and reuse scenes, BGM decodes and read sets ([25461d1](https://github.com/MetaSekaiLab/nnnotes/commit/25461d12c715369285027d008ebc53f49c73acb6))
+- Start numpy with one OpenBLAS thread unless the environment sets it ([f93d3d2](https://github.com/MetaSekaiLab/nnnotes/commit/f93d3d2d4e1f34e863d96cf17175ead1376d09cc))
+- Serve read-set plans from long-lived player processes ([440ceaa](https://github.com/MetaSekaiLab/nnnotes/commit/440ceaad5c63e83bba4b3a2dde2592467b61c111))
+- **export:** Bound the memory of the finalize and of plan -o ([cad57e6](https://github.com/MetaSekaiLab/nnnotes/commit/cad57e61c4483300f402418501bfb754558287bf))
+- **cli:** Start without UnityPy; --flac-level on audio, live and story ([c5057d5](https://github.com/MetaSekaiLab/nnnotes/commit/c5057d5855b3703308c9b5d7d762821a0498bfaa))
+
+### Refactoring
+
+- Rename the site command to web ([43fe4cc](https://github.com/MetaSekaiLab/nnnotes/commit/43fe4cc3e016aa8a773182f8e8995b1ef27b1066))
+
+### Documentation
+
+- Remove the contributing guide ([056b4f6](https://github.com/MetaSekaiLab/nnnotes/commit/056b4f64316a5949f99f1cbefd3f0f1d7692a97e))
+- Title the project nnnotes？！ ([91b5042](https://github.com/MetaSekaiLab/nnnotes/commit/91b50422fc389945367924bcfdf773954fdafd03))
+- State determinism with its condition; settings per command ([9b0c6f7](https://github.com/MetaSekaiLab/nnnotes/commit/9b0c6f79b651303fca979b3811ffe62d9b7c0c00))
+- Recommend Python 3.13 ([cfea0f5](https://github.com/MetaSekaiLab/nnnotes/commit/cfea0f56be5758dc8b7fa3ca0f8f0191fc38336a))
+- Add performance.md: where a web build spends its time ([a4fb6a0](https://github.com/MetaSekaiLab/nnnotes/commit/a4fb6a0db5a6976630ac9cb069e026078772823a))
+- **performance:** Incremental runs and raw files not in the cache ([69a879c](https://github.com/MetaSekaiLab/nnnotes/commit/69a879ca1d64aecdd5eea3e352cd0861f0a88a66))
+
+### Build
+
+- **release:** Publish to PyPI with trusted publishing ([bb542af](https://github.com/MetaSekaiLab/nnnotes/commit/bb542af0d7e22a0255a7ee45099a51eb7fbadd12))
+
+### CI
+
+- Check the stage golden records with pinned library versions ([f2594f7](https://github.com/MetaSekaiLab/nnnotes/commit/f2594f70366c8b46d70d638168d43f6dd7949e5b))
+
+### Miscellaneous
+
+- List MetaMiku and emptysekai as copyright holders ([1629616](https://github.com/MetaSekaiLab/nnnotes/commit/1629616da629b7fbe7f714287aeff17933176357))
+- List MetaMiku as an author ([cc43e13](https://github.com/MetaSekaiLab/nnnotes/commit/cc43e132875206d02d8665b19c06b27255ab0037))
+- Point the project links at MetaSekaiLab/nnnotes ([a2b8304](https://github.com/MetaSekaiLab/nnnotes/commit/a2b83040bcf06771028bbfd5e90c10c225bde3e9))
+- English package readme; check commits on pull requests only ([e602dd5](https://github.com/MetaSekaiLab/nnnotes/commit/e602dd5ebf6dda0f18da5ace54a02dbb893a796f))
+
+

{nnnotes-0.1.3 → nnnotes-0.2.0}/PKG-INFO

@@ -1,32 +1,34 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: nnnotes
-Version: 0.1.3
-Classifier: Programming Language :: Python :: 3
+Version: 0.2.0
+Summary: Offline data toolkit for BanG Dream! Our Notes game files: catalogs, bundles, master data, stories, Live2D, audio and live charts
+Project-URL: Homepage, https://github.com/MetaSekaiLab/nnnotes
+Project-URL: Source, https://github.com/MetaSekaiLab/nnnotes
+Project-URL: Issues, https://github.com/MetaSekaiLab/nnnotes/issues
+Author: MetaMiku, emptysekai
+License-Expression: MIT
+License-File: LICENSE
 Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Multimedia
-Requires-Dist: unitypy>=1.25
+Requires-Python: >=3.11
+Requires-Dist: brotli>=1.1
+Requires-Dist: grpcio>=1.49.1
 Requires-Dist: numpy>=2.0
 Requires-Dist: pillow>=10.0
 Requires-Dist: pycryptodome>=3.20
-Requires-Dist: grpcio>=1.49.1
-Requires-Dist: brotli>=1.1
-Requires-Dist: fonttools>=4.50 ; extra == 'fonts'
-Requires-Dist: freetype-py>=2.5 ; extra == 'fonts'
-Requires-Dist: scipy>=1.13 ; extra == 'fonts'
-Requires-Dist: pytest>=8 ; extra == 'test'
-Requires-Dist: pyflakes>=3.2 ; extra == 'test'
-Requires-Dist: jsonschema>=4.18 ; extra == 'test'
+Requires-Dist: unitypy>=1.25
+Provides-Extra: deck
+Requires-Dist: ournotes-sim==0.0.7; extra == 'deck'
 Provides-Extra: fonts
+Requires-Dist: fonttools>=4.50; extra == 'fonts'
+Requires-Dist: freetype-py>=2.5; extra == 'fonts'
+Requires-Dist: scipy>=1.13; extra == 'fonts'
 Provides-Extra: test
-License-File: LICENSE
-Summary: Offline data toolkit for BanG Dream! Our Notes game files: catalogs, bundles, master data, stories, Live2D, audio and live charts
-Author: MetaMiku, emptysekai
-License-Expression: MIT
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
-Project-URL: Homepage, https://github.com/MetaSekaiLab/nnnotes
-Project-URL: Issues, https://github.com/MetaSekaiLab/nnnotes/issues
-Project-URL: Source, https://github.com/MetaSekaiLab/nnnotes
+Requires-Dist: jsonschema>=4.18; extra == 'test'
+Requires-Dist: pyflakes>=3.2; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
 
 # nnnotes？！
 
@@ -39,7 +41,7 @@ for configuration and validation limits.
 nnnotes is an offline data toolkit for the game files of BanG Dream! Our Notes: it reads Addressables catalogs,
 downloads and decrypts asset bundles, downloads and decodes master data, and exports stories, Live2D models, spots,
 shaders, CRI audio and live charts as structured JSON and common file formats. The charts, Live2D models and stories `web`
-exports are the data that [ournotes-player](https://github.com/empty-sekai/ournotes-player) reads. The naming was inspired by [mos9527/sssekai](https://github.com/mos9527/sssekai).
+exports are the data that [ournotes-player](https://github.com/empty-sekai/ournotes-player) reads. The naming was inspired by sssekai.
 
 This is an unofficial fan project, not affiliated with the game's developer or operator. The repository contains no
 game assets, keys or server addresses: users supply the game files, the keys needed for decryption and the server
@@ -58,7 +60,8 @@ nnnotes config check             # each setting's origin and whether it is valid
 - Scripts and AI agents get no questions: `nnnotes config init --user --no-input --set SECTION.KEY=VALUE ...` writes
   the file at once, `nnnotes config set SECTION.KEY VALUE` changes one value (VALUE `-` reads it from standard input,
   so a key need not appear on the command line), and `nnnotes config check --json` reports the states for machines.
-- `--fonts game` also needs `pip install 'nnnotes[fonts]'`; the APK, the master data and the external tools are listed
+- `--fonts game` also needs `pip install 'nnnotes[fonts]'`, and the deck statistics of `music-data` need
+  `pip install 'nnnotes[deck]'`; the APK, the master data and the external tools are listed
   under Requirements below.
 
 ## Features
@@ -84,7 +87,7 @@ nnnotes config check             # each setting's origin and whether it is valid
 | `ui` (experimental) | APK set and its embedded catalog | an offline serialized prefab library with dependency roots, AnimatorControllers, stable references and PNG/font resources for the optional ournotes-player UI preview ([format and limits](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/ui.md)) |
 | `live` | music ID + difficulty | a full chart directory: chart and runtime notes, 3D scene, note and effect assets, BGM and sounds, sound routing |
 | `web` | `--pair music:difficulty` (repeatable) or `--all`; `--live2d model` (repeatable) or `--all-live2d`; `--story episode` (repeatable) or `--all-stories`; `--region region` (repeatable) or `--all-regions` | an ournotes-player static site: shared player + per-chart / per-model / per-episode manifests + content-addressed assets; the Live2D models of the stories are built first as models, listed in `models.json`, and the story manifests reference them; one site can serve several regions, with listing texts in five languages; a story's interface texts are grouped by language, with TextMeshPro font assets generated from open fonts (the game's fonts with `--fonts game`); compressible assets (JSON, shaders, moc3, ...) are stored gzip encoded by default (`--compress br` / `none`) |
-| `music-data` | master data files (`--master-files` directory or `--apk-master`), or decoded master data with its manifest (`--decoded-master`) | one JSON file with every song and chart: titles and credits in five languages, bands, vocal characters, category, tags, release time, score ranks, BGM length; the Gekisou catalog (member cards, snaps and their Gekisou skills and support skills); per difficulty the level, note counts, BPM, chart times, skill events and fever ranges; and the chart statistics the deck model ournotes-deck (built into nnnotes) measures on its whole-live simulation (the no-skill score, the weight of every score-up skill kind at every position), plus single-shape Gekisou aptitude (increments and standard errors, not an optimal deck; omit with `--no-gekisou-aptitude`). `--full` adds the deck model's input: every chart's runtime notes and the master data tables about cards, skills, bonuses, scores and events ([format](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/music-data.md)) |
+| `music-data` | master data files (`--master-files` directory or `--apk-master`), or decoded master data with its manifest (`--decoded-master`) | one JSON file with every song and chart: titles and credits in five languages, bands, vocal characters, category, tags, release time, score ranks, BGM length; the Gekisou catalog (member cards, snaps and their Gekisou skills and support skills); per difficulty the level, note counts, BPM, chart times, skill events and fever ranges; and the chart statistics the deck model ournotes-deck (installed with `pip install 'nnnotes[deck]'`) measures on its whole-live simulation (the no-skill score, the weight of every score-up skill kind at every position), plus single-shape Gekisou aptitude (increments and standard errors, not an optimal deck; omit with `--no-gekisou-aptitude`). `--full` adds the deck model's input: every chart's runtime notes and the master data tables about cards, skills, bonuses, scores and events ([format](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/music-data.md)) |
 
 Export conventions:
 
@@ -218,10 +221,17 @@ settings (TOML / environment / flags)
 Every JSON file is written by one writer (`jsonio`), so encoding, line endings and number formatting are the same
 everywhere.
 
-See [docs/performance.md](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/performance.md) for where a
-`web` build spends its time and which parts of it run in compiled code.
+## Changelog
+
+[CHANGELOG.md](https://github.com/MetaSekaiLab/nnnotes/blob/main/CHANGELOG.md) lists the changes in every version,
+generated from the commits by [git-cliff](https://git-cliff.org/). The commit that bumps the version regenerates it:
+
+```bash
+git cliff --tag vX.Y.Z -o CHANGELOG.md
+```
+
+When a `vX.Y.Z` tag is pushed, the release workflow checks the versions and that CHANGELOG.md has a section for it.
 
 ## License
 
 MIT, see [LICENSE](https://github.com/MetaSekaiLab/nnnotes/blob/main/LICENSE).
-

{nnnotes-0.1.3 → nnnotes-0.2.0}/README.en.md

@@ -9,7 +9,7 @@ for configuration and validation limits.
 nnnotes is an offline data toolkit for the game files of BanG Dream! Our Notes: it reads Addressables catalogs,
 downloads and decrypts asset bundles, downloads and decodes master data, and exports stories, Live2D models, spots,
 shaders, CRI audio and live charts as structured JSON and common file formats. The charts, Live2D models and stories `web`
-exports are the data that [ournotes-player](https://github.com/empty-sekai/ournotes-player) reads. The naming was inspired by [mos9527/sssekai](https://github.com/mos9527/sssekai).
+exports are the data that [ournotes-player](https://github.com/empty-sekai/ournotes-player) reads. The naming was inspired by sssekai.
 
 This is an unofficial fan project, not affiliated with the game's developer or operator. The repository contains no
 game assets, keys or server addresses: users supply the game files, the keys needed for decryption and the server
@@ -28,7 +28,8 @@ nnnotes config check             # each setting's origin and whether it is valid
 - Scripts and AI agents get no questions: `nnnotes config init --user --no-input --set SECTION.KEY=VALUE ...` writes
   the file at once, `nnnotes config set SECTION.KEY VALUE` changes one value (VALUE `-` reads it from standard input,
   so a key need not appear on the command line), and `nnnotes config check --json` reports the states for machines.
-- `--fonts game` also needs `pip install 'nnnotes[fonts]'`; the APK, the master data and the external tools are listed
+- `--fonts game` also needs `pip install 'nnnotes[fonts]'`, and the deck statistics of `music-data` need
+  `pip install 'nnnotes[deck]'`; the APK, the master data and the external tools are listed
   under Requirements below.
 
 ## Features
@@ -54,7 +55,7 @@ nnnotes config check             # each setting's origin and whether it is valid
 | `ui` (experimental) | APK set and its embedded catalog | an offline serialized prefab library with dependency roots, AnimatorControllers, stable references and PNG/font resources for the optional ournotes-player UI preview ([format and limits](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/ui.md)) |
 | `live` | music ID + difficulty | a full chart directory: chart and runtime notes, 3D scene, note and effect assets, BGM and sounds, sound routing |
 | `web` | `--pair music:difficulty` (repeatable) or `--all`; `--live2d model` (repeatable) or `--all-live2d`; `--story episode` (repeatable) or `--all-stories`; `--region region` (repeatable) or `--all-regions` | an ournotes-player static site: shared player + per-chart / per-model / per-episode manifests + content-addressed assets; the Live2D models of the stories are built first as models, listed in `models.json`, and the story manifests reference them; one site can serve several regions, with listing texts in five languages; a story's interface texts are grouped by language, with TextMeshPro font assets generated from open fonts (the game's fonts with `--fonts game`); compressible assets (JSON, shaders, moc3, ...) are stored gzip encoded by default (`--compress br` / `none`) |
-| `music-data` | master data files (`--master-files` directory or `--apk-master`), or decoded master data with its manifest (`--decoded-master`) | one JSON file with every song and chart: titles and credits in five languages, bands, vocal characters, category, tags, release time, score ranks, BGM length; the Gekisou catalog (member cards, snaps and their Gekisou skills and support skills); per difficulty the level, note counts, BPM, chart times, skill events and fever ranges; and the chart statistics the deck model ournotes-deck (built into nnnotes) measures on its whole-live simulation (the no-skill score, the weight of every score-up skill kind at every position), plus single-shape Gekisou aptitude (increments and standard errors, not an optimal deck; omit with `--no-gekisou-aptitude`). `--full` adds the deck model's input: every chart's runtime notes and the master data tables about cards, skills, bonuses, scores and events ([format](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/music-data.md)) |
+| `music-data` | master data files (`--master-files` directory or `--apk-master`), or decoded master data with its manifest (`--decoded-master`) | one JSON file with every song and chart: titles and credits in five languages, bands, vocal characters, category, tags, release time, score ranks, BGM length; the Gekisou catalog (member cards, snaps and their Gekisou skills and support skills); per difficulty the level, note counts, BPM, chart times, skill events and fever ranges; and the chart statistics the deck model ournotes-deck (installed with `pip install 'nnnotes[deck]'`) measures on its whole-live simulation (the no-skill score, the weight of every score-up skill kind at every position), plus single-shape Gekisou aptitude (increments and standard errors, not an optimal deck; omit with `--no-gekisou-aptitude`). `--full` adds the deck model's input: every chart's runtime notes and the master data tables about cards, skills, bonuses, scores and events ([format](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/music-data.md)) |
 
 Export conventions:
 
@@ -188,8 +189,16 @@ settings (TOML / environment / flags)
 Every JSON file is written by one writer (`jsonio`), so encoding, line endings and number formatting are the same
 everywhere.
 
-See [docs/performance.md](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/performance.md) for where a
-`web` build spends its time and which parts of it run in compiled code.
+## Changelog
+
+[CHANGELOG.md](https://github.com/MetaSekaiLab/nnnotes/blob/main/CHANGELOG.md) lists the changes in every version,
+generated from the commits by [git-cliff](https://git-cliff.org/). The commit that bumps the version regenerates it:
+
+```bash
+git cliff --tag vX.Y.Z -o CHANGELOG.md
+```
+
+When a `vX.Y.Z` tag is pushed, the release workflow checks the versions and that CHANGELOG.md has a section for it.
 
 ## License
 

nnnotes-0.2.0/README.md

@@ -0,0 +1,156 @@
+# nnnotes？！
+
+[简体中文](README.md) | [English](README.en.md)
+
+nnnotes 是 BanG Dream! Our Notes 游戏文件的离线数据工具包：读取 Addressables catalog、下载并解密资源包、下载与解码 masterdata，再把剧情、Live2D、据点场景、着色器、CRI 音频和谱面导出成结构化的 JSON 与通用格式文件。`web` 导出的谱面、Live2D 模型与剧情站点就是 [ournotes-player](https://github.com/empty-sekai/ournotes-player) 读取的数据。命名灵感来自 sssekai。
+
+本项目为非官方爱好者项目，与游戏的开发和运营方无关。仓库不包含任何游戏资源、密钥或服务器地址：游戏文件、解密所需的密钥和服务器地址都由使用者在配置中自行提供，导出结果只保存在使用者指定的本地目录。
+
+## 安装与初始化
+
+```sh
+pip install nnnotes              # Python 3.11+，推荐 3.13
+nnnotes config init --user       # 在终端里逐项填写设置（密钥不回显），写入用户配置文件，在任何目录下都会读取
+nnnotes config check             # 每项设置的来源和格式是否有效，不显示设置值
+```
+
+- 设置值（密钥、区服的 CDN 与 API 地址、本地数据与工具的路径）都来自使用者自己的游戏客户端，见[配置](#配置)。
+- 在脚本或 AI 代理中不会有交互提问：`nnnotes config init --user --no-input --set 段.键=值 ...` 一次写好，之后用 `nnnotes config set 段.键 值` 修改单项（值写 `-` 时从标准输入读取，密钥不必出现在命令行里），`nnnotes config check --json` 给出机器可读的状态。
+- `--fonts game` 另需 `pip install 'nnnotes[fonts]'`，`music-data` 的组卡统计另需 `pip install 'nnnotes[deck]'`；APK、masterdata 与外部工具见[需要准备](#需要准备)。
+
+## 功能
+
+| 命令 | 输入 | 输出 |
+|---|---|---|
+| `catalog` | 区服 catalog | 列出 Addressables 资源键（可按前缀过滤） |
+| `browse` | 已配置的各区服 catalog | 本地网页浏览 catalog 与资源包（`--host` / `--port`） |
+| `pull` | 资源键 | 下载并解密该键依赖闭包中的全部资源包到本地缓存 |
+| `servers` | 引导 API 根地址 `[bootstrap] api` | 游戏 API 的服务器列表：各区服名称、区域 ID 与 CDN / API 根地址（地址仅在 `--show-hosts` 时输出） |
+| `master version` | 区服 | 该区服当前的 masterdata 版本与资源版本（游戏 API 匿名调用） |
+| `master download` | masterdata 版本号，或 `--latest`（区服当前版本） | 该版本的 `MasterManifest.json` 与全部 `.bin` 文件（SHA-256 校验） |
+| `master decode` | masterdata `.bin` 文件或目录 | 每张表一个 JSON（Rijndael-256 CBC 解密 + gzip 解压） |
+| `adv` | 剧情 ID | `episode.json`：命令表、五语台词、语音 / 音效 / 视频索引 |
+| `story` | 剧情 ID | 剧情目录：episode、音频、舞台场景与着色器、剧情 UI、Frame / 粒子特效 / 后处理 / 静帧 / 对话框 / 聊天资源、视频（WebM）；用到的 Live2D 模型导出到模型目录（`--models`，默认为剧情目录旁的 `live2d/`），已导出的模型供其他剧情复用 |
+| `live2d` | 模型资源键或模型 ID | Live2D（Cubism）运行时目录：moc3、贴图、motion3、物理、表情、预制体参数 |
+| `spot` | 据点 ID | `spot.json` + Spine 角色 + 房间 `room.glb` + 着色器 |
+| `room` | 背景预制体键 | 房间模型（binary glTF） |
+| `shader` | 资源键或 APK 内资源包 | 着色器各平台变体（GLSL ES 等）与索引 |
+| `audio` | CRI cue sheet | 每个 cue 一个音频文件（FLAC / Ogg / WAV）+ cue 元数据 |
+| `crikey` | APK | 读出游戏启动数据中的 CRI HCA 解码密钥（只显示是否找到，可写成 `.hcakey`） |
+| `player` | APK | 渲染相关的全局设置（色彩空间、画质等级、渲染器）JSON |
+| `ui`（实验性） | APK 集合及内嵌 catalog | 离线序列化预制体库，包含依赖根对象、AnimatorController、稳定引用与 PNG／字体资源，供 ournotes-player 可选 UI 预览使用（[格式与边界](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/ui.md)） |
+| `live` | 曲目 ID + 难度 | 完整谱面目录：谱面与运行时音符、3D 场景、音符与特效资源、BGM 与音效、声音路由 |
+| `web` | `--pair 曲目:难度`（可重复）或 `--all`；`--live2d 模型`（可重复）或 `--all-live2d`；`--story 剧情 ID`（可重复）或 `--all-stories`；`--region 区服`（可重复）或 `--all-regions` | ournotes-player 静态站点：共享播放器 + 每谱 / 每模型 / 每集剧情清单 + 内容寻址资源；剧情用到的 Live2D 模型先按模型构建并列入 `models.json`，剧情清单引用它们；一个站点可服务多个区服，列表文本含五种语言；剧情的界面文字按语言分组，字形由开源字体生成 TextMeshPro 字体资源（`--fonts game` 时用游戏字体）；可压缩的资源（JSON、着色器、moc3 等）默认以 gzip 存储，`--compress br` / `none` 可改 |
+| `music-data` | masterdata 文件（`--master-files` 目录或 `--apk-master`），或带清单的解码 masterdata（`--decoded-master`） | 全部歌曲与谱面的单个 JSON：五语标题与作词作曲编曲、乐队、演唱角色、分类、标签、上线时间、评级线、BGM 时长；激走目录（成员卡、小卡及其激走技能与激走支援技能）；每个难度的等级、音符数、BPM、谱面时间、技能事件与 fever 区间；以及组卡模型 ournotes-deck（`pip install 'nnnotes[deck]'` 安装）在整场模拟上实测的谱面统计（无技能得分、每种加分技能在每个演出位的权重），以及单个激走技能形状的谱面适性（增量与标准误，不选最佳编成；`--no-gekisou-aptitude` 可跳过）。`--full` 另附组卡模型的输入：每张谱面的运行时音符与卡牌、技能、加成、分数、活动相关的 masterdata 表（[格式](docs/music-data.md)） |
+
+导出约定：
+
+- 写文件的命令都用 `-o` 指定输出路径（必填）；`web` 的站点目录是位置参数。
+- JSON 一律 UTF-8、LF 换行；无穷大写作 `1e999`。
+- 在同一套环境下导出是确定的：同样的输入，在 nnnotes、Python 依赖库（UnityPy、Pillow、numpy 等）和外部工具（vgmstream、FFmpeg）版本都相同时，导出文件逐字节相同。版本不同时，相同内容可能写成不同的字节：例如不同版本的 Pillow 写出的 PNG 像素相同，字节可能不同。
+- 数值保留 Unity 序列化值与字段名（`m_LocalPosition`、`_bandIDs` 等），便于与游戏数据对照。
+- 贴图导出为 PNG，着色器保留游戏自带的编译结果，音频由 CRI 格式解码为通用格式。
+
+## 完成度
+
+日服现已支持匿名版本查询、CDN 认证下载、gzip catalog、资源路径与缓存隔离，以及 Android 分包读取。
+配置、命令和日服验证范围见 [日服支持](docs/jp.md)。
+
+以下结果基于台服 1.0.1（zh-Hant）的全部数据：
+
+| 部分 | 状态 |
+|---|---|
+| catalog / 资源包解密 / 依赖闭包 | 可用 |
+| masterdata 解码 | 可用 |
+| 剧情 `adv` | 946 / 946 集可导出 |
+| 剧情 `story`（完整目录） | 946 / 946 集的资源都在 catalog 中且类型均受支持（资源闭包与游戏自带的每集下载清单一致）；946 / 946 集已逐集导出验证：输出中引用的文件、模型与音频均存在，JSON 均可解析，引用的路径均可解析；其中 235 集用到 Frame / Effect / PostEffect / Still / Chat / TalkWindow / 视频资源，两次导出除模型目录路径外逐字节一致 |
+| Live2D 模型 | 239 / 239 个可导出（catalog 中的全部模型，剧情用到其中 185 个） |
+| CRI 音频 | 681 / 681 个 cue sheet 可解码 |
+| 谱面 `live` | 336 / 336 个（曲目, 难度）组合可导出 |
+| 网页站点 `web` | 336 / 336 张谱面，239 / 239 个 Live2D 模型，946 / 946 集剧情（英语、无音频的全量构建两次结果逐字节一致，946 / 946 集通过数据校验）；三个区服、五种语言、含 AAC 音频的全量构建（`--all-regions`，用线上 masterdata：85 首曲目的 340 张谱面）两次结果同样逐字节一致，全部通过数据校验 |
+| 据点 `spot` / `room` | 39 / 39 个据点可导出，引用均可解析；catalog 中 20 / 20 个房间背景可由 `room` 导出。生成的 glb 均通过 Khronos glTF-Validator，0 个错误 |
+| 其他区服（en / kr）与其他语言 | 已核对：各区服同一语言的 catalog 相同、资源包相同，密钥通用；谱面用到的 masterdata 表在三个区服间一致，文本表五种语言齐全；抽查的谱面导出与台服一致。多区服整站已全量构建验证（见上一行） |
+
+## 需要准备
+
+- Python 3.11+，推荐 3.13（`web` 构建读写大量 JSON，3.13 的标准库 JSON 编码更快）；开发时在仓库内 `pip install -e .`
+- 游戏安装包 `base.apk`：APK 内置资源包、CRI 解码密钥、启动设置。`player`、`story`、`live`、`web` 用 nnnotes 自带的类型树读取 APK 启动数据中的 MonoBehaviour，目前支持游戏版本 1.0.1（Unity 6000.3.12f1）；其他版本的 APK 若类型不符，这些命令会报错并给出类名、游戏版本和 Unity 版本
+- 解码后的 masterdata 目录（可用 `master download` + `master decode` 生成）：`adv`、`story`、`spot`、`live` 和 `web` 的谱面需要；`web` 的 Live2D 模型只用它取角色名（可选）
+- 外部工具：[vgmstream](https://vgmstream.org/)（CRI HCA 解码）、[FFmpeg](https://ffmpeg.org/)（转码，含剧情视频的 WebM 封装与 Opus 音频）；`web` 另需 Node.js 20+ 与构建好的 ournotes-player
+
+## 配置
+
+代码中没有任何密钥、服务器地址和默认路径。所有设置按以下顺序读取，后者覆盖前者：
+
+1. 配置文件：`--config <文件>`，否则 `NNNOTES_CONFIG`，否则当前目录的 `nnnotes.toml`，否则用户配置文件（Windows 为 `%APPDATA%\nnnotes\nnnotes.toml`，其他系统为 `~/.config/nnnotes/nnnotes.toml`；`nnnotes config path` 列出查找顺序与实际读取的文件）
+2. 环境变量：`NNNOTES_<节>_<键>`（如 `NNNOTES_BUNDLE_KEY`、`NNNOTES_SERVERS_TW_CDN`）
+3. 命令行参数：`--region`、`--language`、`--catalog`、`--cache`、`--master`、`--apk`、`--ffmpeg`、`--vgmstream`、`--node` 写在命令名之前；`--player` 是 `web` 的参数
+
+`nnnotes config init` 写出配置模板（每项设置为空，模板随包安装，仓库中为 [`src/nnnotes/nnnotes.example.toml`](src/nnnotes/nnnotes.example.toml)），在终端中会逐项询问；`config set` / `config unset` 修改单项并保留文件中的注释。需要的设置包括：资源包解密密钥与 nonce 种子、masterdata 的密钥与 IV、使用的区服 `[catalog] region` 与 catalog 语言 `[catalog] language`、每个区服的 CDN 地址与 API 根地址（`[servers.<区服>]` 的 `cdn`、`api`）、客户端版本 `[client] version`（未设置时读取 APK 的 versionName）、可选的引导 API 根地址 `[bootstrap] api`（`servers` 使用），以及缓存目录、APK、masterdata 目录、ournotes-player 和 vgmstream / FFmpeg / Node.js 的路径（三个工具未设置时在 `PATH` 中查找）。这些值都来自使用者自己的游戏客户端。
+
+缺少或格式错误的设置会让命令以退出码 2 结束，并用一行说明对应的配置键、环境变量和命令行参数，不会输出任何设置值。`nnnotes.toml` 已在 `.gitignore` 中，请勿提交。
+
+完整说明见 [docs/configuration.md](docs/configuration.md)。
+
+## 使用示例
+
+```bash
+nnnotes catalog --prefix Live/MusicScore/ --limit 20
+nnnotes browse --port 8000
+nnnotes pull Live/MusicScore/0001/0001_03
+nnnotes master version
+nnnotes master download --latest -o work/master-bin
+nnnotes master decode work/master-bin -o work/master
+nnnotes --master work/master adv 10462 -o out/adv_10462.json
+nnnotes story 10462 -o out/story_10462
+nnnotes live 100001 --difficulty expert -o out/live_100001
+nnnotes web out/site --all --player <ournotes-player 目录> --workers 5
+nnnotes web out/site --pair 100001:expert --pair 100001:hard --player <ournotes-player 目录>
+nnnotes web out/site --all --region tw --region en --region kr --player <ournotes-player 目录>
+nnnotes web out/site --live2d adv_live2d_rana_003_casual_spring_01 --player <ournotes-player 目录>
+```
+
+`web` 可以增量构建：清单已存在的谱面和模型会跳过（`--force` 重建），不再被引用的资源会被清理。常用参数：
+
+- `--format aac|opus|vorbis|mp3|flac`：BGM 格式，默认 AAC；`--no-audio`：不导出音频
+- `--band` / `--leader-card`：轻量背景与开场时间轴所用乐队；默认取曲目第一位演唱角色的乐队
+- `--workers`：并行处理的曲目进程数（默认为 CPU 数的四分之一，最多 8）与模型进程数（默认最多 4）；`--read-workers`：同时运行的谱面读取集（Node.js 进程）数（默认为 CPU 数的一半，最多 16）；`--tmp`：临时构建目录（默认 `<站点>.tmp`）
+- `--live2d 模型`（模型 ID 或资源键，可重复）/ `--all-live2d`：加入 Live2D 模型（catalog 中全部模型），可与谱面在同一次构建中加入
+- `--region 区服`（可重复）/ `--all-regions`：站点服务的区服（默认 `[catalog] region`）；每个区服的 masterdata 由 `[servers.<区服>] master` 指定。谱面数据相同的区服共用一份清单，列表页用 `?region=&lang=` 切换区服与语言
+- `--player-only`：只重写播放器文件与 `charts.json`、`models.json`；`--reingest-json`：按当前规则重新存储所有谱面与模型的 JSON
+
+各命令的参数与输出目录结构见 [docs/commands.md](docs/commands.md)。
+
+## 架构
+
+```
+配置（TOML / 环境变量 / 参数）
+  └─ 访问层      addressables（catalog 解析、资源包解密、本地浏览）
+                 catalog（依赖闭包、远端与 APK 内资源、本地缓存）
+                 master（masterdata 下载与解码）
+                 gameapi（游戏 API 匿名调用：当前 masterdata 版本、服务器列表）
+       └─ 读取层  unity（UnityPy 读取 typetree 与 TextAsset）
+                  export（预制体 / 组件 / 引用全部解析为 JSON，贴图与着色器随同导出）
+                  shader、textstyle（文字排版与样式）、tmpfont（TextMesh Pro 字体）、player（启动设置）、cri + crikey（CRI 音频）
+            └─ 内容层  剧情：adv、advscene、advmedia（Frame / 特效 / 后处理 / 静帧 / 聊天）、advvideo（USM 视频）、advui、story
+                       Live2D：live2d、motion
+                       据点：spot、room
+                       谱面：score（谱面解析与游戏谱面转换器的复现）、livescene、livenotes、liveui、liveaudio、live
+                       站点：web、webmodel（ournotes-player 数据）
+```
+
+所有 JSON 由同一个写出器生成（`jsonio`），保证编码、换行与数值格式一致。
+
+## 版本记录
+
+每个版本的改动见 [CHANGELOG.md](CHANGELOG.md)，由 [git-cliff](https://git-cliff.org/) 根据提交生成。发版时，改版本号的那个提交同时重新生成它：
+
+```bash
+git cliff --tag vX.Y.Z -o CHANGELOG.md
+```
+
+推送 `vX.Y.Z` 标签后，发布流程会核对版本号，并确认 CHANGELOG.md 里有这个版本。
+
+## License
+
+MIT，见 [LICENSE](LICENSE)。