Initial commit

docs/categories.md

@@ -0,0 +1,64 @@
+# Categories and characters
+
+Implemented in `ackit/classify.py`; used both when building the shipped catalog (`tools/build_catalog.py`)
+and when a game build is not in the catalog (runtime scan), so every language/build gets the same scheme.
+
+## Groups and categories
+Every sound has a **group** and a finer **category**, derived from its Wwise name (from the community hash
+list; unnamed IDs show as hex). First matching rule wins:
+
+| name starts with | group | category |
+|------------------|-------|----------|
+| `CHR_RadioScanner`, `PSO_CarRadio`, `Speech_RADIO`, `Speech_TV`, `Speech_CAMERAS`, `DIA_` | Speech | Radio & TV |
+| `Speech_TAPE_` | Speech | Interview tapes |
+| `Speech_INTERROGATION_` | Speech | Interrogations |
+| `Speech_CINEMATIC_`, `Speech_New_` | Speech | Cinematics |
+| `Speech_Boss_` / `Speech_BOSS_` | Speech | Boss fights |
+| `Speech_RIDDLER_`, `Speech_RIDDLES_` | Speech | Riddler |
+| `Speech_SIDE_` | Speech | Side missions |
+| `Speech_DLC_` | Speech | DLC |
+| `Speech_PRED_` | Speech | Predator chatter |
+| `Speech_COMBAT_`, `Speech_Bully_` | Speech | Combat barks |
+| `Speech_EMOTE_` | Speech | Efforts & emotes |
+| `Speech_REACT_` | Speech | Reactions |
+| `Speech_STREETS_`, `Speech_ZONES_`, `Speech_OUTCAST_`, `Speech_Vertical_` | Speech | Open-world chatter |
+| `Speech_CHAR_` | Speech | Character lines |
+| `Speech_CH_`, `Speech_SEQUENCE_`, `Speech_STEEL_`, `_MUSEUM_`, `_CHURCH_`, `_COURT_`, `_UNDER_`, `_GCPD_`, `_ZP1_` | Speech | Story missions |
+| `Speech_GAME_`, `Speech_MAP_`, `Speech_AUGMENTED_`, `Speech_FORENSICS_`, `Speech_TEMP_` | Speech | Gameplay & hints |
+| `NPC_` | Ambience | Crowds |
+| other `Speech_` | Speech | Other speech |
+| media of the `Music` / `Music_PDLC` stream packs, `Music*` | Music | Music / Music (DLC) |
+| `AMB_`, `PSA_` | Ambience | Ambience |
+| `WND_` | Ambience | Wind |
+| `VOL_`, `PVOL_` | Ambience | Room tone |
+| `SEQ_` | SFX | Scripted sequences |
+| `OBJ_` | SFX | Objects |
+| `WPN_` | SFX | Weapons |
+| `CHR_` (in SFX) | SFX | Character foley |
+| `Global` | SFX | Global |
+| anything else (e.g. unnamed hex IDs) | Unknown | Unknown |
+
+Counts in the ITA catalog: Story missions 1993, Predator chatter 1796, Character lines 1537, Open-world chatter
+1295, Side missions 808, Combat barks 801, Efforts & emotes 616, Interview tapes 514, Riddler 360, Radio & TV 226,
+Gameplay & hints 199, DLC 167, Boss fights 150, Cinematics 150, Reactions 108, Interrogations 95. SFX archive:
+Music 389, Ambience 225, SFX 31, Unknown 6.
+
+## Characters
+Two separate fields, because Wwise names describe a *scene*, not the speaker of each variation (a conversation
+alternates speakers between `NAME_1`, `NAME_2`, ...):
+
+- **character** - the verified speaker, only from the curated lists in `data/catalog/source/<lang>/*.txt`
+  (one file per character, listening-based). Mapped by sound name, so labels made on the Italian files apply to
+  every language (the five language WADs have identical names and variation counts). Display names:
+  Calendar -> Calendar Man, Croc -> Killer Croc, Freeze -> Mr. Freeze, Ivy -> Poison Ivy, Madhatter -> Mad
+  Hatter, Quinn -> Harley Quinn, Ras -> Ra's al Ghul, Strange -> Hugo Strange, Talia -> Talia al Ghul,
+  Twoface -> Two-Face, Vicky -> Vicki Vale, Zsazz -> Victor Zsasz, Unknown -> Unknown (speaker checked but not
+  identified). A line in two lists gets both ("A; B").
+- **characters_inferred** - characters and roles *mentioned by the name* (token rules in `classify._TOKENS`,
+  e.g. `BM`/`BATMAN` -> Batman, `PENG` -> Penguin, `TF` -> Two-Face, `THUG*`/`GENTHUG*` -> Thug, `TYGER` ->
+  TYGER guard; interview tapes add Hugo Strange). A hint for the ~7,500 lines without a verified speaker,
+  never shown as the speaker. In the editor the character filter matches verified speakers, and optionally
+  inferred ones.
+
+Coverage (every language): 3,366 sounds with a verified speaker, 5,930 more with inferred characters, 1,520 with
+neither (mostly predator/efforts from unnamed thugs).