LethalMusicSync 📻

Welcome to the ultimate immersive audio mod for Lethal Company! LethalMusicSync brings real-time custom music streaming directly to your ship Terminal, supporting both your custom boomboxes and ship speakers with perfect multiplayer sync!

Natively supports Suno AI tracks and direct URL streams!

[!WARNING] 🤖 AI Usage Notice: This mod natively integrates with Suno AI platforms, allowing you to stream AI-generated music tracks and playlists directly in-game. Additionally, parts of this mod's code (specifically the complex Harmony virtual method patches and network failovers) were developed and optimized with the assistance of AI coding agents to ensure a cleaner and more stable assembly.

[!IMPORTANT] ⚠️ Potential Issues (Especially with the Boombox): Because of how Lethal Company's physics engine and pocketing routines are constructed natively, sync issues or audio glitches may occasionally occur—particularly with the Boombox.

• Pocketing the boombox, dropping it on the floor, or carrying it into facility boundaries can sometimes trigger vanilla audio overrides.
• If the boombox gets stuck, desynced, or plays the wrong volume, use the terminal command boombox stop or boombox clear to reset its network state, or drop and pick it back up.
• All players must have the mod installed to hear synced music.

🌟 Key Features

• 💻 Retro Terminal Controls: Fully integrated into the ship's Terminal interface. Control your music just like the rest of the ship systems!
• 📱 Interactive Boombox HUD Dashboard (F8): While holding a boombox anywhere (even deep inside facility corridors), press F8 to open an on-screen control console! Paste URLs, play, queue, skip, slide volume, and cycle loop modes on the fly!
• ⏯️ Seamless Play & Pause: Clicking the action button on the custom boombox pauses and resumes the custom track right where you left off. No more resetting or lost tracks!
• 🎶 Native Suno AI Streaming (with Real Titles): Copy a Suno song or playlist link. The mod scrapes Suno's React Server Components state tree, resolves the direct audio files, and pulls real track titles into your queue!
• 📢 3D Spatial ceiling Speaker: Sounds like a real physical intercom speaker with directional panning, echoes, and distance attenuation inside the Hangar Ship!
• 🤝 Chat-Based RPC Lobby Sync: Perfect synchronization between all players. Zero complex network configurations or port forwarding needed!
• 📦 100% Client-Safe & Lag-Free: Audio streams directly to each player, ensuring zero network overhead.

🎮 Terminal Commands

Access these commands from the ship's Terminal (works for speaker, music, and boombox!):

🔊 Three Distinct Playback Modes:

1. speaker (3D Spatial Intercom Ceiling Speaker): Sounds like it is coming from the ceiling of the hangar ship cabin in 3D. Has physical direction, distance attenuation, and echoes as you walk around the ship!
2. music (2D Global Cabin Background Music): Plays flat 2D stereo background music throughout the game. Perfect for rich, non-attenuated background music!
3. boombox (3D Portable Boombox Player): Spatial 3D audio parented directly to the nearest boombox item in hand or on the ground.

📻 Active Controls (Replace speaker with music or boombox to control other devices!)

• speaker play [URL] - Overrides everything, clears the queue, and plays the Suno song/playlist or YouTube link immediately.
• speaker queue [URL] (or q [URL]) - Appends the song or playlist to the end of the queue. If idle, starts playing it immediately.
• speaker list (or queue) - Displays a gorgeous list of all tracks currently in the queue, indicating which one is active.
• speaker skip (or s) - Skips the current track and starts playing the next one in the queue.
• speaker skip to [index] (or skipto [index]) - Skips directly to a specific track index in the queue.
• speaker loop [track/queue/off] - Sets loop mode:
  • track - Loops the current track endlessly.
  • queue - Loops the entire queue (wraps around when the last track ends).
  • off - Normal progression (turns off looping).
• speaker volume [0-100] (or vol [0-100]) - Adjusts volume.
• speaker stop - Stops playback.
• speaker clear - Clears the entire queue and stops playback.

⚡ Suno AI Link Examples

You can copy and paste links directly from your browser:

• https://suno.com/song/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• https://suno.com/playlist/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• https://cdn1.suno.ai/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.mp3

⚙️ Installation & Multiplayer

1. Install via r2modman, the Thunderstore App, or manually place LethalMusicSync.dll into your BepInEx/plugins/ folder.
2. To play with friends: All players in the lobby who wish to hear the synced music must have this mod installed. Syncing is automatic!

Changelog

1.0.1 - Bugfixes & Search Reliability Upgrades

• Fatal Harmony Crash Fix: Removed the redundant subclass BoomboxPocketPatch on BoomboxItem.PocketItem which was causing a fatal HarmonyException on startup and preventing all mod features from loading. Pocketing pause/resume is now safely handled via the base virtual GrabbableObject patch.
• Drop / Discard State Lock Fix: Modified BoomboxDiscardPatch to conditionally honor the active stream state when the boombox is dropped. Dropped playing boomboxes now keep playing custom music on the floor seamlessly, and dropped paused boomboxes remain paused to block game activation glitches.
• Terminal Control Ground Fix: Added explicit AudioSource stopping and state variables clear under the STOP and CLEAR blocks in ExecuteSyncCommand. Terminal commands can now successfully halt or reset the boombox stream even when it is lying on the ground.
• Direct YouTube Search Resolver: Implemented a highly stable browser simulation parser directly requesting youtube.com/results?search_query=... from the local player's IP, completely bypassing rate-limited and blocked public Invidious API instances.
• Multi-Endpoint Cobalt Failover: Added automated failover support for YouTube stream resolution, shifting from the locked official Cobalt API to community-run, Unlocked Cobalt instances (like apicobalt.mgytr.top) to prevent bad request/missing authentication errors.

1.0.0 - Initial Release

• Immersive Terminal Controls: Play music via the ship terminal with commands like boombox play [URL] and speaker play [URL].
• Direct Suno AI Link Resolution: Copy a Suno playlist or track link directly from your browser. The mod automatically extracts the song ID and points it to the direct streaming MP3 CDN link (cdn1.suno.ai/...), making Suno AI tracks play natively in the game with zero friction!
• Invisible Chat RPC Syncing: Perfect lobby-wide music sync without bloated netcode patches. Sync signals are hidden from the chat box for players.
• Ceiling Ship Speaker: A custom-spawned physical audio source in the ship's ceiling. Enjoy high-fidelity spatial audio that spreads through the ship cabin cleanly.
• Compatibility Patches: Integrated direct flags bypass on BoomboxItem.ItemActivate to prevent default game soundtracks from clashing with custom streams.