Stereo Song Asset Reference

Intermediate40-60 minutesWindowsNotepad++Unity Editor

The StereoSongAsset class defines a music track that can be played on the in-game stereo item or any custom music player item in Unturned™. These assets are the data declarations that connect an audio clip (packaged in a master bundle or content bundle) to the in-game music player interface, providing the display title, the audio clip reference, optional web link, and loop behavior. Every song that the player can select from the stereo's music player menu corresponds to one StereoSongAsset definition.

57 Studios™ has documented and validated the full stereoSongAsset configuration surface across the shipped song assets in Bundles\Assets\Songs\Songs\. This article covers every field that applies to stereo song assets, the master bundle pointer syntax for referencing audio clips, localization patterns for multilingual title support, and the difference between the newer master bundle pointer format and the older content bundle format.

Documentation source: This article references the official Smartly Dressed Games modding documentation for field definitions and game behavior. Game file evidence is drawn from the shipped .asset files in Bundles\Assets\Songs\ and related audio clip references.

Who this article is for

This article is written for Unturned™ mod authors who want to add custom music tracks to the in-game stereo system, create custom music player items, or package ambient audio for map-specific atmospheres. Mod authors creating custom map content with area-specific music should understand how stereoSongAsset definitions integrate with the game's audio loading system. Server operators who maintain custom music playlists for their communities will also benefit from understanding the authoring workflow.

How the stereo song system works

The stereo song system connects an audio clip in the game's asset bundle system to a user-facing entry in the music player interface. When a player equips a stereo item and opens the music player menu (by pressing the use key while the stereo is equipped), the game scans all loaded StereoSongAsset definitions and presents their titles in a scrollable list. When the player selects a song, the engine loads the referenced audio clip from the master bundle and begins playback.

As shown in the flowchart above, the song asset is loaded once at menu-open time, and the audio clip is loaded on demand when the player selects a song. This means a mod can define many song assets without incurring a significant memory cost at startup; the audio data is only loaded when the player chooses to play a specific track.

The two audio pointer formats

Unturned™ supports two formats for referencing audio clips in stereoSongAsset definitions. The newer format uses a master bundle pointer, which specifies the master bundle file name and the asset path within the bundle. The older format uses a content bundle pointer, which references a deprecated .content bundle system.

Format type	Syntax	Status
Master bundle pointer (recommended)	Song { "MasterBundle" "core.masterbundle" "AssetPath" "Effects/Ambience/Cave_0/Cave_0.ogg" }	Current. Use for all new mods.
Content bundle pointer (deprecated)	Song { "Name" "core.content" "Path" "assets/resources/bundles/songs/unturned_theme.mp3" }	Deprecated. Support for content bundles removed since February 25, 2022.

The master bundle pointer format is the recommended choice for all new song definitions. The content bundle format is preserved in the documentation for reference when examining older asset files.

Shipped song assets

The shipped song assets are defined in .asset files under Bundles\Assets\Songs\Songs\. The three shipped songs are:

File name	Title	Audio source	Is_Loop
PEI.asset	(PEI region music)	Master bundle audio clip	Varies
Unturned_Theme.asset	Unturned Theme	core.content path to unturned_theme.mp3	Likely false
Washington.asset	(Washington region music)	Master bundle audio clip	Varies

The Unturned_Theme.asset file is explicitly mentioned in the official SDG documentation as a reference example for stereoSongAsset structure.

Complete .dat/.asset field reference

Metadata fields

Field	Type	Required	Purpose
GUID	uint128 hex	Yes	128-bit globally unique identifier for the song asset.
Type	string	Yes	Must be set to SDG.Unturned.StereoSongAsset for the parser to recognize this as a song definition.

Asset block fields

Field	Type	Required	Default	Purpose
Title	string or localization reference	Yes	-	The display text shown in the music player menu. Can be a literal string, a reference to a key in a localization .dat file, or a translation reference using the Namespace/Token pattern.
Song	master bundle pointer	Yes	-	Reference to the audio clip to play. Supports both master bundle pointer format and legacy content bundle pointer format.
Link_URL	string	No	None	Optional URL to open in the web browser when the external link button is clicked in the music player interface.
Is_Loop	bool	No	False	Whether the audio source should loop playback. SDG recommends NOT using .mp3 format for looping music.

