UnheardCity/REPORT.md

Report — repository cleanup and the editor, now Unheard City (mission 2)

What works (verified)

• Repository: clean layout (ackit/, app/, tests/, data/catalog/, docs/, tools/); old state in git tag pre-cleanup. One CLI (ackit) and one app (UnheardCity).
• Toolkit: portable encoder (libvorbis via libsndfile; no Wwise, ffmpeg or vgmstream), WAD/pack injector, originals store with byte-exact revert, conflict detection, mod packages, Steam/Linux/Proton game discovery.
• Catalog: CSVs for ITA/INT/FRA/DEU/ESN/SFX (11,467 sounds per speech language set), categories, verified speakers from the user's lists (3,366 lines in every language), inferred characters for the rest, original sizes and checksums. Schema in data/catalog/README.md.
• Editor: browse/search/filter, listen (A/B, loop, waveforms), replace from file or recording, trim/gain/ normalize/loudness, apply/revert/revert all, changed-underneath warnings, notes/tags/favorites, mod export/import, settings.
• Tests: 75 automated tests (synthetic game, real-game read-only tests, offscreen GUI tests) pass. ackit verify (offline self-check on the installed game) PASS.
• Real game: ackit verify --ingame PASS (ncc 1.0); tools/e2e_editor.py — replacement applied through the editor is heard in the game (ncc 1.0, no crash), revert leaves WAD and pack index byte-identical; a speech line applied and reverted byte-identically. Game files are original at the end.
• Package (Windows x86-64): dist/UnheardCity-2.0.0-windows-amd64.zip (78 MB) with THIRD_PARTY_LICENSES.txt; runs its smoke test and starts the GUI with PATH reduced to C:\Windows. Contains a per-user installer (Install.cmd): install, upgrade and uninstall (Settings > Apps) verified.

What is not verified / limitations

• Coverage: only sounds in the WAD archives are listed and editable. About 15,800 short effects (footsteps, foley, weapons, UI, grunts) are stored inside soundbanks (loose .bnk and banks embedded in .upk packages) and are not covered yet (docs/formats/banks.md).
• Speech lines being heard in the game needs gameplay; verified indirectly (same decoder/WAD path as the music test, byte-level apply/revert, boot test with modified speech WAD).
• Speech/effects replacements must fit the original's size (index lives in compressed .upk packages).
• Channel order for 4-6 channel sounds is unverified (tests used identical channels).
• Inputs: WAV/FLAC/OGG/OPUS/MP3/AIFF built in; M4A/AAC/WMA only with an ffmpeg installed on the system.
• Character labels outside the user's lists are inferred from names (marked as such), not verified speakers.

Next steps

1. Support the in-memory sounds in soundbanks: the loose footstep banks first, then the banks embedded in .upk packages (docs/formats/banks.md).
2. Extend the curated speaker lists (data/catalog/source/<lang>/*.txt) and rebuild with tools/build_catalog.py.
3. Optional: rewrite the BKPK indexes inside .upk packages (LZO) to lift the size limit for speech.