cli.md

Command reference

Every command of nnnotes, its arguments and their defaults. The global options go before or after the command name. A command prints a short summary on standard output, or with --json its report as JSON; notes and errors go to standard error. Exit status 2 is a usage or settings error.

Global options

Argument	Description
--config FILE	TOML config file (else NNNOTES_CONFIG, else ./nnnotes.toml)
--region REGION	region: a [servers.] table ([catalog] region)
--language LANG	catalog and client language: ja, en, zh-Hant, zh-Hans or ko ([catalog] language)
--catalog FILE	catalog .bin file ([paths] catalog; else downloaded into the depot)
--catalog-version VERSION	the resource version of an international catalog ([catalog] version; else the version the game API serves when an API root is configured, otherwise main)
--depot DIR	depot directory ([paths] depot)
--master DIR	decoded master data directory ([paths] master)
--apk FILE	base.apk ([paths] apk)
--ffmpeg EXE	ffmpeg executable ([paths] ffmpeg; else on PATH)
--ffprobe EXE	ffprobe executable ([paths] ffprobe; else on PATH)
--vgaudio FILE	VGAudioCli executable or .NET DLL ([paths] vgaudio; else on PATH)
--vgmstream EXE	vgmstream-cli executable ([paths] vgmstream; else on PATH)
--node EXE	Node.js executable ([paths] node; else on PATH)
--json	print the command's report as JSON on standard output (default: a short summary)

nnnotes config init

write a config file from the template: the values are asked in a terminal, else taken from --set (the other settings empty)

Argument	Description
--file FILE	the config file to write (default: the file --config or NNNOTES_CONFIG names, else ./nnnotes.toml)
--user	write the per-user config file, read from any directory (config path shows it)
--set SECTION.KEY=VALUE	a value to write (repeatable; no questions then): VALUE - reads it from standard input; a list comma-separated; a path is written absolute
--no-input	ask nothing, also in a terminal
--force	overwrite an existing file

At most one of --file, --user.

nnnotes config set

set one value of the config file the commands read (or of --file / --user; a missing one is made from the template); comments and other lines stay

Argument	Description
SECTION.KEY	the setting: bundle.key, servers.tw.cdn, paths.fonts.ja, ...
value	the value (a list comma-separated); - reads it from standard input, without echo for the keys in a terminal
--file FILE	the config file to edit
--user	edit the per-user config file, read from any directory (config path shows it)

At most one of --file, --user.

nnnotes config unset

empty one value of the config file (an empty value counts as unset)

Argument	Description
SECTION.KEY	the setting
--file FILE	the config file to edit
--user	edit the per-user config file, read from any directory (config path shows it)

At most one of --file, --user.

nnnotes config check

every setting: where it comes from and whether it is valid, never its value; exit status 1 when one is invalid, not found or unknown (--json: nnnotes.config-check/1)

nnnotes config path

the config files looked up, in order, and the one the commands read (--json: nnnotes.config-path/1)

nnnotes servers

the server list of the bootstrap API root: regions, their CDN and API roots

Argument	Description
--show-hosts	print the CDN and API roots, not only their counts

nnnotes catalog keys

the addressable keys of the catalog (the total on standard error)

Argument	Description
--prefix PREFIX	only the keys that start with this prefix (default ``)
--limit LIMIT	at most N keys (default 200; 0: all)

nnnotes catalog browse

browse the configured regions' catalogs and bundles in a local web page

Argument	Description
--port PORT	port (default 8000)
--host HOST	address to listen on (default 127.0.0.1)

nnnotes catalog versions

the catalog versions imported into the depot (--json: nnnotes.catalogs/1)

nnnotes catalog import

import a catalog file (with the APK's catalog when [paths] apk is set)

Argument	Description
file	catalog__.bin
--label LABEL	label of the version (default: its resource version, else the sha256 prefix)
--apk-catalog APK_CATALOG	the APK's catalog.bin (default: read from [paths] apk)
--resource-version RESOURCE_VERSION	the game's resource version of this catalog (default: the JP source's version, else the version in the file name catalog__.bin)

nnnotes catalog fetch

fetch the region's current catalog and import it into the depot

Argument	Description
--label LABEL	label of the version (default: the resource version when an API root is set)

