UnheardCity/README.md

Arkham City Audio Toolkit

Replace any voice line, music track or ambience in Batman: Arkham City (PC, Steam) with your own audio: by name, from a file or a recording, with one-click revert. No Wwise, no game patch, no external programs.

• Unheard City (app/, user guide): the desktop editor for Windows and Linux. Browse and search the ~11,500 sounds of the game's audio archives, filter by category and character, listen, replace or record, apply and revert. Most short effects (footsteps, foley, weapons, UI) live inside soundbanks and are not listed yet (docs/formats/banks.md).
• ackit (ackit/): the Python library and command-line tool behind it.

How it works in one paragraph: the game's Wwise 2011.1 decoder only knows the standard Vorbis codebooks, so ackit encodes with libvorbis and rewrites the stream into exactly the layout the game expects (codebook IDs, packet format, seek table, header hash and memory size reversed from the game), then writes it into the .wad archives atomically, keeping the original bytes in a store for exact reverts. Details in docs/.

Install

• Editor (users), Windows: unzip UnheardCity-<version>-windows-amd64.zip and double-click Install.cmd. It installs for your user (no admin rights), adds a Start menu shortcut and an entry in Settings > Apps for uninstalling. Or skip installing and run UnheardCity.exe straight from the unzipped folder.
• Editor (users), Linux: unpack the .tar.gz and run UnheardCity.
• Nothing else is needed (no Python, no Wwise, no ffmpeg). To build it yourself: docs/building.md.
• Toolkit (developers): Python 3.10+:

  python -m venv .venv && .venv/Scripts/activate        # Linux: source .venv/bin/activate
  pip install -e .[app,dev]                              # app = editor, dev = tests/packaging
  python -m app.main                                     # run the editor from source
  

Quick start (command line)

ackit find joker tape                            # search by name, category or character
ackit extract Speech_TAPE_JOKER_1_4 orig.wav     # listen to the original
ackit replace Speech_TAPE_JOKER_1_4 my_line.wav --match-loudness
ackit revert Speech_TAPE_JOKER_1_4               # or: ackit revert --all

More: ackit status, ackit list --character Joker, ackit export-mod my.acmod / ackit import-mod, ackit verify (offline self-check), ackit game (detected install, language, store). ackit -h lists all commands. The game folder is found through Steam (Windows, Linux, Flatpak, Proton); otherwise pass --game DIR.

Rules worth knowing: speech/effects replacements must fit in the original's size (the tool squeezes or refuses with the maximum length); music can be any length. Close the game before writing.

Where things are

ackit/          library + CLI   (formats, encoder, injector, catalog, originals store, workspace)
ackit/verify/   offline self-check, in-game test harness (Windows, WinDbg)
app/            Unheard City (PySide6)
tests/          pytest suite (synthetic game data; real-game tests run when the game is installed)
data/catalog/   sound catalogs (CSV), character lists (source/), schema in data/catalog/README.md
docs/           formats, reverse engineering, decisions, categories, user guide, building
tools/          catalog builder, packaging (build_app.py, installer/), artwork and license scripts
NOTES.md        project status and working notes; CLAUDE.md: guidance for AI sessions

Tests: pytest (the real-game tests are skipped when the game is not installed). In-game test (Windows, Steam running, WinDbg installed): ackit verify --ingame.