Unity Music Player

What the system is for

Background music in Unity tends to start as a single AudioSource that plays on Awake. Then there is a second one for menu music, a third for boss music, and a custom script that swaps clips and tries to fade between them. Pause, resume and skip end up scattered across managers, and the moment the game adds a new state the music code has to be touched again.

The Music Player in Serenity treats music as a typed, configurable system. Music tracks are defined as assets, the service exposes explicit use cases for play, pause, resume, stop and skip, and transitions between tracks have a defined type instead of a one-off coroutine.

The Unity problem

Music is one of the systems that suffers the most from gradual growth. A simple background loop becomes a dynamic system once the game has menus, levels, cutscenes and a pause state. Hand-rolled music managers usually end up with global statics, hard-coded clip references and a fade routine that does not quite handle all the edge cases. Crossfading, queuing the next track and resuming after pause are easy to get wrong individually, and even easier to get wrong together.

Music also has to react to game state. Entering a menu, pausing the game, starting a session and changing game mode are all moments where the music should react. Without a clean integration, those reactions are sprinkled across scripts that should not know about audio at all.

How Serenity approaches it

Serenity exposes music playback through use cases MusicPlayerPlaySong, MusicPlayerPlaySongById, MusicPlayerPauseSong, MusicPlayerResumeSong, MusicPlayerStopSong, MusicPlayerPlayNextSong and MusicPlayerPlayPreviousSong. Tracks are described through IMusicTrackDefinition and stored as MusicTrack entities. Transitions between tracks are configured through MusicPlayerTransitionType, which avoids ad hoc fading code.

The service publishes signals such as PlayMusicTrackSignal and PlayMusicTrackFromGameSettingsSignal, so the rest of the project can request music changes without referencing the service directly. The Unity implementation is provided by UnityMusicPlayerService.

Playback by id makes it easy to drive music from external data such as a level definition or a saved game. The service knows how to resolve the id against the configured tracks, so the calling code only needs to know which song it wants to hear next.

How it fits into Serenity

The Music Player belongs to the Serenity.MusicPlayer namespace. Domain entities describe music tracks. The Application layer exposes the use cases, the service interface IMusicPlayerService and the music gateway IMusicPlayerGateway. The Infrastructure layer provides UnityMusicPlayerService and an editor for settings.

Music Player connects naturally with Game Mode for entering and leaving gameplay states, with the Event Dispatcher for routing signals, with the Sound Mixer for music category volume, with Game Settings for persistent music preferences, and with the Audio Player for sound effects that should not be confused with the background track.

Practical workflow

1. Create music track definitions for each piece of music you want to expose.
2. Configure transitions on each track or per request using MusicPlayerTransitionType.
3. Let the music installer register the service through the initialization pipeline.
4. Dispatch PlayMusicTrackSignal or call MusicPlayerPlaySong to start a track.
5. React to Game Mode signals to switch tracks on menu enter, game start, pause and resume.
6. Bind a music volume slider to Game Settings and the Sound Mixer category for music.

What you get

• Music track definitions described through IMusicTrackDefinition
• Use cases for play, play by id, pause, resume, stop, next and previous
• Configurable transitions via MusicPlayerTransitionType
• Signals PlayMusicTrackSignal and PlayMusicTrackFromGameSettingsSignal
• Unity implementation UnityMusicPlayerService backed by a music gateway
• Integration with Game Mode signals for state-driven music changes
• Integration with Sound Mixer for music category volume
• Installer that registers the music player for the whole project

When to use this

• Projects with more than one music track and at least one state transition between them.
• Games that need crossfades or other transitions without writing one-off coroutines.
• Teams that want music changes to react to game state rather than being triggered manually.
• Codebases that want music volume tied to a real Sound Mixer category instead of an AudioSource volume field.

Related systems

• Unity Audio Player Centralized clip playback with definition assets, emitters and typed signals for UI and gameplay sounds.
• Unity Sound Mixer Per-category volume settings that drive your Unity Audio Mixer and persist through Game Settings.
• Unity Game Mode System Typed game state transitions with signals, pause strategies and a readiness gate that other systems can subscribe to.
• Unity Game Settings Typed get and set use cases for bool, int, float and string settings, with persistence and update signals built in.