Document soundbank findings

docs/README.md

@@ -7,6 +7,7 @@
 | [categories.md](categories.md) | group/category scheme and character fields |
 | [building.md](building.md) | building the editor and its installer (Windows, Linux) |
 | [formats/wad.md](formats/wad.md) | WWAD archives, grouped entries, BKPK stream packs |
+| [formats/banks.md](formats/banks.md) | soundbanks and the in-memory sounds not covered yet (footsteps, foley, effects) |
 | [formats/wem.md](formats/wem.md) | WEM layout the game accepts, setup stripping, hash and decode-alloc formulas |
 | [reverse-engineering/decoder.md](reverse-engineering/decoder.md) | BatmanAC.exe decoder functions and addresses |
 | [reverse-engineering/findings.md](reverse-engineering/findings.md) | root cause, findings, in-game experiment log (incl. failed hypotheses) |

docs/formats/banks.md

@@ -0,0 +1,65 @@
+# Soundbanks and in-memory sounds
+
+Most short sound effects (footsteps, foley, combat, weapons, objects, UI, grunts) are **not in the WADs**: they
+are WEMs stored inside Wwise soundbanks, either loose in `SFX\*.bnk` or embedded in the UE3 packages (`.upk`).
+The catalog and the editor only cover the WADs (`wad.md`), so none of these sounds are listed or editable yet.
+Survey of the installed game (buildid 3718300) on 2026-10-09, read-only.
+
+## Inventory
+
+| where | banks | unique in-memory WEMs | in the catalog |
+|-------|-------|-----------------------|----------------|
+| loose `SFX\*.bnk` (Batman/Catwoman footsteps, 32 surfaces each, + `TST_Prep_Media`) | 65 | 1,117 | 0 |
+| banks embedded in `.upk` packages (in 1,432 of the 2,650 packages) | 3,340 | 15,641 (~276 MB) | 0 |
+
+The two sets share 119 media IDs: about **15,800 unique sounds** in total. The WADs, by comparison, are fully
+covered: the BKPK tables in the packages reference 2,543 WAD entries, all of them in the catalog.
+
+Embedded WEMs by bank name prefix: `Speech` 7,872, `CHR` (character foley, combat, bosses) 3,896, `PSO` 781,
+`WPN` 664, `NPC` 475, `OBJ` 439, `SEQ` 265, `GUI` 208, `PSA` 203, `MTN` 196, `PX` 195, `DVC` 100, `GEN` 80,
+`PHY` 73, `AMB` 65, `SBJ` 50, others < 30. The `Speech_` banks (e.g. `Speech_EMOTE_Batman`, `..._GRUNT`) are
+probably efforts/grunts rather than dialogue (there are no per-language packages); not verified by listening.
+All WEMs seen are Vorbis (format tag 0xFFFF), the same codec as the WADs: the footsteps are mono (4 stereo),
+the embedded ones mono or stereo (~22 % stereo in a 2,533-WEM sample).
+
+## Names
+- The community hash list names none of these media IDs; only the bank names are known.
+- `CookedPCConsole\CookedBanks.txt` lists all 3,345 cooked bank names. Bank ID = FNV-1 32 of the lowercased
+  name (the same hash Wwise uses for every name). 3,338 of them are embedded in packages, 4 are loose `.bnk`
+  files (`Init`, `Global`, `Music`, `Music_PDLC`); `AMB_OW_A6`, `AMB_OW_C1`, `AMB_OW_E1`,
+  `Speech_EMOTE_Thug_Muffled_Stop` and `Speech_GFxUI_ArkhamCityStories` were found nowhere.
+- Loose footstep banks are named in their STID chunk (`CHR_BatmanFootsteps_Concrete_Media`, ...).
+
+## Bank layout (version 56, Wwise 2011.1)
+Chunks `BKHD` {u32 version 56, u32 bank id, ...}, `DIDX` N x {u32 media id, u32 offset, u32 size} (offsets
+relative to the `DATA` payload, WEMs 16-byte aligned), `DATA`, `HIRC`, `STID` {u32 type, u32 count,
+count x {u32 bank id, u8 len, name}}. `Init` (`50C63A23.bnk`) has `STMG`/`ENVS` instead of media.
+`701C1363.bnk` holds only `BKHD`.
+
+HIRC Sound object (type 2) payload: u32 object id, u32 plugin id (`0x00040001` = Vorbis), u32 stream type
+(0 = in memory, 1 = streamed, 2 = prefetch), u32 media id, u32 bank id of the media; for in-memory sources
+then u32 offset, u32 size, where offset = `DATA` payload position (from the start of the bank) + DIDX offset
+and size = DIDX size (checked on every in-memory source of the footstep banks and of `BmGame.upk`).
+A few sources use media of another bank. Every streamed media ID found is in a BKPK table, i.e. a WAD sound
+(`wad.md`).
+
+## Banks inside packages
+- The packages are fully LZO-compressed (package version 805, licensee 101). For the survey they were unpacked
+  with Gildor's `decompress.exe` (gildor.org; used from the user's old modding folder, not part of this
+  repository) and searched for `BKHD` (banks) and `BKPK` (WAD indexes). `UnrealX.upk` (512 bytes) is not a
+  readable package (wrong tag, probably encrypted).
+- Bank blobs in packages: 41,798 for 3,340 bank IDs. Many banks are copied into several packages (e.g.
+  `CHR_CatwomanFoleySuit` 31 times, `CHR_BatmanFoleyBelt` 26). 302 bank IDs occur as several blobs with
+  *different* media subsets (often one WEM each, several per package), so a bank's media set is the union
+  of all its blobs.
+- Largest: `CHR_RobinFoleyCape` 300 WEMs, `CHR_BatmanFoleyCape` 282, `CHR_Clayface` 263,
+  `CHR_NightwingFoley` 242, `CHR_CatwomanFoleySuit` 225, `CHR_MrFreeze` 176, `CHR_Combat` 166.
+
+## Consequences for editing (not implemented)
+- **Loose banks**: a replacement means rebuilding `DATA`/`DIDX` and the in-memory offsets/sizes in the HIRC
+  Sound objects of that bank (and in any other bank whose sources use its media). Whether the game accepts a
+  bank that changed size is untested.
+- **Embedded banks**: the package must be rewritten (decompress, patch every blob of the bank, recompress
+  LZO, fix the package's chunk table and export offsets/sizes). A sound must be replaced in **every** package
+  that carries a copy, otherwise the game may load the original from another package.
+- Either way: unverified in game so far; the same WEM rules apply (`wem.md`).

docs/formats/wad.md

@@ -63,8 +63,7 @@ original bytes where nothing moved).
 Replacing a pack media (`ackit` target `EDF036D6/393BC53A`) rewrites the pack table (`.bnk`), the
 WAD entry payload, and the WAD table/offsets. Verified in-game (NOTES.md, E2).
 