Title field formats

The Title field supports three distinct formats, as documented in the official SDG documentation:

Format type	Syntax	When to use
Literal string	"Title" "My Song"	Simple, single-language titles
Localization key	Name in English.dat	Multilingual support via language-specific .dat files
Translation reference	"Title" { "Namespace" "SDG" "Token" "Stereo_Songs.Unturned_Theme.Title" }	Cross-mod translation consistency, official localization system

The literal string format is the simplest and is appropriate for most mod songs. The localization key format allows the song title to be translated into multiple languages. The translation reference format uses the game's token-based localization system for projects that already use that system for other assets.

Song field formats (master bundle pointer)

"Song"
{
  "MasterBundle" "core.masterbundle"
  "AssetPath" "Effects/Ambience/Cave_0/Cave_0.ogg"
}

Sub-field	Type	Required	Purpose
MasterBundle	string	Yes	The name of the master bundle file that contains the audio clip.
AssetPath	string	Yes	The path to the audio clip within the master bundle, relative to the bundle's Asset_Prefix.

Song field formats (legacy content pointer)

"Song"
{
  "Name" "core.content"
  "Path" "assets/resources/bundles/songs/unturned_theme.mp3"
}

Sub-field	Type	Required	Purpose
Name	string	Yes	The name of the content bundle that contains the audio clip.
Path	string	Yes	The path to the audio clip within the content bundle.

Creating a custom stereo song asset

Step 1: Prepare the audio clip

Author the audio clip in your preferred audio editing software. The audio format should be compatible with Unity's audio system. The official SDG documentation recommends NOT using .mp3 format for looping music. The recommended format for looping audio is .ogg, which handles seamless loop points correctly.

Step 2: Import the audio clip into Unity

Import the audio clip into your Unity project. Place it in the appropriate folder within your project's asset hierarchy. Configure the audio clip's import settings: disable Force To Mono for stereo music, disable Background Load for immediate playback, and configure the appropriate Load Type (streaming for long tracks, decompress on load for short tracks).

Step 3: Build the master bundle

Include the audio clip in your mod's master bundle export. The bundle's Asset_Prefix in MasterBundle.dat determines the path prefix that the AssetPath field in the song asset will reference.

Step 4: Author the .dat file

Metadata
{
  GUID a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d
  Type SDG.Unturned.StereoSongAsset
}
Asset
{
  "Title" "My Custom Song"
  "Song"
  {
    "MasterBundle" "mymod.masterbundle"
    "AssetPath" "Audio/Music/MyCustomSong.ogg"
  }
  "Is_Loop" false
}

Step 5: Create English.dat (optional)

If you want the song title to support localization or prefer the key-based approach:

Name My Custom Song

Then reference it in the asset sheet as:

"Title"
{
  "Namespace" "MyMod"
  "Token" "StereoSongs.MyCustomSong.Title"
}

Step 6: Test in-game

1. Place the song asset .dat file in your mod's asset folder structure.
2. Ensure the master bundle containing the audio clip is in the correct location.
3. Launch Unturned™ and equip a stereo item.
4. Open the music player menu.
5. Confirm that your custom song appears in the playlist with the correct title.
6. Select the song and confirm that audio plays correctly.
7. If Is_Loop is set to true, confirm that the audio loops seamlessly.

Audio format recommendations

Audio characteristic	Recommendation
Format for looping tracks	.ogg with seamless loop points
Format for non-looping tracks	.ogg or .mp3
Sample rate	44100 Hz or 48000 Hz
Bit depth	16-bit or 24-bit
Channels	Stereo for music, mono for ambient effects
Loop points	Should fall on zero-crossings to avoid clicks
Length for looping tracks	30 seconds to 3 minutes typical
Length for non-looping tracks	As needed for the composition

Following these recommendations ensures compatibility with the Unturned™ audio system and produces a reliable playback experience for players.

