Class: SFX

SFX

Sound and audio manager utilising the PixiJS Sound plugin.
Docs: https://pixijs.io/sound/docs/index.html
- If no audio assets are queued in the project then this script will not be requested and is not needed.
- If the PIXI Sound script is not already loaded by the HTML, it will be loaded on first user interaction with the document from the following file path:
- `(build0)/js/pixi-sound.js`
Source:
Example
// app.js
sfx.bgLoopVolume = 0.6; // Set bg audio volume factor.
sfx.volume = 0.8; // Global volume factor.
sfx.waitForInteractionToLoad = false; // Will load immediately when able after initial assets and scene are ready.
sfx.setBgLoop('bg_loop'); // Assign bg loop.
sfx.enqueueBgResources({bg_loop_parent: {path: 'audio/bg_loop.mp3', sprites: {bg_loop: {start:0.5, end:4.5}}); // A bg audio as sprite to assist looping.
createApp(...)

// sampleScene.js
const {sfx} = require(`storymode`);
export default class MyClass extends Scene {
    static getSfxResources(){
      return {
        ding: 'sfx/ding.mp3',
        dong: {path: 'sfx/dong.mp3'}, // Optional path property
        mastertrack: {path:'sfx/master-track.mp3', sprites:{ // Optionally define sprites
          explosion: {start:0.5, end:1.0},
          success_bling: {start:1.0, end: 2.0}
        }},
        _fireloop: {path:'audio/fire.mp3', sprites:{
          fireloop: {start:0.2, end:2.8, loop:true}, // Looping
        }},
        ouch: {multi:true, total:3, prefix:'_ouch_', random:true, rezero:false}, // Create a multi sound that will step through members each subsequent call
        _ouch_0: {path:'sfx/ouch_0.mp3'},
        _ouch_1: {path:'sfx/ouch_1.mp3'},
        _ouch_2: {path:'sfx/ouch_2.mp3'},
      };
    }
    // ...
    sfx.playSFX('ding');
    sfx.playSFX('explosion', {start:1, complete:myFunction}); // Play sprite
  }
}

Extends

  • PIXI.utils.EventEmitter

Members

bgLoopEnabled :boolean

Whether background audio is enabled.
Type:
  • boolean
Source:

bgLoopVolume :number

The background volume level from 0.0 to 1.0.
Type:
  • number
Source:

(readonly, non-null) bgready :boolean

Will be `true` when the background audio assets queued by `sfx.enqueueBgResources()` are loaded.
Type:
  • boolean
Source:

pixisoundJSPath :string

A path to the pixi sound library js file.
- Default is 'js/vendor/pixi-sound.js'
- If editing this value do so before `storymode.createApp` is called.
Type:
  • string
Source:

sfxEnabled :boolean

Whether sound effects are enabled.
Type:
  • boolean
Source:

(readonly, non-null) sfxready :boolean

Will be `true` when the sound engine and registered audio assets are all loaded and ready to play.
This will be set to true before background audio assets are loaded.
Type:
  • boolean
Source:

sfxVolume :number

The sfx volume level from 0.0 to 1.0.
Type:
  • number
Source:

useSfxStateForBg :boolean

If `true` then will piggy back bg loop enabled to auto update to always follow sfx volume.
Type:
  • boolean
Source:

volume :number

Global volume factor.
Type:
  • number
Source:

waitForInteractionToLoad :boolean

If `false` then will load immediately when able, rather than waiting for user to interact with the DOM. Should be called before or during `storymode.createApp()` callback.
Type:
  • boolean
Source:

Methods

enqueueBgResources(bgResources)

Optionally call this method to queue global background audio resources.
- These assets will be loaded after all other assets are loaded and ready to use.
- Should be called before or during `storymode.createApp()` callback.
Parameters:
Name Type Description
bgResources Object Global resources to load. Eg. `{ding: 'sfx/ding.mp3', dong: 'sfx/dong.mp3'}`.
Source:
Example
// app.js
sfx.waitForInteractionToLoad = false;
sfx.setBgLoop('cello'); // Will be played when ready
sfx.enqueueBgResources({cello: 'audio/cello.mp3'});
createApp(...)

// Alternatively use a sprite for smoother looping:

// app.js
sfx.setBgLoop('spriteloop');
sfx.enqueueBgResources({bg_loop: 'audio/bg_loop.mp3',
bg_loop_sprite: {path:'audio/my-music.mp3', sprites:{
 spriteloop: {start:0.1, end:4.9},
}}});

fadeGlobalVolume(volume, duration)

Optionally call this method gradually change the global volume by a set factor.
- Can be called anytime, before `storymode.createApp()`.
- Should be called before or during `storymode.createApp()` callback.
Parameters:
Name Type Description
volume number Volume factor from 0.0 to 1.0. Not releated to sfx / bg volume values.
duration number The fade duration.
Source:

getMultiCounter(soundID) → {int}

Gets the current counter index for the given multisound.
Parameters:
Name Type Description
soundID string The multi sound identifier.
Source:
Returns:
counter - The multi sound counter (zero-indexed).
Type
int

getMultiTotal(soundID) → {int}

Gets the total individual sounds for the given multisound.
Parameters:
Name Type Description
soundID string The multi sound identifier.
Source:
Returns:
total
Type
int

playSFX(soundID, options)

Plays requested audio resource.
Parameters:
Name Type Default Description
soundID string The multi sound identifier.
options SFX.PlaybackOptions | number null Playback options, if a number then will be set as the delay value.
Source:

registerMixer(mixerObjopt)

Register a mixer object to affect volume factor of specified sounds.
Set to null to remove.
Supports simple prefix glob patterns in the format of `mysound_*`.
Parameters:
Name Type Attributes Default Description
mixerObj Object <optional>
 null The configuration object. Eg. {sound_effect_1: 1.0, sound_effect_2:1.0, vo_*:1.0}.
Source:

resetMulti(soundID)

Resets the counter associated with the multisound to zero, if random is set to true will shuffle its members.
Parameters:
Name Type Description
soundID string The multi sound identifier.
Source:

setBgLoop(soundID)

Sets the resource id to be the looping background music track.
Parameters:
Name Type Description
soundID string The sound identifier.
Source:

setMultiRezero(soundID, rezero)

Sets whether the given multisound should rezero after getting to the last sound in the sequence.
Parameters:
Name Type Description
soundID string The multi sound identifier.
rezero boolean Whether to go back to zero or stay on last sound.
Source:

stopAll()

Stop all sound playback.
- Reset concurrent sound tracking.
Source:

stopSFX(soundIDopt)

Stops playback of sfx audio.
Parameters:
Name Type Attributes Default Description
soundID string <optional>
 null The sound identifier, set to null or '*' to stop all looping sfx audio.
Source:

toggleBgLoopEnabled()

Toggle background audio enabled state.
Source:

toggleSfxEnabled()

Toggle sound effect enabled state.
Source:

Type Definitions

PlaybackOptions

Called after initial assets are loaded.
Type:
  • Object
Properties:
Name Type Attributes Default Description
delay number <optional>
 0 Delay before playback, in seconds.
volume volume <optional>
 1.0 Volume multiplier.
Source:

Events

bgloop_enabled_change

Called when bg loop enabled state changes.
Source:

bgready

Called when background audio files are loaded, this will be after all other audio files queued by scenes.
Source:
Example
if (!sfx.bgready){
 sfx.on('bgready', this.onBgReady, this)
} else {
 onBgReady();
}

onBgReady() {
 sfx.off('bgready', this.onBgReady, this)
}

sfx_enabled_change

Called when sound effects enabled state changes.
Source:

sfxready

Called when audio library and audio files are loaded, though background files may still be downloading.
Source:
Example
if (!sfx.sfxready){
 sfx.on('sfxready', this.onSfxReady, this)
} else {
 onSfxReady();
}

onSfxReady() {
 sfx.off('sfxready', this.onSfxReady, this)
}