Unity Audio Player

What the system is for

Every Unity project ends up needing the same thing: a single place to ask for a sound effect. Button clicks, menu transitions, modal confirmations and gameplay events all want a clip to play, but every prefab tends to invent its own AudioSource wiring. The result is a project where the same click sound is duplicated in three prefabs, the volume is unbalanced and tracking down which AudioSource plays what becomes its own debugging task.

The Audio Player in Serenity centralizes clip playback. You describe clips through definitions, you ask the service to play them by reference or signal, and emitters take care of the actual AudioSource on the Unity side.

The Unity problem

Unity AudioSources are easy to add but hard to organize. Without a layer above them, every button reaches for a clip and every system grows its own audio code. Volumes drift, clips overlap and pausing the whole audio stack becomes a manual loop over scenes. UI sound feedback in particular is often baked into prefabs, which makes it impossible to restyle the UI without touching audio at the same time.

The other half of the problem is signals. When gameplay code wants to play a sound, it should not need a direct reference to an AudioSource on a specific GameObject. That coupling is what makes UI prefabs hard to reuse across screens.

How Serenity approaches it

Serenity exposes audio playback as use cases on the AudioPlayer service: AudioPlayerPlayClip, AudioPlayerPauseAllClips, AudioPlayerResumeAllClips and AudioPlayerStopAllClips. Clips are described through IAudioPlayerClipDefinition, grouped into AudioPlayerGroup entries, and played by AudioPlayerEmitter instances created through IAudioPlayerEmitterFactory.

The system also publishes signals such as PlayAudioClipSignal and PlayAudioClipFromGameSettingsSignal. Any code in the project can dispatch a signal to play a clip without resolving the service directly. UI Themes can carry sound references, so menus and modals get their feedback sounds from the active theme.

How it fits into Serenity

The Audio Player lives in the Serenity.AudioPlayer namespace. Domain entities describe clips, groups and emitters. The Application layer exposes the service, factories and use cases. The Infrastructure layer provides the Unity implementation, including the AudioSource-backed emitter, the service editor and the interface adapter UnityAudioPlayerGateway that the rest of the system talks to.

Audio Player connects with the Sound Mixer for category volumes, with Game Settings for persistent volume values, with the Event Dispatcher for play and pause signals, and with UI Themes so menus and modals can declare their sound feedback alongside their visuals.

Practical workflow

1. Author clip definitions for the sounds you want to expose, grouped by purpose or scene.
2. Configure an audio player emitter through CreateAudioPlayerEmitterInput when you need a new playback target.
3. Trigger sounds by calling AudioPlayerPlayClip with the right input, or by dispatching PlayAudioClipSignal.
4. Route UI sounds through the active UI theme so menus and modals stay consistent.
5. Use AudioPlayerPauseAllClips and AudioPlayerResumeAllClips when the game pauses or resumes.
6. Bind a sound effect volume to Game Settings and the Sound Mixer so the player can adjust it.

What you get

• Clip definitions described through IAudioPlayerClipDefinition
• Use cases AudioPlayerPlayClip, AudioPlayerPauseAllClips, AudioPlayerResumeAllClips and AudioPlayerStopAllClips
• Emitter factory that creates Unity AudioSource-backed emitters at runtime
• Signals PlayAudioClipSignal and PlayAudioClipFromGameSettingsSignal for decoupled triggering
• Audio player groups for organizing clips by purpose
• Interface adapter UnityAudioPlayerGateway between application and Unity layers
• Integration with Sound Mixer for category volumes and Game Settings for persistence
• Installer that registers the service for the whole project

When to use this

• Projects that need UI sound feedback and gameplay clips driven from the same service.
• Teams that want sounds attached to themes and signals instead of prefab AudioSources.
• Games that need to pause and resume all sounds together when the game changes state.
• Codebases that want a clean separation between sound effect playback and music tracks.

Related systems

• Unity Sound Mixer Per-category volume settings that drive your Unity Audio Mixer and persist through Game Settings.
• Unity Music Player Background music driven by track definitions, configurable transitions and typed signals you can hook into game state.
• Unity UI Themes ScriptableObject-based UI themes that share visuals and sound feedback across menus, modals and screens.
• Unity Game Settings Typed get and set use cases for bool, int, float and string settings, with persistence and update signals built in.