Phaser3-plugin-sound-a11y NPM

Phaser3 Plugin Sound A11y

Sound A11y is a phaser plugin that provides common accessibility features for sound, captioning and volume control. The plugin creates 3 sound channels for background music, sound effects, and voice, and provides functionality to control the volume of each channel.

It utilizes accessible DOM elements for an options modal that controls captioning and volume as well as the caption cues.

Prerequisites

Installation

Clone the repository from git and run yarn install and you're set to go.

Demo / Development

The plugin is bundled with a demo which is used for testing during development. Build your demo to match your needs and test your plugin on the fly while developing. Run yarn demo or yarn dev in your terminal and direct your browser to http://localhost:3000.

Build plugin

Build the plugin including minified version. Targets the dist folder. npm run build

Usage

Usage can be seen in the demo folder.

Plugin Installation

1a. Install the package by running the following in your terminal yarn add phaser3-plugin-sound-a11y

1b. Import the SoundA11yPlugin plugin import SoundA11yPlugin from "phaser3-plugin-sound-a11y"

Ensure your game config has the parent and dom fields set. See Phaser API docs for game config for more information.

    parent: "game-container",
    dom: {
      createContainer: true
    },

Install the plugin by adding the following in your game config

  plugins: {
      scene: [
        { key: 'SoundA11yPlugin',
          plugin: SoundA11yPlugin,
          start: true,
          mapping: 'SoundA11yPlugin'
        }
      ]
  }

You now have access to the plugin in all scenes.

Initialize the plugin in the scene's create

this.SoundA11yPlugin.init({
  captions: captions,
  modalX: 500,
  modalY: 100,
  primaryColor: "green",
  captionsOn: true,
  volume: {
    music: 1,
    sfx: 1,
    voice: 1
  }
});

name	type	required	default	description
captions	object	false	{}	an object with sound names and markers as keys and the values are the caption cues
captionsOn	boolean	false	false	boolean that indicates if captions are on
modalX	integer	false	500	y position of the options modal
modalY	integer	false	100	x position of the options modal
primaryColor	string	false	"#0d68c2"	primary accent color for the options modal, takes hex or web safe color
volume	object	false	{ music: .2, voice: 1, sfx: .5}	volume setting for each sound channel

Plugin Usage

Adding a Sounds to a Channel

preload () {
  this.load.audio('title', '[your path to tile audio]');
}

create() {
  this.titleSoundObject = this.SoundA11yPlugin.add('voice', 'title');
}

Playing a sound

preload () {
  this.load.audio('title', '[your path to tile audio]');
}

create() {
  this.titleSoundObject = this.SoundA11yPlugin.add('voice', 'title');
  this.SoundA11yPlugin.play(titleSoundObject);
}

Adding Sounds with markers to a Channel

preload () {
  this.load.audio('title', '[your path to tile audio]');
}

create() {
  this.introSoundObject = this.SoundA11yPlugin.add('voice', 'intro');
  this.introSoundObject.addMarker({name: "intro_start", start: 0, duration: 3});
  this.introSoundObject.addMarker({name: "intro_beakers_exploded", start: 3, duration: 2});
  this.introSoundObject.addMarker({name: "intro_slime_everywhere", start: 5, duration: 2.9});
  this.introSoundObject.addMarker({name: "intro_slime_expanding", start: 7.9, duration: 5.3});
  this.introSoundObject.addMarker({name: "intro_end", start: 13.2, duration: 2});
  this.SoundA11yPlugin.play(introSoundObject);
}

Playing a sound with a marker

preload () {
  this.load.audio('title', '[your path to tile audio]');
}

create() {
  this.introSoundObject = this.SoundA11yPlugin.add('voice', 'intro');
  this.introSoundObject.addMarker({name: "intro_start", start: 0, duration: 3});
  this.introSoundObject.addMarker({name: "intro_beakers_exploded", start: 3, duration: 2});
  this.introSoundObject.addMarker({name: "intro_slime_everywhere", start: 5, duration: 2.9});
  this.introSoundObject.addMarker({name: "intro_slime_expanding", start: 7.9, duration: 5.3});
  this.introSoundObject.addMarker({name: "intro_end", start: 13.2, duration: 2});
}

Stopping All Sound Channels

this.SoundA11yPlugin.stop();

Stopping Music Sound Channels

this.SoundA11yPlugin.stop("music");

Stopping SFX Sound Channels

this.SoundA11yPlugin.stop("sound");

Stopping Voice Sound Channels

this.SoundA11yPlugin.stop("voice");

Plugin Methods

method	parameter type	parameter description	returns	description
init	config\	see example, #4	undefined	initializes the plugin with config settings
add	channel\ , key\, phaserSoundConfig\	the sound channel, Phaser sound key, Phaser sound object config	Phaser Sound Object	stops specified sounds channel
play	soundObject\	Phaser sound object	promise	plays phaser sound audio
stop	channel\	valid options are "sound", "music", "voice"	undefined	stops specified sounds channel

Captioning

File structure example

The keys are the sound name given to a Phaser sound object or it can be a marker on a Phaser sound object

{
  "title": "Toxic Slime Sweep",
  "intro_start": "Yikes, there was an accident in Laboratory X",
  "intro_beakers_exploded": "all the beakers exploded",
  "intro_slime_everywhere": "and spilled toxic slime everywhere",
  "intro_slime_expanding": "the slime is expanding quickly, solve the multiplication problems to clean up the slime",
  "intro_end": "and save the laboratory!"
}

Importing captions

It's recommended to store your captions in a json file and then import them.

import captions from './captions.json';
this.SoundA11yPlugin.init({
  captions: captions,
});

Built With

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!