Skip to main content

​
Overview

FunkinSound extends FlxSound with additional functionality including delayed playback via negative song position, sound pooling for efficient memory management, and convenient static methods for immediate playback and recycling. Location: funkin.audio.FunkinSound

​
Key Features

  • Delayed playback support with negative timestamps
  • Object pooling for efficient memory reuse
  • Waveform data generation and caching
  • Music playback with metadata support
  • Partial sound loading for optimized memory usage
  • Volume change signals

​
Properties

​
muted
Bool
Mute this specific sound without affecting volume. When set to true, the sound is silenced.
​
paused
Bool
Whether the sound is currently paused.
​
isPlaying
Bool
Returns true if the sound is playing or scheduled to play (including negative timestamps).
​
waveformData
WaveformData
Lazily-loaded waveform data for this sound. Generated on first access and cached for subsequent use.
​
important
Bool
If true, forcefully adds this sound’s channel to the playing sounds list even when the channel limit is reached. Use sparingly!
​
volume
Float
The volume level (0.0 to 1.0).

​
Static Properties

​
onVolumeChanged
FlxTypedSignal<Float->Void>
A signal dispatched whenever the global volume changes.
​
pool
FlxTypedGroup<FunkinSound>
Internal pool of FunkinSound instances for efficient recycling.

​
Methods

​
play

play(forceRestart:Bool = false, startTime:Float = 0, ?endTime:Float):FunkinSound
Plays the sound. Supports negative startTime values for delayed playback.
​
forceRestart
Bool
default:"false"
If true, restarts the sound even if already playing.
​
startTime
Float
default:"0"
Time in milliseconds to start at. Negative values delay playback.
​
endTime
Float
Time in milliseconds to stop at.
​
return
FunkinSound
Returns the sound instance for method chaining.

​
pause

pause():FunkinSound
Pauses the sound, including sounds with negative timestamps that haven’t started yet.
​
return
FunkinSound
Returns the sound instance for method chaining.

​
resume

resume():FunkinSound
Resumes a paused sound. Handles sounds with negative timestamps correctly.
​
return
FunkinSound
Returns the sound instance for method chaining.

​
togglePlayback

togglePlayback():FunkinSound
Toggles between playing and paused states.
​
return
FunkinSound
Returns the sound instance for method chaining.

​
clone

clone():FunkinSound
Creates a copy of this sound that shares the same audio buffer and waveform data.
​
return
FunkinSound
A new FunkinSound instance with cloned data.

​
Static Methods

​
load

static function load(
  embeddedSound:FlxSoundAsset,
  volume:Float = 1.0,
  looped:Bool = false,
  autoDestroy:Bool = false,
  autoPlay:Bool = false,
  persist:Bool = false,
  ?onComplete:Void->Void,
  ?onLoad:Void->Void,
  important:Bool = false
):Null<FunkinSound>
Loads a sound synchronously from the pool or creates a new instance.
​
embeddedSound
FlxSoundAsset
required
The sound asset path or embedded sound resource.
​
volume
Float
default:"1.0"
Initial volume (0.0 to 1.0).
​
looped
Bool
default:"false"
Whether to loop the sound.
​
autoDestroy
Bool
default:"false"
Whether to destroy the sound when finished. Set to false to reuse the instance.
​
autoPlay
Bool
default:"false"
Whether to play immediately after loading.
​
persist
Bool
default:"false"
Whether to keep the sound across state changes.
​
onComplete
Void->Void
Callback when the sound finishes playing.
​
onLoad
Void->Void
Callback when the sound finishes loading.
​
important
Bool
default:"false"
If true, bypasses channel limits. Use sparingly!
​
return
Null<FunkinSound>
Returns the loaded sound, or null if loading failed or channels are exhausted.

​
loadPartial

static function loadPartial(
  path:String,
  start:Float = 0,
  end:Float = 1,
  volume:Float = 1.0,
  looped:Bool = false,
  autoDestroy:Bool = false,
  autoPlay:Bool = true,
  ?onComplete:Void->Void,
  ?onLoad:Void->Void
):Promise<Null<FunkinSound>>
Loads only a section of a sound file asynchronously. Useful for Freeplay previews to avoid loading entire songs.
​
path
String
required
The path to the sound file.
​
start
Float
default:"0"
Start position as a percentage (0.0 to 1.0).
​
end
Float
default:"1"
End position as a percentage (0.0 to 1.0).
​
volume
Float
default:"1.0"
Initial volume (0.0 to 1.0).
​
looped
Bool
default:"false"
Whether to loop the sound.
​
autoDestroy
Bool
default:"false"
Whether to destroy the sound when finished.
​
autoPlay
Bool
default:"true"
Whether to play immediately after loading.
​
onComplete
Void->Void
Callback when the sound finishes playing.
​
onLoad
Void->Void
Callback when the sound finishes loading.
​
return
Promise<Null<FunkinSound>>
A promise that resolves to the loaded sound or null if loading failed.