nnnotes catalog diff

keys, bundles, raw files (and objects) that differ between two catalog versions of the depot (--json: nnnotes.catalog-diff/1)

Argument	Description
old	label, version id or sha256 prefix
new	label, version id or sha256 prefix

nnnotes catalog rebuild

write a catalog with added locations (--add), removed primary keys (--drop) and updated bundle request options (--bundle)

Argument	Description
CATALOG	the catalog to read (catalog__.bin)
-o, --out OUT	the catalog to write (required)
--add FILE	JSON location entries or bundle descriptions with file, internal_id, bundle_name and assets; bundle descriptions generate crc, bundleSize and a cache hash from the bundle (repeatable)
--drop KEY	drop every location of this addressable key (repeatable)
--bundle FILE	write this bundle's decompressed content crc, stored bundleSize and deterministic cache hash (MD5 of the UnityFS bytes) into matching existing or added locations (repeatable)
--hash HASH	override the generated cache hash for one --bundle with 32 hexadecimal digits

nnnotes bundle pull

fetch the bundle closure of keys and copy the decrypted bundles to a directory (prints the bundle files)

Argument	Description
KEY ...	addressable keys (catalog keys lists them)
-o, --out OUT	directory the bundles are copied to, under their file names (required)

nnnotes master version

the master data and resource version the region serves now (game API)

nnnotes master decode

master data .bin files ->

.json

Argument	Description
inputs ...	directories (their *.bin files) or files
-o, --out OUT	output directory (required)
--workers N	parallel decodes (default the CPUs this process may use; 0: one at a time)

nnnotes master download

a master data version from the region's CDN (SHA-256 checked)

Argument	Description
--version VERSION	master data version
--latest	the version the region serves now (master version)
-o, --out OUT	directory for MasterManifest.json and the .bin files (required)
--fetch-workers N	parallel downloads (default 16)

Exactly one of --version, --latest.

nnnotes pack plan

check a song project and its local resource dependencies

Argument	Description
file	nnnotes.song-package/1 JSON project

nnnotes pack verify

verify a generated song package against its local baseline

Argument	Description
directory	directory containing package.json
--target TARGET	nnnotes.pack-target/1 JSON target (required)

nnnotes pack audio

MP3/WAV/FLAC/AAC -> a validated single-cue HCA ACB

Argument	Description
source	local source audio file
-o, --out OUT	output ACB file (required)
--target TARGET	JSON target with local ACB templates and cipher settings (required)
--template TEMPLATE	target ACB profile (default full) (one of full, preview)
--cue-name CUE_NAME	name of the output cue and sheet (required)
--report REPORT	validation JSON path (default .json)
--sample-rate SAMPLE_RATE	output sample rate (default preserve input) (one of 44100, 48000)
--channels CHANNELS	output channels (default preserve input) (one of 1, 2)
--stream STREAM	source audio stream index when the file contains several tracks
--gain-db GAIN_DB	explicit PCM gain in decibels (default 0)
--start-ms START_MS	crop start on the decoded timeline (default 0)
--duration-ms DURATION_MS	crop duration; omitted keeps the remainder
--fade-in-ms FADE_IN_MS	linear fade-in duration (default 0)
--fade-out-ms FADE_OUT_MS	linear fade-out duration (default 0)
--quality QUALITY	HCA encoder quality preset (default high) (one of highest, high, middle, low, lowest)

nnnotes pack master

master data tables (.json) ->

.bin (Rijndael-256-CBC over gzip JSON)

Argument	Description
inputs ...	directories (their *.json files) or files
-o, --out OUT	output directory (required)
--prefix-from BIN	copy the 64-byte prefix of this master data file (the loader ignores it; a replacement should keep it)
--manifest VERSION	also write MasterManifest.json (the file master download reads) for this master data version

nnnotes pack bundle

UnityFS bundles -> the form the CDN serves (AES-128-CTR, first 16 KiB)

