# Using Custom Sounds

## Prerequisites

The current method for generating sound banks uses a Python script, so Python must be installed on your system. You can download and install the latest version by following the instructions on [Python's official website](https://www.python.org/downloads/).

Your project must also be set up to use the Alexandria modding library. This should be done by default if you have followed the mod setup instructions on the [Creating a Mod](../getting-started/setting-up-visual-studio) page.

## One-time Setup

In the `GMStart()` method of your mod's `BaseUnityPlugin` class, add the following line somewhere.

```csharp
SoundManager.LoadSoundbanksFromAssembly();
```

Navigate to your project's "Resources" folder in your file explorer, then create a new subfolder named "Sounds". Then, [download the latest version of the sound bank generation script](https://raw.githubusercontent.com/pcrain/gungeon-modding-tools/master/gen-gungeon-audio-bank.py) and move it into your new "Sounds" folder (if it doesn't download automatically, hit Ctrl + S and save it manually).

Double-click on `gen-gungeon-audio-bank.py` in your file explorer to run the sound bank generation script. This should create an empty sound bank named `Sounds.bnk` in your "Sounds" folder. In Visual Studio, right click`Sounds.bnk` in the Solution Explorer, select "Properties", then change the Build Action to "Embedded Resource".

## Basic Usage

Adding a new sound to your mod is super simple:

* Drag a `.wav` file from anywhere on your computer into your "Sounds" folder.
* Double-click `gen-gungeon-audio-bank.py` to regenerate your sound bank.
* Rebuild your project.

That's it! You can play your sound in game with the following code (replace "soundName" with the name of your `.wav` file not including the `.wav` extension):

```csharp
AkSoundEngine.PostEvent("soundName", GameManager.Instance.gameObject);
```

For instructions on setting up sounds for your guns, see the [Customising Gun Sounds](customising-gun-sounds) page. The remainder of this guide covers advanced use cases and troubleshooting steps.

## Advanced Usage

### Tweaking Sound Parameters

In addition to your "Sounds.bnk" file, running the sound bank generation script also creates a "Sounds.csv" file if it doesn't exist. This file can be edited in any text editor or spreadsheet software to tweak the playback parameters of your sounds. Each line in this file has the following format:

```csv
name,volume,loops,channel,limit
```

* `name` is the filename (minus the `.wav` extension) of the sound the remaining fields will modify.
* `volume` controls the gain of the sound in decibels. E.g., `0` plays the sound as it is on your file system, `2` plays it slightly louder, `10` plays it twice as loud, `-10` plays it half as loud, etc. This should generally be kept between `-10` and `10.`
* `loops` controls how many times the sound loops whenever it plays. `1` makes the sound play once, `3` makes it play 3 times, `0` makes it loop indefinitely until manually stopped, etc.
* `channel` must be either `sound` or `music` and controls whether the sound plays on Gungeon's sound or music channel (this mostly only affects whether the sound's volume is controlled using the Sound or Music slider in the game's Audio options tab).
* `limit` controls the maximum number of instances of a sound that can play at once, with `0` being unlimited. If the limit for a sound is reached and another instance of the sound is played, the oldest instance of the sound will immediately stop playing.

Note that sounds are included in your sound bank whether or not they have a corresponding entry in "Sounds.csv". Sounds without explicit entries are assumed to have `volume` of `0`, `loops` of `1`, `channel` of `sound`, and `limit` of `0`.

"Sounds.csv" is only used by the sound bank generation script, and does not need to be embedded in your project. However, any time you modify "Sounds.csv", you must rerun the sound bank generation script and rebuild your project to apply changes, just as if you had added a new sound.

### Playback Control

The playback of sounds created with the sound bank generation script can be controlled using a handful of suffixes when calling `PostEvent()`. Assuming your sound bank includes a sound named "mysound.wav" and you have a `GameObject` named `myObject`:

```csharp
AkSoundEngine.PostEvent("mysound", myObject);
```

...will play "mysound.wav" on `myObject`. If `myObject` is destroyed, "mysound.wav" will automatically stop playing on `myObject`.&#x20;