​
playMusic

static function playMusic(
  key:String,
  params:FunkinSoundPlayMusicParams
):Bool
Loads and plays music with optional metadata support. Automatically loads song metadata from music/<key>/<key>-metadata.json if available.
​
key
String
required
The music key. Music is loaded from music/<key>/<key>.ogg.
​
params
FunkinSoundPlayMusicParams
required
Configuration object for music playback. See below for properties.
​
return
Bool
Returns true if music started successfully, false if music was already playing or couldn’t start.

​
FunkinSoundPlayMusicParams

​
startingVolume
Float
default:"1.0"
Initial volume for the music.
​
suffix
String
default:"''"
Suffix for the music file (e.g., “-erect” for alternate tracks).
​
overrideExisting
Bool
default:"false"
Whether to override music if a different track is playing.
​
restartTrack
Bool
default:"false"
Whether to restart if the same track is already playing.
​
loop
Bool
default:"true"
Whether the music should loop.
​
mapTimeChanges
Bool
default:"true"
Whether to load and apply time signature changes from metadata.
​
pathsFunction
PathsFunction
default:"MUSIC"
Which Paths function to use (MUSIC or INST).
​
partialParams
PartialSoundParams
Parameters for partial loading (see loadPartial).
​
persist
Bool
Whether the sound persists across state changes.
​
onComplete
Void->Void
Callback when the music finishes.
​
onLoad
Void->Void
Callback when the music finishes loading.

​
playOnce

static function playOnce(
  key:String,
  volume:Float = 1.0,
  ?onComplete:Void->Void,
  ?onLoad:Void->Void,
  important:Bool = false
):Null<FunkinSound>
Plays a sound effect once and automatically destroys it when finished.
​
key
String
required
The sound key/path.
​
volume
Float
default:"1.0"
Playback volume (0.0 to 1.0).
​
onComplete
Void->Void
Callback when the sound finishes.
​
onLoad
Void->Void
Callback when the sound loads.
​
important
Bool
default:"false"
Bypass channel limits if true.
​
return
Null<FunkinSound>
Returns the sound instance or null if loading failed.

​
stopAllAudio

static function stopAllAudio(musicToo:Bool = false, persistToo:Bool = false):Void
Stops and destroys all sounds in the pool.
​
musicToo
Bool
default:"false"
If true, also stops the current music track.
​
persistToo
Bool
default:"false"
If true, also stops sounds marked as persistent.

​
setMusic

static function setMusic(newMusic:FunkinSound):Void
Sets the given sound as the current music track (FlxG.sound.music).
​
newMusic
FunkinSound
required
The sound to set as music.

​
Example Usage

​
Basic Sound Playback

// Play a sound effect once
FunkinSound.playOnce('sounds/confirm', 0.7);

// Load and manually control a sound
var sound = FunkinSound.load('sounds/scroll', 1.0, false, false, false);
sound.play();

​
Playing Music

// Simple music playback
FunkinSound.playMusic('freakyMenu', {
  startingVolume: 0.7,
  loop: true
});

// With custom configuration
FunkinSound.playMusic('tutorial', {
  startingVolume: 0.8,
  overrideExisting: true,
  mapTimeChanges: true,
  onLoad: () -> trace('Music loaded!'),
  onComplete: () -> trace('Music finished!')
});

​
Delayed Playback

// Start playback 500ms from now
var sound = FunkinSound.load('music/intro', 1.0);
sound.play(false, -500.0);

​
Partial Loading

// Load only the first 30% of a song
var promise = FunkinSound.loadPartial('songs/bopeebo/Inst', 0.0, 0.3, 1.0, true);
promise.future.onComplete(function(sound) {
  if (sound != null) {
    trace('Preview loaded!');
  }
});

​
Notes

  • Sounds with negative timestamps require the sound to be added to a scene with add() for the countdown timer to work
  • The important flag should be used sparingly as it bypasses audio channel limits
  • Waveform data is cached after first access for performance
  • The sound pool automatically recycles dead instances to reduce garbage collection

Build docs developers (and LLMs) love

Get started for freeTalk to us