Class UnityMusicPlayerService

Unity implementation of music player service providing music playback functionality.
Extends UnityAudioPlayerService with specialized music track management, playlist controls, and game settings integration.
Handles track sequencing, repeat modes, and event-driven music playback through the application's event dispatcher system.
Supports both direct music track playing and game settings-based music selection for dynamic audio configuration.

Inheritance

object

UnityMusicPlayerService

Implements

IMusicPlayerService

IService

IFoundationSettings

Namespace: Serenity.MusicPlayer.Infrastructure.Services

Assembly: Serenity.UnityMusicPlayer.Infrastructure.dll

Syntax

public class UnityMusicPlayerService : UnityAudioPlayerService, IMusicPlayerService, IService, IFoundationSettings

Constructors

UnityMusicPlayerService()

Declaration

public UnityMusicPlayerService()

Methods

AddMusicTrack(MusicTrack)

Adds a single music track to the current playlist.
Appends the provided music track to the existing collection of tracks.
Allows for dynamic expansion of the music library during runtime.

Declaration

public void AddMusicTrack(MusicTrack musicTrack)

Parameters

Type	Name	Description
MusicTrack	musicTrack	The MusicTrack to add to the playlist.

GetCurrentMusicTrack()

Gets the currently selected music track from the playlist.
Returns the track at the current index position in the music tracks collection.
Used for displaying current track information and managing playback state.

Declaration

public MusicTrack GetCurrentMusicTrack()

Returns

Type	Description
MusicTrack	The MusicTrack currently selected for playback.

GetCurrentTrackAudioSource()

Gets the Unity AudioSource component for the currently playing track.
Provides access to the AudioSource for advanced audio control and monitoring.
Returns null if no track is currently playing.

Declaration

public AudioSource GetCurrentTrackAudioSource()

Returns

Type	Description
AudioSource	The AudioSource component of the current track, or null if none is playing.

GetMusicTrackById(string)

Retrieves a music track from the playlist by its unique identifier.
Searches through the loaded music tracks collection to find a matching track ID.
Returns null if no matching track is found.

Declaration

public MusicTrack GetMusicTrackById(string id)

Parameters

Type	Name	Description
string	id	The unique identifier of the music track to retrieve.

Returns

Type	Description
MusicTrack	The MusicTrack with the specified ID, or null if not found.

GetMusicTracks()

Gets the complete collection of available music tracks.
Returns the current playlist containing all loaded music tracks.
Used for playlist management and track selection operations.

Declaration

public List<MusicTrack> GetMusicTracks()

Returns

Type	Description
List<MusicTrack>	The complete list of available MusicTrack objects.

PauseSong()

Pauses the currently playing music track.
Sets the playing state to false and pauses all active audio clips.
Music can be resumed later from the same position using ResumeSong.

Declaration

public void PauseSong()

PlayNextSong()

Advances to and plays the next song in the playlist.
Increments the current track index, wrapping to the beginning if at the end of the playlist.
Stops the current song and immediately starts playing the next track.

Declaration

public void PlayNextSong()

PlayPreviousSong()

Goes back to and plays the previous song in the playlist.
Decrements the current track index, wrapping to the end if at the beginning of the playlist.
Stops the current song and immediately starts playing the previous track.

Declaration

public void PlayPreviousSong()

PlaySong(MusicPlayerTransitionType, float)

Starts playback of the currently selected music track, transitioning out the previous track when one is active.
Falls back to CUT when the implementation cannot safely perform the requested transition.

Declaration

public void PlaySong(MusicPlayerTransitionType transitionType = 0, float transitionDuration = 0.5)

Parameters

Type	Name	Description
MusicPlayerTransitionType	transitionType	Transition strategy applied when moving from the current track to the new one.
float	transitionDuration	Duration of the transition in seconds. Ignored for CUT.

PlaySongById(string, bool, MusicPlayerTransitionType, float)

Starts playback of a specific music track resolved by its id, independently of the playlist position.
Resolves the id against the configured music tracks list and plays it with the requested loop behavior, transitioning out the previous track when one is active. Falls back to CUT when the implementation cannot safely perform the requested transition.

Declaration

public void PlaySongById(string musicTrackId, bool loop, MusicPlayerTransitionType transitionType = 0, float transitionDuration = 0.5)

Parameters

Type	Name	Description
string	musicTrackId	The id of the music track to play.
bool	loop	Whether the track should loop when it finishes.
MusicPlayerTransitionType	transitionType	Transition strategy applied when moving from the current track to the new one.
float	transitionDuration	Duration of the transition in seconds. Ignored for CUT.

ResumeSong()

Resumes playback of the previously paused music track.
Sets the playing state to true and resumes all paused audio clips.
Continues music playback from the position where it was paused.

Declaration

public void ResumeSong()

SetMusicTracks(List<MusicTrack>)

Sets the complete music tracks collection for the player.
Replaces the current playlist with the provided music tracks collection.
Resets the playlist and allows for dynamic music library updates.

Declaration

public void SetMusicTracks(List<MusicTrack> musicTracks)

Parameters

Type	Name	Description
List<MusicTrack>	musicTracks	The new collection of music tracks to use as the playlist.

StopSong()

Stops the currently playing music track completely and cancels any in-flight transition.
Sets playing state to false, releases both the current and previous transition sources, and stops all audio clips.
Unlike pause, this resets playback position and requires starting from the beginning when playing again.

Declaration

public void StopSong()

SubscribeToEventDispatcherEvents()

Subscribes to event dispatcher events for music playback control.
Registers handlers for PlayMusicTrackSignal and PlayMusicTrackFromGameSettingsSignal events.
Enables event-driven music control throughout the application.

Declaration

public override void SubscribeToEventDispatcherEvents()

Update()

Unity Update method called every frame to monitor music playback state.
Continuously checks for track ending conditions and handles automatic track transitions.
Ensures seamless music playback and proper playlist progression.

Declaration

public void Update()

ValidateAudioGameSettings(string, UnityAudioGameSettingsDefinition)

Validates audio game settings for music player compatibility.
Ensures that the provided audio game settings are configured correctly for music playback.
Verifies that settings use SELECTABLE value type and that all options reference valid UnityMusicTrackDefinition assets.
Throws exceptions if validation fails to prevent runtime errors.

Declaration

public override void ValidateAudioGameSettings(string id, UnityAudioGameSettingsDefinition audioGameSettings)

Parameters

Type	Name	Description
string	id	The identifier for the audio game settings being validated.
UnityAudioGameSettingsDefinition	audioGameSettings	The audio game settings definition to validate.

Exceptions

Type	Condition
Exception	Thrown when audio game settings are invalid or contain invalid references.

Implements

IMusicPlayerService

IService

IFoundationSettings