Audio Formats

Features

Framework mod: everywhere SideLoader accepts a .wav file, it now also accepts .ogg and .mp3.

Nothing to configure, nothing to call. Install it, and the audio files of any SideLoader pack are picked up whatever their format.

Details

As a mod builder, drop your .ogg / .mp3 files in Sideloader\<YourPack>\AudioClip\ exactly like you would drop .wav files, and add this mod as a dependency. The file name (without its extension) stays the clip key, so an existing pack keeps working after converting its files.

This covers:

• the AudioClip\ folder of a SideLoader pack (folder, .zip archive or asset bundle),
• CustomAudio.LoadAudioClip(filePath, ...) and CustomAudio.LoadAudioClip(byte[], ...),
• CustomAudio.ConvertByteArrayToAudioClip(byte[], ...),
• replacing a vanilla GlobalAudioManager.Sounds entry, by naming the file after it.

Ogg and mp3 are compressed formats, so unlike .wav a long track stays small on disk.

Prefer ogg. At the bitrates that matter for voice or short effects it is smaller than mp3 for the same fidelity, and it decodes sample-exact. Mp3 keeps the encoder's padding: a clip comes out about 110 ms longer in game than its source, which the engine does not trim.

Decoding

Files are decoded by the game engine itself, which is fast and needs nothing extra. If the engine refuses a file, the mod retries with the bundled fully managed decoders (NVorbis for ogg, under Ms-PL, and NLayer for mp3, under MIT - both redistributed unmodified, see THIRD-PARTY-NOTICES.md). That fallback is what makes mp3 dependable, since the engine's mp3 support is picky about tags and unusual bitrates, and it is also what reads audio stored inside a .zip pack, where the engine has no file to work from.

PreferManagedDecoders (via Outward Configuration Manager: F5) forces the managed decoders for every file, should a file play everywhere except in game. VerboseLogging reports the sample rate, channel count and decoder used for each clip in output_log.txt. Whatever that setting, loading a batch of 25 clips or more logs how long it took and where the time went, which is what to look at first if a pack is slow to load.

Loading

A voice pack can hold thousands of clips, of which a session plays a handful. Decoding all of them at startup costs the loading time, and the memory, of everything the player never hears. Three settings govern that. The defaults suit a pack of any size, so none of them normally needs touching.

LazyLoadingThreshold (default 100) is the pack size from which clips are merely indexed at startup and decoded the first time something plays them. On a 2500 clip voice pack this turns twenty seconds of startup decoding, and over a gigabyte of PCM, into a directory listing. 0 always loads everything up front.

Two limits come with it. It only applies to packs whose files sit in a folder, since a clip inside a .zip pack has no path to come back to later. And a lazily indexed pack leaves its SLPack.AudioClips empty until its clips are played, so raise the threshold above your pack's size if you read that dictionary yourself.

MaxConcurrentLoads (default 256) caps how many files load at the same time. SideLoader asks for every file of a pack in a single frame, and a pack with thousands of clips would otherwise hold them all open at once. 0 removes the limit.

LoadMode decides how a clip is held once loaded. Decompress, the default, expands it to raw PCM - a minute of 24 kHz mono is ~3 MB of PCM against ~300 KB of ogg. Streaming decodes from the file as it plays, which loads about five times faster, at the cost of keeping the file open for as long as the game runs, and of Unity playing only one instance of a streamed clip at a time. CompressedInMemory asks the engine to keep the file compressed and decode it as it plays; the game's Unity version (2020.3) was measured to ignore that request and decompress anyway, so it currently behaves like Decompress.