Lyriclib

A shared library for Lethal Company that gives CustomBoomboxMusic native FLAC playback and exposes the decoder plus the catalog bridge to other mods.

What it does

CustomBoomboxMusic's file loader (LethalModUtils.Audio.GetAudioType) only understands ogg / mp3 / wav / m4a / aiff, so a .flac file dropped into a CustomBoomboxMusic folder is logged as "Couldn't load file" and skipped.

Lyriclib decodes those files with its own dependency-free FLAC decoder and registers the resulting clips in CustomBoomboxMusic's catalog (AudioManager.audioClips). In game they behave exactly like a track CustomBoomboxMusic loaded itself: randomizer, /play, CRC-based network sync, lyrics mods, everything.

• Only .flac files below a folder named CustomBoomboxMusic are touched (the same rule CustomBoomboxMusic uses); every other format is still loaded by CustomBoomboxMusic itself.
• Tracks keep the CRC-32 identity CustomBoomboxMusic computes, so remote clients resolve them correctly.
• Decoding runs on a background thread; the finished PCM buffer is uploaded to Unity once, on the main thread.
• A track whose CRC is already in the catalog is never registered a second time, so Lyriclib can coexist with another flac provider (e.g. LyricDisplay's built-in shim).

Configuration

BepInEx/config/Lyriclib.cfg

Section	Key	Default	Meaning
General	Enabled	true	Load the .flac tracks in your CustomBoomboxMusic folders. Off = stock CustomBoomboxMusic behaviour.

For mod developers

Reference Lyriclib.dll (do not ship your own copy of it) and call Lyriclib.LyriclibApi:

Member	Thread	Purpose
IsFlacSupportEnabled	any	is flac loading switched on
IsBoomboxAvailable	main	is CustomBoomboxMusic's catalog hooked
IsInCustomBoomboxMusicFolder(path)	any	does the file sit in a folder CustomBoomboxMusic scans
IsFlac(bytes)	any	cheap fLaC marker check, never throws
DecodeFile(path, out error)	any	FLAC file → PCM (FlacAudio)
Decode(bytes, out error)	any	FLAC bytes → PCM (FlacAudio)
ComputeTrackCrc(bytes)	any	the CRC-32 CustomBoomboxMusic uses as track identity
CreateClip(audio, name)	main	PCM → Unity AudioClip
TryRegisterTrack(path, clip, crc, out error)	main	hand a clip to CustomBoomboxMusic
IsTrackRegistered(crc)	main	is a track with this CRC already in the catalog
LoadTrack(path, out error)	main	read + decode + create + register in one call

Decoding a long track inline will hitch the game. For those, decode on a worker thread with DecodeFile and register on the main thread:

// worker thread
byte[] bytes = File.ReadAllBytes(path);
FlacAudio audio = LyriclibApi.Decode(bytes, out string error);

// main thread
AudioClip clip = LyriclibApi.CreateClip(audio, "my track");
if (!LyriclibApi.TryRegisterTrack(path, clip, LyriclibApi.ComputeTrackCrc(bytes), out error))
{
    UnityEngine.Object.Destroy(clip);   // the catalogue refused it; the clip is yours
}

Lyriclib.Flac.FlacDecoder, FlacAudio, FlacStreamReader and Crc32 are public as well, if you need frame-level access.

Temporary, by design

This library exists only because CustomBoomboxMusic cannot play flac on its own. As soon as CustomBoomboxMusic supports flac playback natively, the automatic loading in Lyriclib has to be removed — doing it twice would register every flac twice. Until then the Enabled switch is the escape hatch.

Credits

• FLAC decoder, CRC-32 and catalog bridge: the same from-scratch code that started inside LyricDisplay (no third-party decoding code).
• CustomBoomboxMusic by baer1 — the catalogue this hooks into.