UnheardCity/data/catalog/README.md

Sound catalog

file	content
<ARCHIVE>.csv	every sound of one audio archive: ITA, INT, FRA, DEU, ESN (speech, one per language) and SFX (music, ambience, effects of the SFX WAD; sounds stored inside soundbanks are not listed, see docs/formats/banks.md)
characters.csv	name,character: verified speaker per sound name (language independent)
index.json	fingerprint of the game WAD each CSV was built from (ackit/game.py: wad_fingerprint) and counts
source/<lang>/*.txt	the curated original lists (one file per character, one wemscan-style file name per line, e.g. Speech_TAPE_JOKER_1_4.wem). Files.txt = all files, Stats.txt = counts, Checkpoint.txt = progress marker. Never edited by tools.

All CSVs are UTF-8 with a header row. They contain only names and metadata (no game audio).

<ARCHIVE>.csv columns

column	meaning
archive	ITA, INT, ... or SFX
target	location inside the archive: HASH (entry with one WEM), HASH:i (i-th variation, 0-based), PACK/MEDIA (music stream pack)
name	display name (NAME, NAME_1..n for variations, see ackit/catalog.py)
aliases	other accepted names, |-separated (NAME_1 for single entries, NAME#i for variations)
group	Speech, Music, Ambience, SFX, Unknown (docs/categories.md)
category	finer category (docs/categories.md)
character	verified speaker(s) from characters.csv, ; -separated, empty if unknown
characters_inferred	characters/roles mentioned by the name (hint only)
seconds, rate, channels	of the original sound
size	size of the original WEM in bytes = maximum size of a replacement (except music packs: any size)
sha1	first 16 hex digits of the original WEM's SHA-1 (detects files changed outside the tool)
notes	free text (empty; for future curation, e.g. transcripts)

The editor uses these files directly when the installed WAD matches index.json; for another game build it scans the WAD itself and applies the same rules (no checksums then).

Rebuilding / adding a language

1. Make sure the game files are original (ackit status; ackit revert --all).
2. Optional: add listening-based lists for another language in source/<lang>/<Character>.txt (same format; names are the same in every language, so the Italian lists already label all languages).
3. Run python tools/build_catalog.py - it scans every archive of the installed game (all languages present) and rewrites the CSVs, characters.csv and index.json. New character labels need a display name in ackit/classify.py: USER_LABELS (otherwise the file name is used).