# 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
1. **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`.
2. 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`).
3. **Close the game** while you apply or revert changes (the files are locked while it runs).

![Main window](img/main.png)

## 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.

![Browsing by category](img/browse.png)

## 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
![Editor](img/editor.png)
1. **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.
2. Adjust: **Keep … to** trims (or right-drag on the replacement waveform), **Trim silence**, **Gain**,
   **Normalize**, **Match loudness** (to the original; recommended for voice lines).
3. **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.

## Menu text
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.

## Share your changes (mods)
- **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
![Settings](img/settings.png)
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 |