API Reference

Everything is available from Blueprints under the category Elys Persistent Music.

Two ways to reach the same functions:

• the Persistent Music function library — the nodes resolve the subsystem for you and do nothing outside of play;
• the Persistent Music Subsystem itself — Get Persistent Music, or Get Game Instance Subsystem → Persistent Music Subsystem — needed to bind the events.

Playback

Play Music

Pin	Type	Default	Meaning
Music	Sound Base	—	The track to play. Sound Wave, Sound Cue or MetaSound Source.
Fade In Time	Float	-1	Seconds. -1 uses the project default.
Volume	Float	-1	1 is the asset volume. -1 uses the project default.
b Loop	Bool	true	Restart the track when it ends. Assets that already loop are untouched.
End Notice Time	Float	-1	Seconds before the end at which On Music Ending fires. -1 uses the project default, 0 never fires it.

Starts the global track. Calling it with the track already playing does nothing (the volume is still applied), so the node is safe in the Begin Play of every level. Calling it with a different track fades over to it.

Switch Music

Pin	Type	Default	Meaning
New Music	Sound Base	—	The track to fade to.
Crossfade Time	Float	-1	Seconds. -1 uses the project default crossfade.
End Notice Time	Float	-1	Seconds before the end at which On Music Ending fires, for the new track.

Crossfades from the current track to another one. Passing the track already playing does nothing. If nothing is playing, the new track fades in.

Stop Music

Pin	Type	Default	Meaning
Fade Out Time	Float	-1	Seconds. -1 uses the project default, 0 cuts immediately.

Fades the music out and stops it. The state is Fading Out until the fade completes, then Stopped, and On Music Stopped fires.

Pause Music / Resume Music

No parameters. Pause holds the track where it is; Resume continues from the same position. Pausing does not count as playback time.

Volume

Set Music Volume

Pin	Type	Default	Meaning
Volume	Float	—	1 is the unmodified asset volume. 0 is silent.
Fade Time	Float	0.25	Seconds to reach the new volume. 0 applies it immediately.

The volume is kept across tracks and level changes.

Get Music Volume

Returns the current volume. Returns 0 outside of play.

State

Node	Returns	Meaning
Is Music Playing	Bool	True while a track plays, fade in and crossfade included.
Is Music Paused	Bool	True while a track is loaded but paused. (Subsystem only.)
Get Current Music	Sound Base	The track playing or paused, or None.
Get Music State	Music State	Stopped, Playing, Paused or Fading Out.
Get Persistent Music	Subsystem	The subsystem, or None outside of play.

Music State

Value	Meaning
Stopped	Nothing is playing.
Playing	A track is playing, including during a fade in or crossfade.
Paused	A track is loaded and paused.
Fading Out	Stop Music was called and the fade is still running.

Events

Available on the subsystem (Get Persistent Music → Bind Event to…).

Event	Payload	Fires when
On Music Ending	Music (Sound Base), Time Remaining (Float)	The current track is about to end, End Notice Time seconds before it does. Never fires for a track that loops forever, since it has no end.
On Music Stopped	—	The music stops, at the end of a fade out or immediately on a hard stop.

Time Remaining is the playback actually left, which is shorter than the requested notice when the notice is longer than the track. Feed it straight into the crossfade time of Switch Music to chain tracks with no gap.

Bind them from something that outlives the level, such as your Game Instance.

Project settings

Project Settings → Plugins → Elys Persistent Music (saved in DefaultGame.ini).

Setting	Default	Meaning
Default Volume	1.0	Volume used when Play Music receives -1.
Default Fade In Time	1.0	Fade used when Play Music receives -1.
Default Fade Out Time	1.0	Fade used when Stop Music receives -1.
Default Crossfade Time	2.0	Crossfade used when Switch Music receives -1.
Default End Notice Time	5.0	Notice used when Play Music or Switch Music receives -1. 0 disables the event.
Music Sound Class	none	Sound Class applied to the music component.
Restore Music After Level Load	true	Restart the track at its position if a map change dropped it.

C++

The runtime module is ElysPersistentMusic.

#include "ERP_PersistentMusicSubsystem.h"

if (UERP_PersistentMusicSubsystem* Music = GetGameInstance()->GetSubsystem<UERP_PersistentMusicSubsystem>())
{
    Music->PlayMusic(ExplorationTheme, /*FadeInTime=*/ 2.0f);
    Music->SwitchMusic(CombatTheme, /*CrossfadeTime=*/ 1.5f, /*EndNoticeTime=*/ 8.0f);
    Music->OnMusicEnding.AddDynamic(this, &AMyActor::HandleMusicEnding);
    Music->SetMusicVolume(0.6f, /*FadeTime=*/ 0.5f);
}

Public headers: ERP_PersistentMusicSubsystem.h, ERP_PersistentMusicLibrary.h, ERP_PersistentMusicSettings.h, ERP_PersistentMusicTypes.h. Log category: LogElysPersistentMusic.