Argument	Description
inputs ...	directories (their bundles) or files
-o, --out OUT	output directory (required)
--suffix SUFFIX	the file name suffix bundles have among the inputs (default .bundle)
--name NAME	the file name the bundle is served under (it seeds the nonce; default: the input's name)

nnnotes pack asset

replace a binary TextAsset in a bundle; --new-name changes its object name

Argument	Description
bundle	the bundle to copy
-o, --out OUT	output bundle (required)
--name NAME	the TextAsset's name inside the bundle (required)
--data DATA	the file whose bytes become the asset's payload (required)
--new-name NEW_NAME	also rename the object; its container path is preserved

nnnotes pack build

build a song package or a UnityFS bundle from a JSON manifest

Argument	Description
file	song project or asset manifest with template, mode and asset operations
-o, --out OUT	new song package directory, or output UnityFS bundle (required)
--encrypt FILE	also write the encrypted bundle to this file
--name NAME	served file name used for encryption and catalog validation
--catalog-add JSON	also write a manifest accepted by catalog rebuild --add
--catalog-out FILE	rebuild the --catalog source with the bundle's locations

nnnotes export assets

every object of the selected bundles -> common formats (the depot and its layouts)

Argument	Description
-o, --out OUT	output directory (required)
--select SEL	group:, key: or bundle: (repeatable; default: everything)
--views all|none|a,b	semantic views to build (default: all when master data is set, else none)
--stored-catalog LABEL|SHA	a catalog version of the depot (catalog versions; default: the current catalog)
--png-level N	PNG compression level 0-9 (changes the output)
--flac-level N	FLAC compression level 0-12 of the CRI audio (default 8; every level decodes to the same samples; changes the files)
--only-class C,...	export only the units whose root object is of these classes
--workers N	worker processes (default: the CPUs this process may use; 0: this process)
--memory GiB	memory budget of the running tasks and workers (default: 80 % of the physical memory)
--fetch-workers N	parallel downloads (default 8)
--layout LAYOUT	original, cas, product, comma-separated (default original; product: the products of the selection)
--explain	print every setting of the run first
--link LINK	how the layout files are made from the depot: auto (default; [export] link): a clone where the file system makes them, else a hard link (read-only), else a copy; or that method only (one of auto, clone, hard, copy)
--strict	exit 1 when a view has gaps
--dry-run	print the plan, run nothing

nnnotes export episode

an ADV episode -> JSON

Argument	Description
adv_id	MasterAdv id of the episode
-o, --out OUT	output .json file (required)

nnnotes export story

an ADV episode -> the story product and the products it plays with (scene, assets, Live2D models, cue sheets, videos, chat, UI, fonts, CRI Lips)

Argument	Description
adv_id	MasterAdv id of the episode
--story-languages LANG,...	text languages, comma-separated (default: [catalog] language)
--fonts FONTS	glyph source: open font files (default) or game TMP assets (one of open, game)
--font LANG=PATH	font file for a language, or emoji=PATH (repeatable; [paths] fonts.)
--format FORMAT	web audio format of the cue sheets (default aac) (one of aac, flac, mp3, opus, vorbis)
--flac-level N	FLAC compression level 0-12 of the decoded sounds (default 8; every level decodes to the same samples)
-o, --out OUT	output directory (required)
--stored-catalog LABEL|SHA	a catalog version of the depot (catalog versions; default: the current catalog)
--workers N	worker processes (default: the usable CPUs)
--link LINK	as export assets --link (one of auto, clone, hard, copy)
--explain	print every setting of the run first
--dry-run	print the plan, run nothing

nnnotes export live

a live (music + difficulty) -> the live product and the products it plays with (scene, note highway, sounds, music)

Argument	Description
music_id	MasterLiveMusic id
--difficulty DIFFICULTY	chart difficulty (default expert) (one of easy, normal, hard, expert)
--format FORMAT	web audio format of the BGM (default aac) (one of aac, flac, mp3, opus, vorbis)
--flac-level N	FLAC compression level 0-12 of the decoded sounds (default 8; every level decodes to the same samples)
--band BAND	band of the LightWeight background and start timeline (default: band of the music's first vocal character)
--leader-card LEADER_CARD	deck centre MasterMemberCard id (its character's band)
--live-option OPTION[=VALUES]	also export the files of a Live option's variants (repeatable): MirrorChart, MeasureLineDisplay, NoteDesignId, NoteEffectId, LiveQuality, NoteSePatternId (every value of the master data, or =v,v...), defaults (the option defaults and ranges only) or all
--live-languages CODES	comma-separated UI languages, or all (default: catalog language)
--fonts FONTS	glyph source: open font files (default) or game TMP assets (one of open, game)
--font LANG=PATH	font file for a language (repeatable; [paths] fonts.)
-o, --out OUT	output directory (required)
--stored-catalog LABEL|SHA	a catalog version of the depot (catalog versions; default: the current catalog)
--workers N	worker processes (default: the usable CPUs)
--link LINK	as export assets --link (one of auto, clone, hard, copy)
--explain	print every setting of the run first
--dry-run	print the plan, run nothing

At most one of --band, --leader-card.

nnnotes export live2d

a Live2D model -> its Cubism SDK files, or the player's model

Argument	Description
key	model key Character/Live2D///model/, or its model id
-o, --out OUT	output directory (required)
--player	write the player's model (models/.json and assets/) instead of the Cubism SDK files
--stored-catalog LABEL|SHA	a catalog version of the depot (catalog versions; default: the current catalog)
--workers N	worker processes (default: the usable CPUs)
--link LINK	as export assets --link (one of auto, clone, hard, copy)
--explain	print every setting of the run first
--dry-run	print the plan, run nothing

nnnotes export spot

a spot -> spot.json + Spine files + room.glb + room.json

Argument	Description
spot_id	MasterHomeSpot id
-o, --out OUT	output directory (required)
--stored-catalog LABEL|SHA	a catalog version of the depot (catalog versions; default: the current catalog)
--workers N	worker processes (default: the usable CPUs)
--link LINK	as export assets --link (one of auto, clone, hard, copy)
--explain	print every setting of the run first
--dry-run	print the plan, run nothing

nnnotes export room

a spot background -> room.glb + room.json

Argument	Description
key	background key Spot//Background/
-o, --out OUT	output directory (required)
--stored-catalog LABEL|SHA	a catalog version of the depot (catalog versions; default: the current catalog)
--workers N	worker processes (default: the usable CPUs)
--link LINK	as export assets --link (one of auto, clone, hard, copy)
--explain	print every setting of the run first
--dry-run	print the plan, run nothing

nnnotes export shader

the shaders of a key's bundle closure or of APK bundles

Argument	Description
--key KEY	addressable key: the shaders of its bundle closure
--apk-bundle APK_BUNDLE ...	substring(s) of APK bundle file names
-o, --out OUT	output directory (required)

Exactly one of --key, --apk-bundle.

nnnotes export audio

a CRI cue sheet -> audio files

Argument	Description
cue_sheet	cue sheet name: the key Cri/Sound/<cue_sheet> of the catalog
-o, --out OUT	output directory (required)
--format FORMAT	audio file format (default flac) (one of flac, ogg, wav)
--flac-level N	FLAC compression level 0-12 of --format flac (default 8; every level decodes to the same samples)

nnnotes export ui

the APK's UI prefabs -> an offline UI prefab library for ournotes-player/ui

Argument	Description
-o, --out OUT	UI data directory outside the source repositories (required)
--key KEY	exact APK catalog key (repeatable)
--prefix PREFIX	APK UI key prefix (default EmbUI/)
--limit LIMIT	maximum number of keys
--stored-catalog LABEL|SHA	a catalog version of the depot (catalog versions; default: the current catalog)
--workers N	worker processes (default: the usable CPUs)
--link LINK	as export assets --link (one of auto, clone, hard, copy)
--explain	print every setting of the run first
--dry-run	print the plan, run nothing

nnnotes apk settings

the player's graphics settings (color space, quality levels) -> JSON

Argument	Description
-o, --out OUT	output .json file (required)

nnnotes apk hca-key

find the HCA keycode of the CRI audio (never printed)

Argument	Description
--write DIR	write it as DIR/.hcakey (the file vgmstream reads)

nnnotes depot plan

what export assets would run and why, without running it (--json: nnnotes.plan/1)

Argument	Description
-o, --out OUT	output directory of the export (counts the layout files to write)
--select SEL	group:, key: or bundle: (repeatable; default: everything)
--views all|none|a,b	semantic views to build (default: all when master data is set, else none)
--stored-catalog LABEL|SHA	a catalog version of the depot (catalog versions; default: the current catalog)
--png-level N	PNG compression level 0-9 (changes the output)
--flac-level N	FLAC compression level 0-12 of the CRI audio (default 8; every level decodes to the same samples; changes the files)
--only-class C,...	export only the units whose root object is of these classes
--workers N	worker processes (default: the CPUs this process may use; 0: this process)
--memory GiB	memory budget of the running tasks and workers (default: 80 % of the physical memory)
--fetch-workers N	parallel downloads (default 8)
--layout LAYOUT	original, cas, product, comma-separated (default original; product: the products of the selection)
--explain	print every setting of the run first
--since RUN	explain against this run (default: the latest of the selection)
--check	exit 1 when anything would run or change
--census	first fetch and census the bundles without one
--emit-tasks DIR	write the runnable tasks as task descriptions
--why TASK	the reasons and key parts of one task

nnnotes depot run

run task descriptions (nnnotes.task/1) into the depot

Argument	Description
TASK ...	task description files, or directories of them
--fetch	fetch inputs through their catalog locators
--force	run tasks whose result is stored (it must not change)

nnnotes depot verify

check every stored content and result

Argument	Description
--quick	check sizes only, do not hash the contents
--workers N	parallel hashing (default the CPUs this process may use; 0: one at a time)

nnnotes depot gc

remove the runs, results and contents no kept run reaches

Argument	Description
--keep N	keep the N latest runs of each selection (default: every run; the latest run of a selection is kept)
--dry-run	count what would be removed, remove nothing
--grace SECONDS	keep recent results and their inputs and contents in both depots (default: 86400 seconds)
--remote	also collect the depot's remote, by its runs (its results and contents younger than a day stay)

nnnotes voices list

the voices matching the filters (the text column in the --language language, default [catalog] language)

Argument	Description
--from OUT	an export directory with views/voices.json (export assets --views voices); else the index is built from the configured master data and catalog (no files)
--character CHARACTER	a MasterCharacter id or a part of a name in any language
--category CATEGORY	a category (CharacterRankUp or character-rank-up), Source.Category or a source
--source SOURCE	a source (Talk, CharacterVoice, ..., HomeSpot, Title, Sound, Story)
--episode ADV	the Story voices of one episode: a MasterAdv id or an episode asset (without --from: read from the catalog)
--status STATUS	only the rows with this status (one of ok, missing-cue, missing-key, not-exported, unsupported, no-value)
--limit LIMIT	at most N rows (0: all)

nnnotes voices search

the voices whose text (or cue name) contains TEXT

Argument	Description
text	text to look for
--from OUT	an export directory with views/voices.json (export assets --views voices); else the index is built from the configured master data and catalog (no files)
--character CHARACTER	a MasterCharacter id or a part of a name in any language
--category CATEGORY	a category (CharacterRankUp or character-rank-up), Source.Category or a source
--source SOURCE	a source (Talk, CharacterVoice, ..., HomeSpot, Title, Sound, Story)
--episode ADV	the Story voices of one episode: a MasterAdv id or an episode asset (without --from: read from the catalog)
--status STATUS	only the rows with this status (one of ok, missing-cue, missing-key, not-exported, unsupported, no-value)
--limit LIMIT	at most N rows (0: all)
--search-language SEARCH_LANGUAGE	search this language only (default: all five) (one of ja, en, zh-Hant, zh-Hans, ko)

nnnotes voices summary

rows per status, category and character; gaps both ways

Argument	Description
--from OUT	an export directory with views/voices.json (export assets --views voices); else the index is built from the configured master data and catalog (no files)

nnnotes voices get

the files of one voice: a row id (MasterTalk:561, MasterAdv::) or a sound id

Argument	Description
id	row id or sound id
-o, --out OUT	output directory (required)
--from OUT	an export directory with views/voices.json (export assets --views voices); else the index is built from the configured master data and catalog (no files)
--format FORMAT	flac (default: the exported files when --from has them), ogg or wav (decodes the sheet) (one of flac, ogg, wav)
--flac-level N	FLAC compression level 0-12 of --format flac: decode the sheet at this level, also with --from (default 8; every level decodes to the same samples)

nnnotes site build

live charts, Live2D models and stories -> static site for ournotes-player (shared player + per-chart / per-model / per-story data)

Argument	Description
-o, --out SITE	site directory (required)
--name NAME	persistent site name in the depot (default: default)
--player PLAYER	ournotes-player checkout (built) or installed package ([paths] player)
--pair PAIR	: (repeatable)
--all	every MasterLiveMusic x difficulty
--player-only	publish the saved catalog with current player pages
--live2d MODEL	Live2D model id or key Character/Live2D///model/ (repeatable)
--all-live2d	every Live2D model of the catalog
--format FORMAT	audio format of the charts and stories (default aac) (one of aac, opus, vorbis, mp3, flac)
--no-audio	export no audio files
--compress COMPRESS	encoding of the compressible assets (JSON, shaders, moc3, ...) where it makes them smaller: gzip (default), br (brotli) or none (one of gzip, br, none)
--workers N	product task worker processes; 0: this process
--memory GiB	product task memory budget
--fetch-workers N	parallel source downloads
--stored-catalog LABEL|SHA	a stored catalog version of the depot
--story ADV_ID	story episode: its MasterAdv id (repeatable)
--all-stories	every story episode (MasterAdv) of the master data
--story-languages LANGS	languages of the stories' text, comma-separated (default: the catalog language)
--font LANG=PATH	font file the story text of a language is drawn with (repeatable; [paths] fonts.); emoji=PATH: the colour emoji font the emoji sprites are drawn from ([paths] fonts.emoji)
--site-region REGION	a region the site serves: a [servers.] table (repeatable; the first is the base; default: [catalog] region)
--all-regions	every configured region
--fonts FONTS	text of the start canvas and stories: open (default): glyphs from your font files (--font); game: the game's TMP fonts (needs the 'fonts' extra) (one of open, game)
--band BAND	band of the LightWeight background and start timeline (default: band of the music's first vocal character)
--leader-card LEADER_CARD	deck centre MasterMemberCard id (its character's band)
--live-option OPTION[=VALUES]	also export the files of a Live option's variants (repeatable): MirrorChart, MeasureLineDisplay, NoteDesignId, NoteEffectId, LiveQuality, NoteSePatternId (every value of the master data, or =v,v...), defaults (the option defaults and ranges only) or all

At most one of --pair, --all, --player-only.

At most one of --live2d, --all-live2d.

At most one of --story, --all-stories.

At most one of --site-region, --all-regions.

At most one of --band, --leader-card.

nnnotes music-data

every live song and chart: metadata in every language, chart facts and the deck model's chart statistics -> one JSON file

Argument	Description
--master-files DIR	master data files as served: MasterManifest.json and the .bin files it lists (master download)
--apk-master	the master data files of base.apk ([paths] apk)
--decoded-master	decoded master data ([paths] master or --master) with the MasterManifest.json of the files it was decoded from; no master key
--full	also write the deck model's input: every chart's runtime notes and the master data tables about cards, skills, bonuses, scores and events
--no-deck	do not run the deck model (every chart's deck is null)
--seeds N	replay seeds for a chart with a luck range (default 8); expectations do not use sampling
--workers N	threads measuring charts (default: every processor; 0: one thread)
--no-gekisou-aptitude	leave out the charts' Gekisou aptitude (every gekisouAptitude is null)
--stats-cache DIR	reuse native simulation programs and runs in DIR across builds; completed cache entries survive interrupted builds
--no-bgm	do not read the BGM cue sheets (every song's bgm.length is null)
--replay-dir DIR	write canonical runtime DeckData, per-chart inputs and replay manifest under the output directory
--replay-engine PKG	the deck model's replay WASM release package (ournotes-replay-wasm-vVERSION.tar.gz or its directory); its web JS/WASM and build-info.json are copied into --replay-dir
--recommend-engine PKG	the deck model's recommendation WASM release package (ournotes-recommend-wasm-vVERSION.tar.gz or its directory); its web JS/WASM and build-info.json are copied into --replay-dir
--jackets DIR	also write every song's jacket as DIR/.webp (at most 320 px on the longer side)
-o, --out OUT	output file (.json, or .json.gz for gzip) (required)

Exactly one of --master-files, --apk-master, --decoded-master.