Files

Cristian Gora 1ccaa8b398 Full correctness check against the docs: safer writes, reverts and texts

Safety
- Writes are serialized (Workspace.lock): two background jobs rebuilding one
  package (a sound and its subtitle applied side by side) lost an edit.
- A store copies a bank file or package as "original" only if it matches the
  shipped catalog (Workspace.unoriginal_files: in-memory sounds, bank copies of
  voice lines, subtitles); the editor refuses to switch stores while changes
  are applied. A second store could otherwise resurrect a reverted sound.
- Mod import in the editor asks before overwriting files changed outside the
  tool (it forced silently).
- Revert all in the editor reverts texts too; the uninstaller counts text
  edits before offering to delete the store.
- ackit restore-backup: the full-backup restore decisions.md described; it
  keeps the sounds of WADs without a full copy recorded.
- build_catalog also stops when a subtitle differs from the catalog.

Languages and texts
- Game.language() returns languages without voices (JPN, RUS, ...) and
  Game.voice_archive() their INT voices; ackit text --lang JPN works.
- Menu lookups parse one cached file (find & replace: minutes -> ms).
- Subtitles decode cp1252 as Windows does: the UTF-8-in-cp1252 line
  Speech_TAPE_J_Answer_1_00 (KOR/POL/POR/RUS) is written back byte-for-byte;
  SUB_KOR/SUB_RUS rebuilt from the original game (only those rows changed).
- Mods exported while another language is loaded keep name and line.

Other fixes
- Down-mix folds extra channels in at -3 dB (a 5.1 centre voice was dropped).
- e2e_editor no longer overwrites the user's settings.json; kill_game waits
  for the game to exit before reverts.
- Recorder handles Int32/UInt8 input and split frames; package block cache
  locked; conflict messages, CLI help examples, stale docstrings and doc
  references fixed; tests no longer read this PC's game language.

Docs (decisions, user guide, README, subtitles.md, banks.md, catalog README,
REPORT, NOTES, CLAUDE.md) updated; check_docs: 102 claims match. 148 tests;
e2e_features 9/9, e2e_editor and verify PASS; game original afterwards.

2026-10-13 21:34:13 +02:00

12 KiB

Raw Blame History

Unheard City - user guide

Replace voice lines, music, ambience and sound effects, and edit subtitles and menu text in Batman: Arkham City (PC, Steam). Everything you change can be put back with one click.

Install and start

Windows: unzip the download and double-click Install.cmd. It installs Unheard City for your user (no admin rights), adds it to the Start menu (and, if you want, the desktop) and offers to start it. Running a newer version's Install.cmd later upgrades it. To remove it: Settings > Apps > Installed apps > Unheard City. You can also skip installing and run UnheardCity.exe from the unzipped folder. Linux: unpack the download and run UnheardCity.
The game is found through Steam automatically. If not (other drive, Linux/Proton), a red bar appears at the top: click Choose game folder… and pick the folder that contains BmGame and Binaries (Linux: usually ~/.steam/steam/steamapps/common/Batman Arkham City GOTY).
Close the game while you apply or revert changes (the files are locked while it runs).

Language

There is one language setting: the Language list at the top of the window. It starts at the language the game is set to (Steam > game properties > Language) and applies to everything you edit:

Sounds: the voice lines of that language, plus the sounds every language shares (music, ambience, effects). The game has voices in English (INT), French, Italian, German and Spanish; for the other languages (Latin American Spanish, Polish, Portuguese, Russian, Japanese, Korean) it plays the English voices, so the editor shows those and says voices: INT next to the list.
Subtitles and Menu text: the texts of that language. Changing it reloads the lists; the next start is again in the game's language. Some voice lines sound English in every language: the game itself ships the English recording for most efforts and grunts, many cinematics and a few other lines, and some in-memory lines exist only once for all languages. The editor shows what each language's game files contain.

Names