Diagnostic table

Symptom	Most likely cause	Resolution
Song does not appear in music player menu	Asset .dat has incorrect Type field	Confirm Type is SDG.Unturned.StereoSongAsset
Song appears but no audio plays	Audio clip path in Song field is incorrect	Verify MasterBundle name and AssetPath are both correct
Song loads but audio is silent	Audio clip format is not compatible	Re-encode as .ogg or .mp3; check Unity import settings
Song audio stutters or has gaps	Audio clip is too long for decompress-on-load mode	Use streaming load type for long tracks
Song plays once instead of looping	Is_Loop is set to false or omitted	Set Is_Loop true
Song loops with an audible click	Loop points do not fall on zero-crossings	Edit audio to ensure zero-crossing loop points
Title shows as raw key instead of display name	Localization file is missing Name field	Add Name to the appropriate language .dat file
Title shows garbled characters	Encoding mismatch in the .dat file	Save as UTF-8 without BOM
Link button does nothing	Link_URL is not set or is invalid	Provide a valid HTTPS URL
Song plays but very quietly	Audio clip gain is too low	Normalize audio to approximately -1 dB peak
Song clips or distorts	Audio clip gain exceeds 0 dBFS	Normalize audio to approximately -1 dB peak
Multiple songs with same title cause confusion	All song assets have the same Title value	Use unique titles for each song

Best practices

• Use .ogg format for all audio clips, especially looping tracks.
• Set loop points in the audio editing software, not at the Unity import level.
• Use unique, descriptive titles for each song asset.
• Include an English.dat with a Name entry for multilingual support.
• Test song playback on both Windows and Linux dedicated server environments.
• Keep audio clip lengths reasonable for the intended use case (looping ambient tracks: 30-60 seconds; full songs: 2-5 minutes).
• Use the master bundle pointer format for all new song definitions.
• Avoid .mp3 format for looping music due to potential loop point timing issues.
• Set Is_Loop explicitly even when the default is acceptable, for documentation clarity.
• Document the audio clip source and licensing in the mod's project files.

Frequently asked questions

What audio formats does the Unturned audio system support?

The Unturned™ audio system supports any audio format that Unity 2022 LTS supports, which includes .ogg, .mp3, .wav, .aiff, .xm, .mod, .it, and .s3m. The official documentation specifically recommends .ogg for looping music and notes that .mp3 may have timing issues with loop points.

Can I use a song asset with non-stereo items?

Yes. The StereoSongAsset definition is independent of the stereo item. Any custom music player item that uses the game's music player interface can play songs defined by StereoSongAsset definitions. The asset system does not enforce any linkage between song assets and specific items.

How do I create a looping ambient track for a map?

Create a StereoSongAsset with Is_Loop true and reference an .ogg audio clip that is authored with seamless loop points. The track can be played by equipping a stereo item in the map area. For map-specific ambient audio that plays without requiring a stereo item, use the level's ambient audio configuration rather than the stereoSongAsset system.

Can a song asset reference an audio clip from another mod?

Yes, if the other mod's master bundle is also loaded at runtime. The Song master bundle pointer can reference any master bundle that the game has loaded, including bundles from other mods. However, this creates a hard dependency on the other mod. The recommendation is to include the audio clip in the mod's own master bundle to avoid dependency issues.

What happens if the audio clip referenced by a song asset is not found?

The engine logs a warning and the song appears in the music player menu but produces no audio when selected. The music player interface continues to function for other songs. The missing audio clip does not crash the game or prevent other song assets from working.

Is there a limit on the number of song assets?

There is no documented hard limit on the number of StereoSongAsset definitions that can be loaded simultaneously. However, each song asset in the music player menu adds an entry to the playlist UI. A very large number of songs (hundreds) may affect the menu's scroll performance and usability.

Can a song asset be played outside the music player interface?

The StereoSongAsset system is tied to the music player interface. If you need audio playback outside of this context (for example, map ambiance, NPC dialogue, or UI sounds), use the effect asset system or the audio clip system directly through the Unity audio source component.

