Initial commit

docs/user-guide.md

@@ -0,0 +1,88 @@
+# Unheard City - user guide
+
+Replace voice lines, music and ambience 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)
+
+## 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 or SFX), **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.
+- **Language** (top left) switches the speech language. Speech is read from the language the game is set to.
+
+![Browsing by category](img/browse.png)
+
+## Listen
+Select a row and press **Space** (or double-click) to play the original. In the editor below:
+- **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 from / to** trims (or right-drag on the replacement waveform), **Trim silence**, **Gain**,
+   **Normalize**, **Match original loudness** (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 to original** 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.
+
+## 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.
+
+## 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 |