Every voice line has one name in every language, taken from the game itself (e.g. Speech_TAPE_JOKER_1_04, the same as in the Subtitles tab): the line Speech_X in English is the same line Speech_X in French, Italian, German and Spanish. Inside a WAD entry the game stores the variations of a line in a different order in each language, so the position-based name is kept only as a second name (Speech_TAPE_JOKER_1#4 = the 4th WEM of that entry in this language; search finds both). When the game plays one of two versions of a line, the second is shown as NAME#2. About 6 % of the lines are named by no game event; they take the name of their English recording in every language. A few recordings are stored twice in the game files: both rows belong to the same line and are changed and reverted together.

Find a sound

Type in the search box (Ctrl+F): words can be parts of the name, a category, a character, your own notes or tags, or an ID like b49cdf48. All words must match.
Narrow down with Group (Speech, Music, Ambience, SFX), Category (e.g. Interview tapes, Combat barks, Cinematics), Character, Archive (speech language, SFX or BANK), Tag, Modified only and Favorites only. Combine them freely; results update instantly.
Character is the verified speaker from the curated catalog. Grey ~ names are only mentioned in the 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.
Archive BANK holds the short sounds stored inside soundbanks (footsteps, foley, combat, weapons, menu sounds, grunts). Many are named after the game event that plays them (Play_...), the rest after their bank (CHR_BatclawGrapple_3). The editor shows the bank and how many copies the game keeps of the sound; a replacement is written into every copy.

Listen

The editor under the list shows the selected sound in three columns side by side (drag the dividers to resize them): Listen, Replace and Subtitle. Select a row and press Space to play the original (once a replacement is loaded, Space plays the replacement; Space again stops), or double-click it. Each column ends with its own buttons on one line. In Listen:

Original / Installed play the game's original and what is currently in the game; Stop (Esc). Click on a waveform to play from that point.
Above them: A/B (switch between the original and your replacement at the same position, to compare), Loop, Volume and the playback position. The icon buttons show their names when you point at them.

Replace

Load file… (Ctrl+O): WAV, FLAC, OGG, OPUS, MP3 or AIFF. (M4A/WMA work only if ffmpeg is installed.) Or choose a microphone in the list and press Record, then Stop recording. Listen with Replacement; record again as often as you like.
Adjust: Keep … to trims (or right-drag on the replacement waveform), Trim silence, Gain, Normalize, Match loudness (to the original; recommended for voice lines).
Apply to game (Ctrl+S). The audio is converted to the original's format and written into the game files. The row turns bold and shows Modified.

Size rule: voice lines and effects must fit into the original's size (the Max size column), because the game reads exactly that many bytes. Longer audio is encoded at lower quality to fit; if it still does not fit you are asked to shorten it. Music (Music_…) can be any length. A warning appears when your audio is longer than the original, since the game may cut it off.

Undo

Revert in the editor puts that sound back exactly.
Right-click rows → Revert selected; toolbar Revert all puts every original back: all sounds, subtitles and menu texts you changed, in every language.
Originals are kept in your user data folder (%APPDATA%\UnheardCity on Windows, ~/.local/share/unheardcity on Linux), so reverting works after updating or reinstalling the app too. Uninstalling keeps this folder; use Revert all before uninstalling if you want the game back to original. Before the first change to a game file, a full copy of it is kept there too: optional for the WAD archives (Settings), always for soundbanks, packages and text files (they are rebuilt from that copy). Only files the game ships unchanged are copied; a file another tool (or another originals store) has changed is reported as changed outside this tool first.
The originals of your changes are only in the store that made them, so the store folder (Settings) cannot be changed while changes are applied: use Revert all first.
If Steam "Verify integrity of game files" or an update undoes your changes, a bar offers Re-apply my changes or Forget them. Do not use "verify" to undo mods; use Revert all.
If the store folder itself is damaged, the full copies can still be put back with the command-line toolkit that Unheard City is built on (ackit restore-backup, see the project README; not part of the editor download).

Subtitles

The Subtitles tab lists the subtitle of every speech line in the selected language (see Language).

Search by text or line name, filter by Character and Category (taken from the linked speech sound), or show Modified only. Select a row to edit its text below and press Apply (or Enter).
Each subtitle replaces the original in place, so it can be at most as long as the original (the counter shows used / room characters). Most subtitles are stored in the Western European character set (Windows-1252: accents are fine, other scripts are not); those stored as Unicode (almost all Russian, Japanese and Korean ones, most Polish ones) accept any character. The editor says so when a character does not fit.
Go to the sound opens the speech line in the Sounds tab. In the Sounds tab, the editor of a speech line shows its subtitle in the Subtitle column next to the audio: edit both side by side, Apply / Revert the subtitle there, or Show in list to jump back to the Subtitles tab.
Find and replace… works on the rows the filters show (texts that would not fit are listed and skipped).
Revert / Revert all texts here put the original text back (every copy in every game file).
About 30 subtitles per language have no sound in the game (texts such as the Arkham City Stories, unused radio reports); they have no linked sound. A subtitle of a line the game plays in two versions belongs to both. The game itself has no subtitles for efforts and grunts and for most combat barks and cutscene lines.

The Menu text tab lists every menu, HUD, bio, riddle and credits string of the selected language (about 7,000), grouped by File (e.g. FRONTEND, GFxUI, Bios). Search, edit, apply and revert work like subtitles; menu texts can be of any length but cannot contain line breaks (keep the game's own markers such as \n as they are).

Notes, tags, favorites

Right-click → Notes & tags… (F2): free text and comma-separated tags, searchable and filterable. Click the ★ column to mark favorites. These are stored in your user data folder, not in the game.

Export mod…: choose which changed sounds and texts to include and save a .acmod file (the exact game data plus the audio, so it also works for another language whose original has a different size).
Import mod…: shows which sounds match this game, then installs them. You can revert them like any change. If a sound or text the mod replaces was changed outside the editor, you are asked before it is overwritten.
Changed subtitles and menu texts are exported and imported with the sounds (listed as Text); a text stays in its language (a French subtitle edit changes the French subtitle).
In another language, voice lines are matched by the game's own identity of the line, so the same line is replaced even where its position differs. Voice lines from packages made with versions before 3.1 carry no such identity: the import lists them instead of guessing (export the mod again with this version).

Settings

Game folder, where originals are kept (changeable only while nothing is modified), the full-backup option and the playback device. The recording device is chosen next to the Record button. Background: show or hide the Arkham City wallpaper behind the filter panel; Background strength: how visible it is (10 % by default). The editor panel opens tall enough to show all its controls; drag the divider above it to change that.

Troubleshooting

message	what to do
"Cannot write … close the game"	quit Arkham City (and anything else using the file) and try again
"not a Batman: Arkham City folder"	pick the folder that contains `BmGame` and `Binaries`
"audio is too long for this sound"	shorten the audio (see the original's length)
"the text is … characters long but this subtitle has room for …"	shorten the subtitle (the counter shows the room)
"Cannot read … Supported: WAV, FLAC, …"	convert the file to WAV/MP3/FLAC, or install ffmpeg
"changed outside this tool"	the game files were changed by an update or another tool; revert or confirm to overwrite
no sound when playing	choose another playback device in Settings

12 KiB Raw Blame History