Skip to main content

nnnotes

English | 简体中文

nnnotes turns your BanG Dream! Our Notes game files into structured data, media and static player sites. It reads Addressables catalogs, bundles, master data and APK resources; exports stories, Live2D models, live charts, rooms, UI, shaders and audio; and assembles sites for ournotes-player.

A persistent depot stores converted objects, task results and catalog versions. Exports share these results, and named sites retain their selected products across builds. A depot can also share work through a directory or S3-compatible object storage.

Documentation · Quick start · Commands

Install

Python 3.11 or newer:

pip install nnnotes==0.3.1
pip install 'nnnotes[fonts]==0.3.1'    # story and UI fonts
pip install 'nnnotes[remote]==0.3.1'   # S3-compatible depot storage
pip install 'nnnotes[deck]==0.3.1'     # music-data chart statistics

Choose the extras your commands need; they can be combined as nnnotes[fonts,remote,deck]==0.3.1. Audio/video conversion uses vgmstream and FFmpeg. Site builds additionally require Node.js 22+ and a built ournotes-player 0.2.x package. The deck extra installs ournotes-sim==0.0.12.

First export

Supply your own client files, keys and server addresses through the configuration wizard:

nnnotes config init --user
nnnotes config check
nnnotes master download --latest -o work/master-bin
nnnotes master decode work/master-bin -o work/master
nnnotes config set paths.master work/master
nnnotes export episode 10462 -o out/episode.json
nnnotes export story 10462 --fonts game -o out/story

Set paths.depot to a persistent directory and paths.apk to your game APK. The wizard reads keys without echo; config check reports setting names, origins and validity. Story export requires the fonts extra and audio tools. See the quick start for prerequisites and output layout.

Build a player site

npm install ournotes-player@0.2.0
nnnotes site build --name stories -o out/site --story 10462 --fonts game --player node_modules/ournotes-player
node node_modules/ournotes-player/scripts/validate-data.mjs out/site
python -m http.server 8000 --directory out/site

Open http://localhost:8000/story/. Live2D, MotionSync and Spine features require the corresponding browser runtimes supplied by the embedding page. See the site guide. Use --pair MUSIC_ID:DIFFICULTY for a chart, --live2d KEY for a model, and --story-languages ja,en for selected story languages. Reusing a site name updates selected topics and retains the others.

Choose a workflow

Task Commands Guide
Configure inputs config init, config check, servers Configuration
Inspect or retain catalogs catalog keys, browse, versions, import, fetch, diff Commands
Copy source bundles bundle pull Asset export
Package songs and audio pack plan, pack build, pack verify, pack audio Song packing
Export a subject export episode, story, live, live2d, spot, room, shader, audio, ui Exports
Convert selected assets export assets, depot plan, depot run Asset export
Check and retain stored work depot verify, depot gc Depot
Export song and chart statistics music-data Music data
Find character voices voices list, search, summary, get Commands

Commands print summaries; --json selects a structured report. The reference describes exit statuses and options.

Data and compatibility

Product exports use versioned manifests and shared object records. Read the format reference, product reference and schemas to consume them. Task identities include input contents, options and conversion implementations, including native encoders. Byte-identical output requires matching inputs and library/tool implementations, including Pillow and its native compression backend. JSON uses UTF-8 and LF; infinite values use 1e999 or -1e999. Determinism explains reproducibility across installations.

Versions cover the CLI, configuration, schemas and documented Python API. Before 1.0, a minor version can change these interfaces. See CHANGELOG.md and the architecture.

Contributing and license

CONTRIBUTING.md describes development and synthetic tests. nnnotes is licensed under MIT. This is an unofficial fan project, unaffiliated with the game's developer or operator. Game resources, keys and server configuration are supplied by each user and are subject to their owners' rights.

Metadata

Release files for nnnotes 0.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nnnotes 0.3.2
File Size Uploaded Provenance Actions
nnnotes-0.3.2.tar.gz 1.2 MB With provenance Details for nnnotes-0.3.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nnnotes 0.3.2
File Interpreter ABI Platform Actions
nnnotes-0.3.2-py3-none-any.whl Python 3 none any Details for nnnotes-0.3.2-py3-none-any.whl

Total release size: 1.9 MB

Release files / nnnotes-0.3.2.tar.gz

Download URL nnnotes-0.3.2.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
cf35d977fc1893232c41e1ae8953974b43e13dd3f2f7b59c74622a6d59a978a0
BLAKE2b-256 checksum
How to use checksums
ac3c7f940bca3702a6a3dc472f889f711342aa362839a3a1a38d53b299b47db2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / nnnotes-0.3.2-py3-none-any.whl

Download URL nnnotes-0.3.2-py3-none-any.whl
Size 733.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f954e74e0927a310751460b8093442a150c0afd034702fa44eb6af63da9320df
BLAKE2b-256 checksum
How to use checksums
2ca52d5d90e53acea0d9a0a671c23c1130c88a0fedf1b8b49a3727bb2a393f0e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for nnnotes 0.3.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for nnnotes-0.3.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page