nnnotes 0.1.0__tar.gz

nnnotes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetaMiku, emptysekai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nnnotes-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: nnnotes
+Version: 0.1.0
+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
+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
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: UnityPy>=1.25
+Requires-Dist: numpy>=2.0
+Requires-Dist: Pillow>=10.0
+Requires-Dist: pycryptodome>=3.20
+Requires-Dist: grpcio>=1.49.1
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pyflakes>=3.2; extra == "test"
+Requires-Dist: jsonschema>=4.18; extra == "test"
+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"
+Dynamic: license-file
+
+# nnnotes？！
+
+[简体中文](https://github.com/MetaSekaiLab/nnnotes/blob/main/README.md) | [English](https://github.com/MetaSekaiLab/nnnotes/blob/main/README.en.md)
+
+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 chart export is 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).
+
+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
+addresses in their own configuration, and the exports stay in local directories the user chooses.
+
+## Features
+
+| Command | Input | Output |
+|---|---|---|
+| `catalog` | the region's catalog | addressable keys (optionally by prefix) |
+| `browse` | the configured regions' catalogs | a local web page to browse catalogs and bundles (`--host` / `--port`) |
+| `pull` | addressable keys | every bundle of each key's dependency closure, decrypted into the local cache |
+| `servers` | the bootstrap API root `[bootstrap] api` | the game API's server list: each region's name, area id and CDN / API roots (the roots only with `--show-hosts`) |
+| `master version` | region | the master data version and resource version the region serves now (anonymous game API call) |
+| `master download` | master data version, or `--latest` (the region's current one) | that version's `MasterManifest.json` and every `.bin` file (SHA-256 checked) |
+| `master decode` | master data `.bin` files or directories | one JSON per table (Rijndael-256 CBC decryption + gzip) |
+| `adv` | episode ID | `episode.json`: command list, lines in five languages, voice / sound / video index |
+| `story` | episode ID | a full story directory: episode, every Live2D model, audio, stage scene and shaders, story UI, frames / particle effects / post effects / stills / talk windows / chat assets, videos (WebM) |
+| `live2d` | model key or model id | a Live2D (Cubism) runtime directory: moc3, textures, motion3, physics, expressions, prefab parameters |
+| `spot` | spot ID | `spot.json` + Spine characters + the room as `room.glb` + shaders |
+| `room` | background prefab key | the room model (binary glTF) |
+| `shader` | key or APK bundles | every platform variant of the shaders (GLSL ES and others) with an index |
+| `audio` | CRI cue sheet | one audio file per cue (FLAC / Ogg / WAV) + cue metadata |
+| `crikey` | APK | the CRI HCA keycode from the game's boot data (shows whether it was found; can write a `.hcakey`) |
+| `player` | APK | render-related global settings (color space, quality levels, renderers) as JSON |
+| `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; 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`) |
+| `deck-data` | master data files (`--master-files` directory or `--apk-master`) | one JSON file for deck-building tools: every chart's runtime notes, skill events and fever ranges, and the master data tables about cards, skills, bonuses, scores and events ([format](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/deck-data.md)) |
+
+Export conventions:
+
+- Commands that write files take the output path with `-o` (required); `web` takes the site directory as a
+  positional argument.
+- JSON is always UTF-8 with LF line endings; infinity is written as `1e999`.
+- Exports are deterministic for a given installation: the same input with the same versions of nnnotes, its Python
+  dependencies (UnityPy, Pillow, numpy, ...) and the external tools (vgmstream, FFmpeg) gives byte-identical files.
+  Other versions can encode the same content into other bytes: PNG files written by another Pillow version can
+  differ in their bytes while their pixels are equal.
+- Values keep Unity's serialized values and field names (`m_LocalPosition`, `_bandIDs`, ...), so they can be
+  compared with the game data.
+- Textures are exported as PNG, shaders keep the game's own compiled programs, audio is decoded from the CRI formats
+  to common formats.
+
+## Status
+
+Based on all data of the Taiwan server, version 1.0.1 (zh-Hant):
+
+| Part | Status |
+|---|---|
+| catalog / bundle decryption / dependency closure | working |
+| master data decoding | working |
+| stories, `adv` | 946 / 946 episodes |
+| stories, `story` (full directory) | 946 / 946 episodes have all their resources in the catalog and of supported kinds (the resource closure equals the game's own per-episode download list); 759 exported one by one, the other 187 (with frames, effects, post effects, stills and the like) not yet one by one |
+| Live2D models | 239 / 239 (every model of the catalog; episodes use 185 of them) |
+| CRI audio | 681 / 681 cue sheets |
+| charts, `live` | 336 / 336 (music, difficulty) pairs |
+| web site, `web` | 336 / 336 charts, 239 / 239 Live2D models, 946 / 946 story episodes (two full builds in English without audio are byte-identical and 946 / 946 pass the data validation; a 27-episode sample in five languages with AAC audio is likewise identical across two builds and valid) |
+| spots, `spot` / `room` | one spot verified, the others not individually checked |
+| other regions (en / kr) and languages | checked: the regions serve the same catalog for a language and the same bundles, and the keys are shared; the master tables the charts use are the same in the three regions, and the text tables have all five languages; the chart exports checked match the Taiwan server's. A full multi-region site build is not verified yet |
+
+## Requirements
+
+- Python 3.11+, 3.13 recommended (a `web` build reads and writes a lot of JSON, and the standard library encodes
+  JSON faster on 3.13); `pip install nnnotes` (for development `pip install -e .` in the repository)
+- the game's `base.apk`: APK-local bundles, the CRI keycode, boot settings. `player`, `story`, `live` and `web` read
+  MonoBehaviours of its boot data with type trees that ship with nnnotes; supported now: game version 1.0.1
+  (Unity 6000.3.12f1). With an APK of another version whose classes do not match, these commands stop with an
+  error naming the class, the game version and the Unity version
+- a decoded master data directory (from `master download` + `master decode`): needed by `adv`, `story`, `spot`,
+  `live` and the charts of `web`; the Live2D models of `web` use it only for their character names (optional)
+- external tools: [vgmstream](https://vgmstream.org/) (CRI HCA decoding), [FFmpeg](https://ffmpeg.org/)
+  (transcoding, including the WebM muxing and Opus audio of story videos); `web` also needs Node.js 20+ and a built
+  ournotes-player
+
+## Configuration
+
+The code contains no keys, server addresses or default paths. Settings are read in this order, later sources
+overriding earlier ones:
+
+1. config file: `--config <file>`, else `NNNOTES_CONFIG`, else `nnnotes.toml` in the working directory
+2. environment variables: `NNNOTES_<SECTION>_<KEY>` (e.g. `NNNOTES_BUNDLE_KEY`, `NNNOTES_SERVERS_TW_CDN`)
+3. command-line flags: `--region`, `--language`, `--catalog`, `--cache`, `--master`, `--apk`, `--ffmpeg`,
+   `--vgmstream`, `--node` go before the command name; `--player` is an option of `web`
+
+Copy [`nnnotes.example.toml`](https://github.com/MetaSekaiLab/nnnotes/blob/main/nnnotes.example.toml) to `nnnotes.toml` and fill it in. The settings are: the bundle
+key and nonce seed, the master data key and IV, the region in use (`[catalog] region`) and the catalog language
+(`[catalog] language`), the CDN base and API root of each region (`cdn`, `api` of `[servers.<region>]`), the client
+version (`[client] version`; unset: the APK's versionName), optionally the bootstrap API root (`[bootstrap] api`, for
+`servers`), and the paths of the cache, the APK, the master data directory, ournotes-player and vgmstream / FFmpeg /
+Node.js (the three tools are looked up on `PATH` when unset). All values come from the game client you own.
+
+A missing or malformed setting stops the command with exit status 2 and one line naming the TOML key, the
+environment variable and the flag; no setting value is printed. `nnnotes.toml` is in `.gitignore`; do not commit it.
+
+See [docs/configuration.md](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/configuration.md) for the full reference.
+
+## Examples
+
+```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 dir> --workers 5
+nnnotes web out/site --pair 100001:expert --pair 100001:hard --player <ournotes-player dir>
+nnnotes web out/site --all --region tw --region en --region kr --player <ournotes-player dir>
+nnnotes web out/site --live2d adv_live2d_rana_003_casual_spring_01 --player <ournotes-player dir>
+```
+
+`web` builds incrementally: charts and models whose manifest exists are skipped (`--force` rebuilds them) and assets
+no longer referenced are removed. Common options:
+
+- `--format aac|opus|vorbis|mp3|flac`: BGM format, default AAC; `--no-audio`: no audio files
+- `--band` / `--leader-card`: the band of the LightWeight background and the start timeline; default: the band of
+  the music's first vocal character
+- `--workers`: parallel music processes (default a quarter of the CPUs, up to 8) and model processes (default up
+  to 4); `--read-workers`: chart read sets at a time (Node.js processes; default half the CPUs, up to 16); `--tmp`:
+  temporary build directory (default `<site>.tmp`)
+- `--live2d MODEL` (model id or key, repeatable) / `--all-live2d`: add Live2D models (every model of the catalog);
+  charts and models can be added in the same run
+- `--region REGION` (repeatable) / `--all-regions`: the regions the site serves (default: `[catalog] region`);
+  each region's master data is `[servers.<region>] master`. Regions with the same chart data share one manifest;
+  the chart list page switches region and language with `?region=&lang=`
+- `--player-only`: rewrite the player files, `charts.json` and `models.json` only; `--reingest-json`: store every
+  chart's and model's JSON files again under the current rules
+
+See [docs/commands.md](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/commands.md) for every command's options and output layout.
+
+## Architecture
+
+```
+settings (TOML / environment / flags)
+  └─ access    addressables (catalog parsing, bundle decryption, local browser)
+               catalog (dependency closures, remote and APK bundles, local cache)
+               master (master data download and decoding)
+               gameapi (anonymous game API calls: current master data version, server list)
+       └─ reading  unity (UnityPy type trees and TextAssets)
+                   export (prefabs / components / references resolved to JSON, textures and shaders alongside)
+                   shader, textstyle (text layout and style), tmpfont (TextMesh Pro fonts), player (boot settings), cri + crikey (CRI audio)
+            └─ content  stories: adv, advscene, advmedia (frames / effects / post effects / stills / chat),
+                                 advvideo (USM videos), advui, story
+                        Live2D: live2d, motion
+                        spots: spot, room
+                        charts: score (chart parsing and a reimplementation of the game's chart converter),
+                                livescene, livenotes, liveui, liveaudio, live
+                        site: web, webmodel (ournotes-player data)
+```
+
+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.
+
+## License
+
+MIT, see [LICENSE](https://github.com/MetaSekaiLab/nnnotes/blob/main/LICENSE).

nnnotes-0.1.0/README.en.md

@@ -0,0 +1,170 @@
+# nnnotes？！
+
+[简体中文](https://github.com/MetaSekaiLab/nnnotes/blob/main/README.md) | [English](https://github.com/MetaSekaiLab/nnnotes/blob/main/README.en.md)
+
+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 chart export is 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).
+
+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
+addresses in their own configuration, and the exports stay in local directories the user chooses.
+
+## Features
+
+| Command | Input | Output |
+|---|---|---|
+| `catalog` | the region's catalog | addressable keys (optionally by prefix) |
+| `browse` | the configured regions' catalogs | a local web page to browse catalogs and bundles (`--host` / `--port`) |
+| `pull` | addressable keys | every bundle of each key's dependency closure, decrypted into the local cache |
+| `servers` | the bootstrap API root `[bootstrap] api` | the game API's server list: each region's name, area id and CDN / API roots (the roots only with `--show-hosts`) |
+| `master version` | region | the master data version and resource version the region serves now (anonymous game API call) |
+| `master download` | master data version, or `--latest` (the region's current one) | that version's `MasterManifest.json` and every `.bin` file (SHA-256 checked) |
+| `master decode` | master data `.bin` files or directories | one JSON per table (Rijndael-256 CBC decryption + gzip) |
+| `adv` | episode ID | `episode.json`: command list, lines in five languages, voice / sound / video index |
+| `story` | episode ID | a full story directory: episode, every Live2D model, audio, stage scene and shaders, story UI, frames / particle effects / post effects / stills / talk windows / chat assets, videos (WebM) |
+| `live2d` | model key or model id | a Live2D (Cubism) runtime directory: moc3, textures, motion3, physics, expressions, prefab parameters |
+| `spot` | spot ID | `spot.json` + Spine characters + the room as `room.glb` + shaders |
+| `room` | background prefab key | the room model (binary glTF) |
+| `shader` | key or APK bundles | every platform variant of the shaders (GLSL ES and others) with an index |
+| `audio` | CRI cue sheet | one audio file per cue (FLAC / Ogg / WAV) + cue metadata |
+| `crikey` | APK | the CRI HCA keycode from the game's boot data (shows whether it was found; can write a `.hcakey`) |
+| `player` | APK | render-related global settings (color space, quality levels, renderers) as JSON |
+| `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; 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`) |
+| `deck-data` | master data files (`--master-files` directory or `--apk-master`) | one JSON file for deck-building tools: every chart's runtime notes, skill events and fever ranges, and the master data tables about cards, skills, bonuses, scores and events ([format](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/deck-data.md)) |
+
+Export conventions:
+
+- Commands that write files take the output path with `-o` (required); `web` takes the site directory as a
+  positional argument.
+- JSON is always UTF-8 with LF line endings; infinity is written as `1e999`.
+- Exports are deterministic for a given installation: the same input with the same versions of nnnotes, its Python
+  dependencies (UnityPy, Pillow, numpy, ...) and the external tools (vgmstream, FFmpeg) gives byte-identical files.
+  Other versions can encode the same content into other bytes: PNG files written by another Pillow version can
+  differ in their bytes while their pixels are equal.
+- Values keep Unity's serialized values and field names (`m_LocalPosition`, `_bandIDs`, ...), so they can be
+  compared with the game data.
+- Textures are exported as PNG, shaders keep the game's own compiled programs, audio is decoded from the CRI formats
+  to common formats.
+
+## Status
+
+Based on all data of the Taiwan server, version 1.0.1 (zh-Hant):
+
+| Part | Status |
+|---|---|
+| catalog / bundle decryption / dependency closure | working |
+| master data decoding | working |
+| stories, `adv` | 946 / 946 episodes |
+| stories, `story` (full directory) | 946 / 946 episodes have all their resources in the catalog and of supported kinds (the resource closure equals the game's own per-episode download list); 759 exported one by one, the other 187 (with frames, effects, post effects, stills and the like) not yet one by one |
+| Live2D models | 239 / 239 (every model of the catalog; episodes use 185 of them) |
+| CRI audio | 681 / 681 cue sheets |
+| charts, `live` | 336 / 336 (music, difficulty) pairs |
+| web site, `web` | 336 / 336 charts, 239 / 239 Live2D models, 946 / 946 story episodes (two full builds in English without audio are byte-identical and 946 / 946 pass the data validation; a 27-episode sample in five languages with AAC audio is likewise identical across two builds and valid) |
+| spots, `spot` / `room` | one spot verified, the others not individually checked |
+| other regions (en / kr) and languages | checked: the regions serve the same catalog for a language and the same bundles, and the keys are shared; the master tables the charts use are the same in the three regions, and the text tables have all five languages; the chart exports checked match the Taiwan server's. A full multi-region site build is not verified yet |
+
+## Requirements
+
+- Python 3.11+, 3.13 recommended (a `web` build reads and writes a lot of JSON, and the standard library encodes
+  JSON faster on 3.13); `pip install nnnotes` (for development `pip install -e .` in the repository)
+- the game's `base.apk`: APK-local bundles, the CRI keycode, boot settings. `player`, `story`, `live` and `web` read
+  MonoBehaviours of its boot data with type trees that ship with nnnotes; supported now: game version 1.0.1
+  (Unity 6000.3.12f1). With an APK of another version whose classes do not match, these commands stop with an
+  error naming the class, the game version and the Unity version
+- a decoded master data directory (from `master download` + `master decode`): needed by `adv`, `story`, `spot`,
+  `live` and the charts of `web`; the Live2D models of `web` use it only for their character names (optional)
+- external tools: [vgmstream](https://vgmstream.org/) (CRI HCA decoding), [FFmpeg](https://ffmpeg.org/)
+  (transcoding, including the WebM muxing and Opus audio of story videos); `web` also needs Node.js 20+ and a built
+  ournotes-player
+
+## Configuration
+
+The code contains no keys, server addresses or default paths. Settings are read in this order, later sources
+overriding earlier ones:
+
+1. config file: `--config <file>`, else `NNNOTES_CONFIG`, else `nnnotes.toml` in the working directory
+2. environment variables: `NNNOTES_<SECTION>_<KEY>` (e.g. `NNNOTES_BUNDLE_KEY`, `NNNOTES_SERVERS_TW_CDN`)
+3. command-line flags: `--region`, `--language`, `--catalog`, `--cache`, `--master`, `--apk`, `--ffmpeg`,
+   `--vgmstream`, `--node` go before the command name; `--player` is an option of `web`
+
+Copy [`nnnotes.example.toml`](https://github.com/MetaSekaiLab/nnnotes/blob/main/nnnotes.example.toml) to `nnnotes.toml` and fill it in. The settings are: the bundle
+key and nonce seed, the master data key and IV, the region in use (`[catalog] region`) and the catalog language
+(`[catalog] language`), the CDN base and API root of each region (`cdn`, `api` of `[servers.<region>]`), the client
+version (`[client] version`; unset: the APK's versionName), optionally the bootstrap API root (`[bootstrap] api`, for
+`servers`), and the paths of the cache, the APK, the master data directory, ournotes-player and vgmstream / FFmpeg /
+Node.js (the three tools are looked up on `PATH` when unset). All values come from the game client you own.
+
+A missing or malformed setting stops the command with exit status 2 and one line naming the TOML key, the
+environment variable and the flag; no setting value is printed. `nnnotes.toml` is in `.gitignore`; do not commit it.
+
+See [docs/configuration.md](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/configuration.md) for the full reference.
+
+## Examples
+
+```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 dir> --workers 5
+nnnotes web out/site --pair 100001:expert --pair 100001:hard --player <ournotes-player dir>
+nnnotes web out/site --all --region tw --region en --region kr --player <ournotes-player dir>
+nnnotes web out/site --live2d adv_live2d_rana_003_casual_spring_01 --player <ournotes-player dir>
+```
+
+`web` builds incrementally: charts and models whose manifest exists are skipped (`--force` rebuilds them) and assets
+no longer referenced are removed. Common options:
+
+- `--format aac|opus|vorbis|mp3|flac`: BGM format, default AAC; `--no-audio`: no audio files
+- `--band` / `--leader-card`: the band of the LightWeight background and the start timeline; default: the band of
+  the music's first vocal character
+- `--workers`: parallel music processes (default a quarter of the CPUs, up to 8) and model processes (default up
+  to 4); `--read-workers`: chart read sets at a time (Node.js processes; default half the CPUs, up to 16); `--tmp`:
+  temporary build directory (default `<site>.tmp`)
+- `--live2d MODEL` (model id or key, repeatable) / `--all-live2d`: add Live2D models (every model of the catalog);
+  charts and models can be added in the same run
+- `--region REGION` (repeatable) / `--all-regions`: the regions the site serves (default: `[catalog] region`);
+  each region's master data is `[servers.<region>] master`. Regions with the same chart data share one manifest;
+  the chart list page switches region and language with `?region=&lang=`
+- `--player-only`: rewrite the player files, `charts.json` and `models.json` only; `--reingest-json`: store every
+  chart's and model's JSON files again under the current rules
+
+See [docs/commands.md](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/commands.md) for every command's options and output layout.
+
+## Architecture
+
+```
+settings (TOML / environment / flags)
+  └─ access    addressables (catalog parsing, bundle decryption, local browser)
+               catalog (dependency closures, remote and APK bundles, local cache)
+               master (master data download and decoding)
+               gameapi (anonymous game API calls: current master data version, server list)
+       └─ reading  unity (UnityPy type trees and TextAssets)
+                   export (prefabs / components / references resolved to JSON, textures and shaders alongside)
+                   shader, textstyle (text layout and style), tmpfont (TextMesh Pro fonts), player (boot settings), cri + crikey (CRI audio)
+            └─ content  stories: adv, advscene, advmedia (frames / effects / post effects / stills / chat),
+                                 advvideo (USM videos), advui, story
+                        Live2D: live2d, motion
+                        spots: spot, room
+                        charts: score (chart parsing and a reimplementation of the game's chart converter),
+                                livescene, livenotes, liveui, liveaudio, live
+                        site: web, webmodel (ournotes-player data)
+```
+
+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.
+
+## License
+
+MIT, see [LICENSE](https://github.com/MetaSekaiLab/nnnotes/blob/main/LICENSE).

nnnotes-0.1.0/README.md

@@ -0,0 +1,132 @@
+# nnnotes？！
+
+[简体中文](README.md) | [English](README.en.md)
+
+nnnotes 是 BanG Dream! Our Notes 游戏文件的离线数据工具包：读取 Addressables catalog、下载并解密资源包、下载与解码 masterdata，再把剧情、Live2D、据点场景、着色器、CRI 音频和谱面导出成结构化的 JSON 与通用格式文件。谱面导出结果就是 [ournotes-player](https://github.com/empty-sekai/ournotes-player) 读取的数据。命名灵感来自 [mos9527/sssekai](https://github.com/mos9527/sssekai)。
+
+本项目为非官方爱好者项目，与游戏的开发和运营方无关。仓库不包含任何游戏资源、密钥或服务器地址：游戏文件、解密所需的密钥和服务器地址都由使用者在配置中自行提供，导出结果只保存在使用者指定的本地目录。
+
+## 功能
+
+| 命令 | 输入 | 输出 |
+|---|---|---|
+| `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、全部 Live2D 模型、音频、舞台场景与着色器、剧情 UI、Frame / 粒子特效 / 后处理 / 静帧 / 对话框 / 聊天资源、视频（WebM） |
+| `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 |
+| `live` | 曲目 ID + 难度 | 完整谱面目录：谱面与运行时音符、3D 场景、音符与特效资源、BGM 与音效、声音路由 |
+| `web` | `--pair 曲目:难度`（可重复）或 `--all`；`--live2d 模型`（可重复）或 `--all-live2d`；`--story 剧情 ID`（可重复）或 `--all-stories`；`--region 区服`（可重复）或 `--all-regions` | ournotes-player 静态站点：共享播放器 + 每谱 / 每模型 / 每集剧情清单 + 内容寻址资源；一个站点可服务多个区服，列表文本含五种语言；剧情的界面文字按语言分组，字形由开源字体生成 TextMeshPro 字体资源（`--fonts game` 时用游戏字体） |
+| `deck-data` | masterdata 文件（`--master-files` 目录或 `--apk-master`） | 供组卡工具读取的单个 JSON：每张谱面的运行时音符、技能事件与 fever 区间，以及卡牌、技能、加成、分数与活动相关的 masterdata 表（[格式](docs/deck-data.md)） |
+
+导出约定：
+
+- 写文件的命令都用 `-o` 指定输出路径（必填）；`web` 的站点目录是位置参数。
+- JSON 一律 UTF-8、LF 换行；无穷大写作 `1e999`。
+- 在同一套环境下导出是确定的：同样的输入，在 nnnotes、Python 依赖库（UnityPy、Pillow、numpy 等）和外部工具（vgmstream、FFmpeg）版本都相同时，导出文件逐字节相同。版本不同时，相同内容可能写成不同的字节：例如不同版本的 Pillow 写出的 PNG 像素相同，字节可能不同。
+- 数值保留 Unity 序列化值与字段名（`m_LocalPosition`、`_bandIDs` 等），便于与游戏数据对照。
+- 贴图导出为 PNG，着色器保留游戏自带的编译结果，音频由 CRI 格式解码为通用格式。
+
+## 完成度
+
+以下结果基于台服 1.0.1（zh-Hant）的全部数据：
+
+| 部分 | 状态 |
+|---|---|
+| catalog / 资源包解密 / 依赖闭包 | 可用 |
+| masterdata 解码 | 可用 |
+| 剧情 `adv` | 946 / 946 集可导出 |
+| 剧情 `story`（完整目录） | 946 / 946 集的资源都在 catalog 中且类型均受支持（资源闭包与游戏自带的每集下载清单一致）；已逐集导出验证 759 集，其余 187 集（用到 Frame / Effect / PostEffect / Still 等资源）未逐一验证 |
+| Live2D 模型 | 239 / 239 个可导出（catalog 中的全部模型，剧情用到其中 185 个） |
+| CRI 音频 | 681 / 681 个 cue sheet 可解码 |
+| 谱面 `live` | 336 / 336 个（曲目, 难度）组合可导出 |
+| 网页站点 `web` | 336 / 336 张谱面，239 / 239 个 Live2D 模型，946 / 946 集剧情（英语、无音频的全量构建两次结果逐字节一致，946 / 946 集通过数据校验；五种语言含 AAC 音频的 27 集抽样同样一致，并通过数据校验） |
+| 据点 `spot` / `room` | 已验证单个据点，其余未逐一验证 |
+| 其他区服（en / kr）与其他语言 | 已核对：各区服同一语言的 catalog 相同、资源包相同，密钥通用；谱面用到的 masterdata 表在三个区服间一致，文本表五种语言齐全；抽查的谱面导出与台服一致。多区服整站构建未做全量验证 |
+
+## 需要准备
+
+- Python 3.11+，推荐 3.13（`web` 构建读写大量 JSON，3.13 的标准库 JSON 编码更快），`pip install nnnotes`（开发时在仓库内 `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`
+2. 环境变量：`NNNOTES_<节>_<键>`（如 `NNNOTES_BUNDLE_KEY`、`NNNOTES_SERVERS_TW_CDN`）
+3. 命令行参数：`--region`、`--language`、`--catalog`、`--cache`、`--master`、`--apk`、`--ffmpeg`、`--vgmstream`、`--node` 写在命令名之前；`--player` 是 `web` 的参数
+
+复制 [`nnnotes.example.toml`](nnnotes.example.toml) 为 `nnnotes.toml` 后填写。需要的设置包括：资源包解密密钥与 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`），保证编码、换行与数值格式一致。
+
+`web` 构建的耗时分布，以及其中哪些部分已由编译代码执行，见 [docs/performance.md](docs/performance.md)。
+
+## License
+
+MIT，见 [LICENSE](LICENSE)。

nnnotes-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nnnotes"
+description = "Offline data toolkit for BanG Dream! Our Notes game files: catalogs, bundles, master data, stories, Live2D, audio and live charts"
+readme = "README.en.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "MetaMiku" }, { name = "emptysekai" }]
+dependencies = [
+    "UnityPy>=1.25",
+    "numpy>=2.0",
+    "Pillow>=10.0",
+    "pycryptodome>=3.20",
+    "grpcio>=1.49.1",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Multimedia",
+]
+dynamic = ["version"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pyflakes>=3.2", "jsonschema>=4.18"]
+fonts = ["fonttools>=4.50", "freetype-py>=2.5", "scipy>=1.13"]
+
+[project.scripts]
+nnnotes = "nnnotes.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/MetaSekaiLab/nnnotes"
+Source = "https://github.com/MetaSekaiLab/nnnotes"
+Issues = "https://github.com/MetaSekaiLab/nnnotes/issues"
+
+[tool.setuptools.dynamic]
+version = { attr = "nnnotes.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+nnnotes = ["typetrees/*.json", "viewrules.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

nnnotes-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nnnotes-0.1.0/src/nnnotes/__init__.py

@@ -0,0 +1,7 @@
+"""nnnotes: offline data toolkit for BanG Dream! Our Notes game files.
+
+Reads Addressables catalogs, fetches and decrypts asset bundles, decodes master data and exports stories, Live2D
+models, spots, shaders, CRI audio and live charts as JSON and common file formats. Game files, keys and server
+addresses are supplied by the user through the configuration; nothing of the game is included.
+"""
+__version__ = "0.1.0"

nnnotes-0.1.0/src/nnnotes/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()