-## Regular soundbanks (`SFX\*.bnk`, bank version 56)
+## Regular soundbanks
 
-BKHD / DIDX {id, offset, size} / DATA / HIRC / STID. In-memory WEMs (DATA) are 16-byte aligned.
-`ackit/bnk.py` can read/rebuild them, but most front-end sounds come from banks embedded in UE3
-packages (`.upk`), which this toolkit does not modify.
+The other `SFX\*.bnk` files and the banks embedded in `.upk` packages hold their WEMs in memory (not in a
+WAD); see `banks.md`. The toolkit does not read or modify them yet.

docs/reverse-engineering/findings.md

@@ -68,6 +68,10 @@ Conclusion: approach A works end-to-end in-game. Use >= 30 s probes for the intr
     6 channels work at <= 32 kHz (uncoupled, like Wwise). The encoder falls back to 32 kHz automatically.
 15. Channel order for > 2 channels: the bitstream order equals the array order given to libsndfile; whether the game
     expects WAVEFORMATEX order (FL FR FC LFE BL BR) is unverified (identical-channel probes were used).
+16. (2026-10-09) The WADs hold only streamed audio. About 15,800 more sounds (footsteps, foley, combat, weapons,
+    UI, grunts) are in-memory WEMs inside soundbanks: 65 loose `SFX\*.bnk` (1,117) and 3,340 banks embedded in
+    the `.upk` packages (15,641; many banks copied into several packages). None are in the catalog; the WAD
+    side is complete. Inventory, layout and editing consequences: `docs/formats/banks.md`.
 
 ## Old path -> new path
 `scripts/harness.py` -> `ackit verify --ingame` (ackit/verify/ingame.py); `scripts/validate_builder.py` ->

docs/user-guide.md

@@ -26,6 +26,8 @@ back with one click.
   sound's name (useful hints for the many unlabelled lines); tick *Include characters mentioned in names*
   to filter on them too.
 - Click a column header to sort (length, size, status, ...). Ctrl/Shift-click selects several rows.
+- Most short effects (footsteps, foley, weapons, menu sounds) are stored inside soundbanks and are not listed
+  yet; the list covers voice lines, music, ambience and the effects of the SFX archive.
 - **Language** (top left) switches the speech language. Speech is read from the language the game is set to.
 
 ![Browsing by category](img/browse.png)