```csharp
AkSoundEngine.PostEvent("mysound_stop", myObject);
```

...will stop all instances of "mysound.wav" playing on `myObject`. This can be useful for controlling the overlap of voices or other sounds that wouldn't make sense to be playing simultaneously on the same object.

```csharp
AkSoundEngine.PostEvent("mysound_stop_all", myObject);
```

...will stop all instances of "mysound.wav" playing on all objects. This can be useful for stopping indefinitely looping sounds.

```csharp
AkSoundEngine.PostEvent("mysound_pause", myObject);
```

...will pause all instances of "mysound.wav" playing on `myObject`. Useful in conjunction with:

```csharp
AkSoundEngine.PostEvent("mysound_resume", myObject);
```

...which will resume playback of any paused instances of "mysound.wav" on `myObject` from the position they were paused.

### Control Over Sound Bank Generation

The sound bank generation script searches its current directory for the first `.csv` file it finds and generates a sound bank with the same name. This means you can change the base name of "Sounds.csv" from "Sounds" to whatever you want to change your sound bank's name. If you do this, remember to update your project's embedded resources accordingly with the new bank filename.

For even finer control over sound bank generation (e.g., for integrating it into your build process), the script can also be run from the command line with various flags to control where audio files are read from, where the data spreadsheet is read from, where the sound bank is output, and what the sound bank is named. Run the script with the `-h` flag for a full list of options available.

## Troubleshooting / FAQ

### \*\*\*PLEASE FOR THE LOVE OF PETE READ THIS PART FIRST\*\*\*

Most issues that you're likely to encounter involve attempting to use audio files with an unsupported format.

If any issues whatsoever occur when adding or playing your sounds, the first thing you should try is opening your file in your preferred audio processing software ([Audacity is recommended](https://www.audacityteam.org/)) and re-exporting it with the following settings:

* Format: Microsoft `.wav` (the script only works with `.wav` files)
* Encoding: Signed 16-bit PCM (24-bit and 32-bit might also work, do NOT use 8-bit or ADPCM)
* Channels: Stereo or Mono
* Sample Rate: at least 16000Hz for stereo and 22050Hz for mono

If re-exporting your audio file doesn't solve your issue, please read on.

### My sounds aren't playing at all

Double check that you've done the following:

* Embedded your sound bank in your mod project
* Loaded your sound bank using `SoundManager.LoadSoundbanksFromAssembly()`
* Posted an event using the name of your sound (minus the `.wav`extension)

### My sounds are playing too quietly / loudly

If your sound is slightly too quiet or too loud, you can tweak its gain (volume) via the spreadsheet described in the [Tweaking Sound Parameters](#tweaking-sound-parameters) section.

If your sound is EXTREMELY quiet or loud, you should normalize it to -1.0dB and re-export it in Audacity. From there, you can continue to tweak the volume to your liking in Audacity, or you can make the remaining small adjustments using the spreadsheet as described above.

### When I run the bank generation script, it prints "wave.Error: unknown format"

You are probably trying to embed a file that is either 1) not a WAV file at all, or 2) is encoded as an ADPCM wave. [See the "Read First" section](#please-for-the-love-of-pete-read-this-part-first).

### The game crashes whenever I try to play my sound

You are probably trying to embed an 8-bit wave file (common in audio dumps from old console games such as the Gameboy or NES). [See the "Read First" section](#please-for-the-love-of-pete-read-this-part-first).

### My sound is playing with a lower / higher pitch than it does when I play it outside the game

This usually happens when trying to play a mono `.wav` file with a low sample rate (16000Hz or lower). [See the "Read First" section](#please-for-the-love-of-pete-read-this-part-first).

### I want to add music to my mod, but I don't want to include a zillion megabyte .wav file! D:

If you absolutely need support for audio other than `.wav` files, you will need to revert to using the older, more difficult WWise method for creating sound banks. Since you've read this far into this guide, I trust you to be responsible, so feel free to [use this guide](using-custom-sounds-1) and to ignore the warning at the top. :)
