nnnotes

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. nnnotes site build writes the static site that ournotes-player plays, and nnnotes music-data one JSON file with every song and chart.

This is an unofficial fan project, not affiliated with the game's developer or operator. nnnotes contains no game assets, keys or server addresses: you supply the game files, the keys and the server addresses in your own configuration, and the exports stay in the local directories you choose.

Where to start

• Quick start

  From an empty config file to an exported story, step by step.

• How-to guides

  Configure nnnotes, export stories and lives, build an ournotes-player site, export every asset, the Japanese release, music data.

• Reference

  Commands, command outputs, JSON schemas, Python API, contracts, stages, views, replay data, UI library.

• Explanation

  Architecture, determinism, validation.

Install

pip install nnnotes                  # Python 3.11+
pip install 'nnnotes[fonts]'         # the game's fonts (--fonts game) and the story text of site build
pip install 'nnnotes[deck]'          # the deck model's chart statistics of music-data

Besides the package, nnnotes reads the game's base.apk and, for the commands that need it, decoded master data; audio and video need vgmstream and FFmpeg, and site build also Node.js 20+ and a built ournotes-player. Configuration lists what each command needs.

Versions

Versions follow Semantic Versioning. The interface a version describes is the command line (commands, options, exit statuses and the --json reports), the configuration keys, the JSON schemas shipped in nnnotes.schemas and the documented Python API. Before 1.0 a minor version can change any of them; the changelog names every change.