# 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_...Crowd...` | Ambience | Crowds |
| other `Speech_` | Speech | Other speech |
| media of the `Music` / `Music_PDLC` stream packs, `Music*`, `MUS_` | Music | Music / Music (DLC) |
| `AMB_`, `PSA_` | Ambience | Ambience |
| `PSO_` (flies, drips, fans, lights) | Ambience | Ambient emitters |
| `WND_` | Ambience | Wind |
| `WTR_` | Ambience | Weather |
| `VOL_`, `PVOL_` | Ambience | Room tone |
| anything containing `Footstep` | SFX | Footsteps |
| `CHR_`/`NPC_` containing `Combat`, `BoneBreak`, `Bodyfall` | SFX | Combat |
| `SEQ_`, `MTN_` | SFX | Scripted sequences |
| `OBJ_` | SFX | Objects |
| `PX_`, `PHY_` | SFX | Physics |
| `WPN_` | SFX | Weapons |
| `DVC_` | SFX | Gadgets |
| `GUI_`, `SBJ_` | SFX | Interface |
| `VFX_` | SFX | Visual effects |
| other `NPC_` | SFX | Enemies & NPCs |
| `CHR_`, `GEN_` | SFX | Character foley |
| `Global` | SFX | Global |
| anything else (e.g. unnamed hex IDs) | Unknown | Unknown |

BANK sounds (in-memory, `docs/formats/banks.md`) are classified by the name of their **soundbank** (e.g.
`CHR_CatwomanFoleySuit`, `Speech_EMOTE_Batman`), which is more systematic than their event names.

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). The lists name ITA sounds by their position in the ITA WAD
  (wemscan names); positions differ between languages, so each label is moved to the game's line name of that
  sound (`characters.csv`, empty `language`) and then applies to the same line in every language. Labels of
  sounds no event plays stay ITA-only (`language` = ITA). Checked against the speaker field of the game's
  dialogue objects: 955 / 955 labelled lines agree (spelling aside: TwoFace, Mysterious_stranger = Azrael).
  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).