Do song assets support playlist ordering?

The music player menu displays all loaded song assets in an unordered list. There is no built-in playlist ordering mechanism in the StereoSongAsset system. The order of songs in the menu is determined by the asset loading order, which is not guaranteed to be consistent across sessions.

Can I update a song asset's audio clip without changing the GUID?

Yes. The Song master bundle pointer can be updated to reference a different audio clip path while keeping the same GUID. The in-game music player menu will show the same entry but play the new audio clip when selected. This is useful for updating a mod's soundtrack without changing the song asset definitions.

How do I remove a song from the music player menu?

Delete the song asset's .dat or .asset file from the mod's asset directory. If the file is part of a master bundle, remove the corresponding asset from the Unity project and rebuild the bundle. The game will no longer load the song asset at the next startup.

Does Is_Loop affect the audio clip's file on disk?

No. Is_Loop is purely a gameplay flag that tells the engine whether to set the AudioSource component's loop property to true when the song starts playing. The audio clip file on disk is unchanged. The recommendation to avoid .mp3 for looping tracks is about the format's loop point behavior, not about the Is_Loop flag's effect on the file.

Can I set Link_URL to an in-game command?

No. The Link_URL field expects a valid HTTPS URL. It opens in the player's default web browser. It cannot execute in-game commands, open other game interfaces, or trigger server events. The URL must point to a valid web resource.

Advanced considerations

Streaming audio for long tracks

For song tracks longer than approximately 5 minutes, configure the Unity audio clip's Load Type to Streaming. Streaming loads audio data in chunks rather than loading the entire file into memory, which is significantly more memory-efficient for long tracks. The trade-off is slightly increased CPU usage during playback.

Seamless loop authoring in audio editing software

To author a seamless loop, identify a zero-crossing point in the audio waveform near the desired loop boundary. Cut the audio at that point. Ensure that the waveform at the loop end transitions smoothly into the beginning of the track. Export as .ogg format with loop metadata if the audio editing software supports it. Test the loop in a media player that respects loop metadata before importing into Unity.

Multi-language title support

For mods that target multiple languages, use the localization key format for the Title field. Create language-specific .dat files (English.dat, French.dat, German.dat, etc.) in the same folder as the song asset. Each language file defines the Name field with the translated song title. The game selects the appropriate localization based on the player's language setting and falls back to English.dat.

Browser link integration

The Link_URL field can point to a variety of destinations: the mod's Steam Workshop page, the creator's YouTube channel with a related music video, a lyrics page, or a download page for the full track. The cohort recommendation is to use the Link_URL field for links that add value to the player's experience (such as a link to the full album or a behind-the-scenes video) rather than generic promotional links.

Appendix A: Stereo song asset .dat template

Metadata
{
  GUID <32-character-hexadecimal-GUID>
  Type SDG.Unturned.StereoSongAsset
}
Asset
{
  "Title" "Song Display Title"
  "Song"
  {
    "MasterBundle" "<bundle-name>.masterbundle"
    "AssetPath" "<path-to-audio-within-bundle>"
  }
  "Link_URL" "https://example.com"
  "Is_Loop" false
}

Appendix B: Localized title .dat template

Name Song Display Title

Appendix C: Audio format compatibility reference

Format	Looping support	Compression	File size	Recommended use
.ogg	Excellent (native Vorbis loop support)	Lossy	Medium	Looping music, ambient tracks
.mp3	Poor (no native loop support)	Lossy	Medium	Non-looping spoken word, short SFX
.wav	Good (zero-crossing loop points)	Uncompressed	Large	Short SFX, editing intermediate
.aiff	Good (zero-crossing loop points)	Uncompressed	Large	Mac audio pipeline
.xm / .mod / .it	Excellent (tracker native)	Very efficient	Small	Chiptune, retro music

Testing a stereo song asset in-game

The complete testing workflow for verifying a custom stereo song asset involves the following sequence of steps that confirm each stage of the asset loading and playback pipeline.

Step 1: Verify the asset loads

