Initial commit

README.md

@@ -0,0 +1,55 @@
+# 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](docs/user-guide.md)): the desktop editor for Windows and Linux. Browse and
+  search all ~11,500 sounds, filter by category and character, listen, replace or record, apply and revert.
+- **`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](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`.