UnheardCity/docs/user-guide.md

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

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.
• Edit: the sounds of the edit list in that language (sounds of another language stay on the list, hidden).
• 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 Edit tab shows the bank and how many copies the game keeps of the sound; a replacement is written into every copy.

Listen

The Sounds tab is for finding and listening; it does not change anything. Below the list, the selected sound is shown with its details and subtitle (left), a player (middle) and the way into the Edit tab (right). Play original (or Space, or double-click the row), Play installed (what the game has now, if you replaced it) and Stop (Esc) sit together above the waveforms; click on a waveform to play from that point.

To change sounds, select them (Ctrl/Shift-click for several) and press Edit (or Enter, or right-click > Edit): they go onto the edit list and the Edit tab opens on the first. Add to edit list puts them there without leaving the list, e.g. to collect all the lines of a character or all the sounds of a weapon first.

Edit

The Edit tab is where sounds are replaced: voice lines, music, ambience, sound effects. Everything fits in the window: left the edit list, middle the sound you are working on, right its effects.

• Edit list: filter it, Remove sounds you are done with, or Remove applied. Columns: a dot = a replacement is saved, FX = number of effects on, a tick = applied to the game. Previous / Next (Alt+Left / Alt+Right) walk the list.

1. Subtitle (voice lines only): shown large, with the game's original (and the English line when you edit another language) under it. You can rewrite it there and Apply it (see Subtitles).
2. Listen: Original, Installed and Replacement each have a play button and a waveform; A/B switches between the original and the replacement at the same position; Loop, Volume, Stop (Esc).
3. Replacement: Record (choose the input in the list next to it; press again to stop) or Load file… (Ctrl+O: WAV, FLAC, OGG, OPUS, MP3 or AIFF; M4A/WMA only if ffmpeg is installed), as often as you like. Keep … to trims (or right-drag on the replacement's waveform), Trim silence, Gain, Normalize, Match loudness (to the original; on by default for voice lines). The replacement is saved at once in your user data folder (edits), with its trim, level and effect settings, so you can come back to it any time; nothing is written to the game until you apply it.
4. Apply to game (Ctrl+S). The audio (with its effects) is converted to the original's format and written into the game files; the list shows a tick and the Sounds tab Modified.

Size rule: voice lines and sound 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.

Effects

Many sounds are not dry in the game (radios, phones, announcements, speakers, Mr. Freeze's suit...); the replacement gets the effects you turn on, and Replacement plays it with them.

• Start from a preset… sets several effects at once: Radio, Phone, Tape / phone mic, TV in a room, PA announcement, Mr. Freeze, Clayface, Riddler broadcast, Giant (Ra's al Ghul), Car radio.
• The effect chain lists every effect in the order it runs: tick an effect to turn it on, click its name to see its settings below. Each effect has preset buttons that set its sliders; then adjust by ear. Moving a slider turns its effect on; double-click a slider to put it back.

effect	in the game, for example
Pitch (shift, formant, drift = pitch over time)	Clayface (shift down), Mr. Freeze (drift)
Octave layers	Ra's al Ghul, Poison Ivy (octaves below the voice)
Robot (ring modulator, metallic comb)	Mr. Freeze's suit
Glitch (pieces repeated, at another pitch)	the Riddler's hacked broadcasts
Band-pass EQ (low/high cut, mid boost)	radio, phone, phone microphone, TV and small speakers
Distortion (drive, clip, bits, phone codec)	speakers, radios, the car radio
Noise (level, colour, crackle)	radio static
Echo	Hugo Strange, the Mayor, Joker and Harley over the city speakers (the PA announcement preset: 160 ms)
Reverb (decay, mix, pre-delay, reflections, damping; reverse swells before phrases)	rooms, TV, halls; reverse: the Riddler, Poison Ivy
Channels (sounds with 2-5 channels)	stereo width, pan over time, the PA layout: dry sound in the centre, echo in the surrounds

Copy / Paste move settings between sounds; Use these effects for the selected gives every selected sound of the edit list the same settings (e.g. all of Mr. Freeze's lines), keeping their replacements. Reset turns everything off.

Some effects are added by the game itself while it plays, not stored in the sound (the radio sound of many thugs and street conversations, the reverb of rooms and areas): if the original sounds clean here but not in the game, keep your replacement clean too, or the effect is applied twice. Glitch, echo and reverb make a sound longer, which counts for the size rule.

Undo

• Revert in the Edit tab puts that sound back exactly (the replacement stays saved for later).
• 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 selects the speech line in the Sounds tab (its subtitle shows in the preview). In the Edit tab, a voice line's Subtitle is shown large above the audio: edit it there, Apply / Revert it, 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

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). Drag the dividers to resize: the preview under the sound list, and the edit list, editor and effects columns of the Edit tab.

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