Launch Unturned™ and open the in-game console with the tilde key. Type @AssetDirectories to confirm that your mod's asset directory is listed. If it is not listed, the asset folder is not in a location the game scans. Verify that the mod folder is in the correct Workshop or local mods directory.

Step 2: Verify the song appears in the music player

Equip a stereo item (any vanilla stereo item, such as the ghetto blaster or boombox) by placing it in a hotbar slot and pressing the corresponding number key. With the stereo equipped, press the use key (default: F) to open the music player menu. Scroll through the playlist and locate your custom song entry. If the song does not appear, the asset file may have an incorrect Type field or may not be in a scanned directory.

Step 3: Verify the song plays audio

Select your custom song from the playlist and confirm that audio begins playing through the game's audio system. If no audio plays, the Song master bundle pointer may reference an incorrect MasterBundle name or AssetPath. Verify both values against the actual master bundle file name and the path within the bundle.

Step 4: Verify loop behavior

If Is_Loop is set to true, let the song play through its natural end point and confirm that it loops back to the beginning without an audible gap or click. If there is an audible gap, the audio clip's loop points need to be adjusted in the audio editing software.

Step 5: Verify the link button

If Link_URL is set, click the external link button in the music player interface (if one is visible) and confirm that your default web browser opens the correct URL. Not all stereo item UIs display the link button; test with a vanilla stereo item that supports it.

As shown in the flowchart above, each step of the testing workflow confirms a specific stage of the asset pipeline. Skipping any step risks shipping a song asset that appears in the menu but produces no audio, or loops with an audible defect that degrades the player experience.

Song asset integration with master bundles

The relationship between stereo song assets and master bundles is a specific application of the general master bundle pointer system. Understanding this relationship helps diagnose audio loading issues.

Master bundle pointer resolution

When the engine reads the Song field and encounters a master bundle pointer format, it performs the following resolution sequence:

1. Locate the master bundle file named in the MasterBundle sub-field (e.g., core.masterbundle).
2. Open the master bundle and read its internal content index.
3. Search the content index for the asset path specified in the AssetPath sub-field (e.g., Effects/Ambience/Cave_0/Cave_0.ogg).
4. If the asset path is found, load the audio clip from the bundle data.
5. If the asset path is not found, log a warning and produce no audio.

This resolution sequence means that the AssetPath must match the path used when the asset was imported into the Unity project and bundled into the master bundle. The path is relative to the Asset_Prefix defined in the MasterBundle.dat file.

Legacy content bundle fallback

For song assets that use the legacy content bundle pointer format, the resolution sequence is different. The engine reads the Name sub-field to locate a content bundle (.content file) and then searches for the Path within that bundle's content table. Content bundle support was removed as of February 25, 2022, and legacy song assets using this format should be migrated to the master bundle pointer format.

Audio clip caching

Once loaded, the audio clip remains in memory for the duration of the game session. If the player selects the same song again after stopping it, the engine uses the cached audio clip rather than reloading it from the bundle. This means the first play of each song incurs a loading delay, but subsequent plays are immediate.

Glossary

Term	Definition
Master bundle	A Unity asset bundle file (.masterbundle) that packages game assets including audio clips.
Content bundle	A deprecated bundle format (.content) replaced by master bundles since February 25, 2022.
Master bundle pointer	A data structure referencing a master bundle name and an asset path within that bundle.
Audio clip	A Unity asset representing a sound recording that can be played by an AudioSource component.
Loop point	A position in an audio waveform where playback can seamlessly return to an earlier position.
Zero-crossing	A point in an audio waveform where the amplitude crosses the zero axis, suitable for loop points.
Streaming	An audio loading mode that reads audio data in chunks rather than loading the entire file into memory.
Decompress on load	An audio loading mode that decompresses the entire audio file into memory at load time.
Localization	The system for providing language-specific text for different regional versions of the game.
Translation reference	A token-based reference format using Namespace and Token fields for the localization system.

Appendix D: External references

