BJDubb · BJDubb · Jun 30, 2026 · Jun 30, 2026
diff --git a/README.md b/README.md
@@ -3,6 +3,12 @@
 
 A FiveM tool for creating server sided sirens.
 
+[![Docs](https://img.shields.io/badge/docs-docs.sirensharp.dev-blue)](https://docs.sirensharp.dev)
+[![Latest release](https://img.shields.io/github/v/release/BJDubb/SirenSharp)](https://github.com/BJDubb/SirenSharp/releases/latest)
+[![Discord](https://img.shields.io/badge/discord-join-5865F2)](https://discord.gg/GCMRtBNCXR)
+
+📖 **Full documentation: [docs.sirensharp.dev](https://docs.sirensharp.dev)**
+
 ![image](https://github.com/user-attachments/assets/7ccdc58f-ba56-4917-95d3-c0294979c25e)
 
 

diff --git a/docs/.gitbook/assets/editor-soundset.png b/docs/.gitbook/assets/editor-soundset.png
diff --git a/docs/.gitbook/assets/generate-dialog.png b/docs/.gitbook/assets/generate-dialog.png
diff --git a/docs/.gitbook/assets/image (11).png b/docs/.gitbook/assets/image (11).png
diff --git a/docs/.gitbook/assets/image (12).png b/docs/.gitbook/assets/image (12).png
diff --git a/docs/.gitbook/assets/image (4).png b/docs/.gitbook/assets/image (4).png
diff --git a/docs/.gitbook/assets/siren-inspector.png b/docs/.gitbook/assets/siren-inspector.png
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -18,4 +18,5 @@
 ## Info
 
 * [📜 Naming Requirements](info/naming-requirements.md)
+* [⚠️ Limits & Edge Cases](info/limits-and-edge-cases.md)
 * [🔧 Troubleshooting](info/troubleshooting.md)
diff --git a/docs/getting-started/creating-awcs.md b/docs/getting-started/creating-awcs.md
@@ -11,15 +11,12 @@ in the generated pack.
 
 ## How do I create one?
 
-In the **Soundsets** panel on the left, click the **+** (Add soundset) button.
-
-<figure><img src="../.gitbook/assets/image (4).png" alt=""><figcaption></figcaption></figure>
-
-A new soundset appears in the list. Select it and rename it in the inspector on
-the right; the panel also shows how many sirens it holds.
+In the **Soundsets** panel on the left, click the **+** (Add soundset) button. A new
+soundset appears in the list. Select it and rename it in the inspector on the right;
+the panel also shows how many sirens it holds.
 
 {% hint style="info" %}
 Soundset names have a few rules - see [Naming Requirements](../info/naming-requirements.md).
 {% endhint %}
 
-<figure><img src="../.gitbook/assets/image (5).png" alt=""><figcaption></figcaption></figure>
+<figure><img src="../.gitbook/assets/editor-soundset.png" alt=""><figcaption><p>The Soundsets panel (with the <strong>+</strong> button) on the left, a selected soundset, and its inspector on the right.</p></figcaption></figure>
diff --git a/docs/getting-started/creating-sirens.md b/docs/getting-started/creating-sirens.md
@@ -7,6 +7,8 @@ panel, or click **Import WAV**.
 You can also click **Add** to create a placeholder siren, then assign a WAV to it
 with **Browse** in the inspector on the right.
 
+<figure><img src="../.gitbook/assets/siren-inspector.png" alt=""><figcaption><p>A selected siren - format badge on the row, name/file and Preview in the inspector.</p></figcaption></figure>
+
 {% hint style="info" %}
 **WAV requirements:** Mono channel, 16-bit PCM encoding. SirenSharp shows a format
 badge on each siren and can **Fix Audio** in one click, or auto-convert during

diff --git a/docs/getting-started/exporting-resource.md b/docs/getting-started/exporting-resource.md
@@ -2,6 +2,8 @@
 
 When your project is ready, click **Generate Resource** in the toolbar.
 
+<figure><img src="../.gitbook/assets/generate-dialog.png" alt=""><figcaption><p>The Generate Resource dialog.</p></figcaption></figure>
+
 Fill in:
 
 * **Resource Name** - the FiveM resource folder name
@@ -30,5 +32,5 @@ Note the DLC name - you need it when configuring LVC Fleet VCF files.
 {% endhint %}
 
 {% hint style="warning" %}
-FiveM may only support **7 concurrent audio banks**. If you have more than 7 AWC soundsets, SirenSharp will warn you before generating.
+The constraints that actually matter are each AWC's **size** (it has to fit a wave slot) and the **total** number of custom audio banks your whole server loads - not how many soundsets are in one project. See [Limits & Edge Cases](../info/limits-and-edge-cases.md).
 {% endhint %}
diff --git a/docs/getting-started/installing-sirensharp.md b/docs/getting-started/installing-sirensharp.md
@@ -1,26 +1,24 @@
 # ⚙️ Installing SirenSharp
 
+SirenSharp is **Windows only**.
+
 ## Step 1 - Download
 
-Go to [GitHub Releases](https://github.com/BJDubb/SirenSharp/releases/latest) and download **SirenSharp-v0.x.zip**.
+Go to [GitHub Releases](https://github.com/BJDubb/SirenSharp/releases/latest) and pick one:
+
+* **Recommended - installer:** download the **Setup** `.exe`. It installs SirenSharp and then **updates itself automatically** in the background, so you don't have to re-download for every new version.
+* **Portable:** download the **portable** `.zip` if you'd rather not install. No auto-update - you re-download to upgrade.
 
 {% hint style="danger" %}
-Do **not** download "Source code" - that is for developers. You need the release ZIP containing `SirenSharp.exe`.
+Do **not** download "Source code" - that is for developers. Use the Setup `.exe` or the portable `.zip`.
 {% endhint %}
 
-<figure><img src="../.gitbook/assets/image (12).png" alt=""><figcaption></figcaption></figure>
-
 ## Step 2 - Run
 
-Extract the archive and run `SirenSharp.exe`.
-
-{% hint style="success" %}
-SirenSharp v0.4 is a **self-contained** single executable - the .NET runtime is bundled in. You do **not** need to install anything else.
-{% endhint %}
-
-<figure><img src="../.gitbook/assets/image (11).png" alt=""><figcaption></figcaption></figure>
+* **Installer:** run the Setup `.exe`. SirenSharp installs and launches itself; a desktop/start-menu shortcut is created. It's **self-contained** - you don't need to install .NET or anything else.
+* **Portable:** extract the `.zip` and run `SirenSharp.exe`.
 
 ## Step 3 - Optional tools for verification
 
-* **CodeWalker** or **OpenIV** - verify generated AWC files (SirenSharp can launch these after generation if installed)
-* **Audacity** - manually fix WAVs if needed (mono 16-bit PCM export)
+* **CodeWalker** or **OpenIV** - inspect generated AWC files (SirenSharp can launch CodeWalker after generation if installed)
+* **Audacity** - only if you want to edit source audio by hand; SirenSharp already auto-converts WAVs on export
diff --git a/docs/info/limits-and-edge-cases.md b/docs/info/limits-and-edge-cases.md
@@ -0,0 +1,34 @@
+# ⚠️ Limits & Edge Cases
+
+Most "it builds fine but won't play" problems come down to a handful of causes. Each one below is a **symptom → why → what to do**.
+
+## A siren is silent in-game
+
+**Why:** the game finds sirens by a **hash of the name**, not the text. If the name in your LVC/VCF config doesn't match the name in the pack exactly (lowercased), the game looks up nothing and you get silence. A typo, a stray space, or different casing is enough.
+
+**Fix:** make the name in your config match the siren name in SirenSharp exactly. See [Naming Requirements](naming-requirements.md).
+
+## Two AWCs clash and one goes silent
+
+**Why:** the game only looks at the **first 8 characters** of an AWC (soundset) name. Two AWCs that start with the same 8 characters (e.g. `policecar1` and `policecar2` -> both `policeca`) are treated as the **same** pack: one loads, the other plays silent, even though the names look different.
+
+**Fix:** keep the first 8 characters of each AWC name unique. Short names are simplest. SirenSharp warns you about this in preflight.
+
+## A single pack is too big to load
+
+**Why:** each audio pack loads into a fixed-size memory **slot**. If a pack is bigger than its slot, it doesn't fit and plays silent. The limit is **bytes, not seconds** and sirens become mono 16-bit PCM, where `bytes ≈ sample_rate × 2 × seconds`. So a **lower sample rate fits more audio**. (Note: the widely-repeated "~7 seconds" figure isn't a real engine value — there's no single fixed per-siren limit. Siren packs are small and rarely hit this.)
+
+**Fix:** **trim** the audio or **lower the sample rate** of the source.
+
+## The server runs out of audio memory (lots of custom audio)
+
+**Why:** all loaded custom audio shares one pool of memory called the **AudioHeap** (default ~195 MB). It's not a fixed *number* of packs — it's memory. When it fills, new packs go silent and the game can crash with:
+
+> `AudioHeap Pool Full ... raise AudioHeap PoolSize in common/data/gameconfig.xml`
+
+This is why people see a wall around **~175–190 custom packs** — that's just the default heap filling up.
+
+## Good to know
+
+* **Audio always ends up mono 16-bit PCM.** SirenSharp auto-converts on export (stereo is downmixed). Stereo separation and high bit depths are lost by design; the source sample rate is kept.
+* **Resources are build-agnostic.** Custom AWC/dat54 audio doesn't depend on a specific GTA build. Use the default `cerulean` fx_version unless your server docs say otherwise.
diff --git a/docs/info/naming-requirements.md b/docs/info/naming-requirements.md
@@ -1,26 +1,45 @@
 # 📜 Naming Requirements
 
-All names are lowercased automatically.
+All names are **lowercased automatically** before the pack is built.
 
-## AWC (soundset) names
+## Why names matter (how the game finds your sirens)
 
-* No spaces
-* Lowercase letters, numbers, underscores
-* Example: `bcso_sirens`, `lspd_pack`
+The game does **not** store your siren's text name inside the AWC. It stores a **hash** of the name (a Jenkins one-at-a-time hash of the lowercased string). The dat54 metadata references each wave by hashing the **same** lowercased name. At runtime the game hashes the name from the dat54/your LVC config and looks that hash up in the bank.
 
-## Siren names
+This has two consequences:
 
-* No spaces
-* Lowercase letters, numbers, underscores
-* Derived from WAV filename on import (spaces become underscores)
-* Example: `wail`, `yelp`, `airhorn`
+* **Case doesn't matter, but it must be consistent.** SirenSharp lowercases everything so the AWC hash and the dat54 reference always match. (Older builds didn't, which is why some packs were silent in-game - see [Troubleshooting](troubleshooting.md).)
+* **The name you put in LVC must match exactly** (lowercased). A typo = a different hash = the game finds nothing and the siren is silent.
+
+## Allowed characters
+
+The in-app validator only blocks **empty** names and **spaces**, but the safe, supported character set is:
+
+* **Lowercase letters `a-z`, numbers `0-9`, and underscores `_`**
+* No spaces, no `dlc_` prefix on the DLC name
+
+Other characters (`-`, `.`, `()`, accents, etc.) may technically hash, but they make LVC/VCF string matching error-prone and some tools assume `[a-z0-9_]`. **Stick to `a-z 0-9 _`.**
 
-## DLC name (export dialog)
+### AWC (soundset) names
+* Example: `lspd`, `bcso`, `fire_amb`
 
+{% hint style="warning" %}
+**The game identifies a wavepack (AWC) by the first 8 characters of its name.** Anything past the 8th character is effectively ignored when the game looks the bank up (this is why FiveM's wavepack handling matches base packs on 8 characters). A longer name still works **as long as its first 8 characters are unique** - but two AWCs that share the same first 8 characters (e.g. `policecar1` and `policecar2`, both `policeca`) resolve to the **same** bank: only one loads and the other plays **silent** in-game, even though the names look different. SirenSharp flags this collision in preflight. Keep the first 8 characters of each AWC name distinct (short names are simplest).
+{% endhint %}
+
+### Siren names
+* Derived from the source filename on import (spaces become underscores)
+* Example: `wail`, `yelp`, `airhorn`
+
+### DLC name (export dialog)
 * Do **not** include the `dlc_` prefix - SirenSharp adds it
 * Must be unique across your SirenSharp projects
 * Example: `policesirens` → output folder `dlc_policesirens/`
 
+## Avoid near-duplicate names
+
+Because waves are stored by a 29-bit slice of the name hash, two **different** names can - very rarely - collide to the same id, and one siren will shadow the other. If a specific siren won't play but its neighbours do, rename it to something distinct.
+
 ## FiveM / LVC references
 
 In LVC Fleet VCF, reference:

diff --git a/docs/info/troubleshooting.md b/docs/info/troubleshooting.md
@@ -11,20 +11,10 @@ This is the **#1 support issue** and is usually **not** a SirenSharp bug.
 
 See [LVC Fleet docs](https://docs.luxartengineering.com/fleet/resource-installation/configure-base-settings).
 
-## Silent or ~1 KB AWC files
-
-**Cause:** Incompatible source WAV (stereo, wrong bit depth, junk RIFF headers).
-
-**Fix in v0.4:** Use **Fix Audio** on the siren, or regenerate - SirenSharp auto-converts on export. You can also re-export from Audacity as *WAV (Microsoft) signed 16-bit PCM* mono.
-
 ## AWC shows hex names in OpenIV
 
 **Expected behaviour.** Hex names are part of AWC encoding. Use your **string siren names** in LVC VCF - not the hex values shown in OpenIV.
 
-## Downloaded source code instead of the app
-
-If `SirenSharp.exe` is missing or generation fails silently, you likely downloaded **Source code** from GitHub instead of the release ZIP. Get [SirenSharp-v0.x.zip](https://github.com/BJDubb/SirenSharp/releases/latest).
-
 ## Testing without LVC
 
 Tick **Generate in-game tester** on the export dialog and SirenSharp writes a `sirensharp-audio-test` resource next to your pack. Run `/sirentest` in-game to play your soundsets through a menu with no LVC configuration. See [Test in-game](../getting-started/test-in-game.md).

diff --git a/docs/overview/what-is-sirensharp.md b/docs/overview/what-is-sirensharp.md
@@ -4,7 +4,7 @@ SirenSharp is a desktop tool for generating FiveM resources that stream custom s
 
 It lets you create multiple AWC soundsets with many sirens each - useful for splitting sirens between departments (e.g. LSPD, BCSO, State).
 
-**v0.4 highlights:**
+**Highlights:**
 
 * Modern dark UI with drag-and-drop WAV import
 * In-app WAV preview before generating
@@ -13,4 +13,4 @@ It lets you create multiple AWC soundsets with many sirens each - useful for spl
 * Selectable `fx_version` for the generated manifest
 * One-click in-game tester (RageUI menu, no LVC config) generated alongside your pack
 
-Download the **release ZIP** from [GitHub Releases](https://github.com/BJDubb/SirenSharp/releases/latest) - not the "Source code" archive.
+Download the latest release from [GitHub Releases](https://github.com/BJDubb/SirenSharp/releases/latest) - not the "Source code" archive.