FunkinSound

Extended FlxSound with delayed playback, pooling, and enhanced audio management

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