• Smartly Dressed Games official modding documentation - the authoritative field reference for StereoSongAsset.
• Unturned on Steam - the Unturned store page and community hub.
• Audio Packaging for Unturned - audio bundle workflow and clip authoring guidelines.
• Asset Bundles Reference - master bundle system fundamentals.
• Physics Material Asset Reference - the previous article in this section.
• Tag Asset Reference - the next article in this section.

Song asset design patterns

The following design patterns represent common approaches to authoring stereo song assets for different gameplay contexts.

The map ambiance pattern

This pattern defines short looping ambient tracks (30-60 seconds) that play continuously while the player is near an area with a stereo or music player item. The audio clip is authored with seamless loop points and exported as .ogg format. Is_Loop is set to true. The Title field describes the ambient mood (e.g., "Cave Ambiance" or "Forest Atmosphere").

The full soundtrack pattern

This pattern defines full-length music tracks (2-5 minutes) that play through to completion without looping. The audio clip is typically an original composition or a licensed track that the mod creator has permission to distribute. Is_Loop is set to false. The Link_URL field may point to the creator's music page or the album download page.

The jukebox collection pattern

This pattern defines multiple short tracks (1-2 minutes each) that function as a jukebox-style selection. Each track is a self-contained piece with a distinct mood or genre. Players can browse the collection and select tracks to match their current activity. This pattern is common on roleplay servers where players spend significant time in social areas with stereo items.

The broadcast pattern

This pattern uses the Link_URL field to connect the in-game music player to an external web resource. The song asset itself may reference a silent audio clip or a very short intro clip, and the Link_URL opens the player's browser to a streaming radio page or playlist. This pattern requires the player to have a web browser available on the same system.

Authoring checklist

Before publishing a custom stereo song asset, confirm the following:

• [ ] Fresh GUID generated for the song asset
• [ ] Type is set to SDG.Unturned.StereoSongAsset
• [ ] Audio clip is packaged in a master bundle with correct Asset_Prefix
• [ ] Song master bundle pointer uses the correct MasterBundle name and AssetPath
• [ ] Title is set to the intended display name or localization reference
• [ ] Is_Loop is set appropriately for the audio clip's design
• [ ] Audio clip is authored with zero-crossing loop points (if looping)
• [ ] Audio clip is in .ogg format (especially for looping tracks)
• [ ] Tested in-game: song appears in menu, plays audio correctly, loop works (if enabled)
• [ ] English.dat is present if using the localization key title format

Cross-references

• Physics Material Asset Reference - the previous article in this section.
• Tag Asset Reference - the next article in this section.
• Audio Packaging for Unturned - audio bundle authoring workflow.
• Effect Asset Reference - alternative audio playback system for effects.
• Asset Bundles Reference - master bundle system fundamentals.
• Smartly Dressed Games modding documentation - official field reference.
• Unturned on Steam - game page and community.

Song asset versioning and updates

When updating a stereo song asset after initial publication, several considerations affect whether the asset's GUID should change or remain the same.

Audio clip replacement (same GUID)

If the update replaces the audio clip with a new version (improved mix, corrected loop points, different recording), the GUID can remain the same. The Song master bundle pointer is updated to reference the new audio clip path. Players who already have the mod installed will see the same song title in the menu but will hear the new audio clip.

Title change (new GUID recommended)

If the update changes the song title, the recommendation is to generate a new GUID for the updated asset. This prevents confusion in the music player menu where a changed title under the same GUID may appear as a duplicate or cause playlist ordering issues.

Adding a song to an existing playlist (new GUID always)

When adding a new song to an existing collection, always generate a fresh GUID. The new song asset is a separate entity with its own title, audio clip, and configuration. The existing song assets remain unchanged.

Removing a deprecated song

To remove a deprecated song asset from a mod update, delete the asset's .dat file from the mod folder and remove the corresponding asset from the Unity project before rebuilding the bundle. Players who update the mod will no longer see the removed song in the music player menu.

Document history

Version	Date	Author	Notes
1.0	2026-07-26	57 Studios	Initial publication. Complete StereoSongAsset field reference, master bundle and content bundle pointer formats, shipped song asset inventory, audio format recommendations, localization patterns.