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

## Names
Voice lines carry the game's own line names (e.g. `Speech_TAPE_JOKER_1_04`), the same in every language and the
same as in the Subtitles tab. 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).

## 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_Bane_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** (or double-click) to
play the original. In **Listen**:
- **Original** / **Installed** play the game's original and what is currently in the game. Click on a
  waveform to play from that point. **Loop**, **Volume** and **Stop** (Esc) work for everything.
- **A/B** switches between the original and your replacement at the same position, to compare.

## 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.
- 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 an audio archive, one full copy of it is also kept there as a fallback (Settings).
- 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.

## 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). Latin-1 subtitles accept Latin-1 characters only (accents are fine);
  Russian, Polish, Japanese and Korean subtitles accept any character.
- **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 under the audio: edit both side by side and use **Apply subtitle**, or **Show in
  Subtitles** to jump back.
- **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 8 % of the subtitles belong to lines the game never plays (placeholders); they have no linked sound.

## 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 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.
- Changed subtitles and menu texts are exported and imported with the sounds (listed as *Text*).

## Settings
![Settings](img/settings.png)
Game folder, where originals are kept, 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) |
| "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 |