Audio Notification

Problem

Your plugin needs to provide some form of audio notification or audible alert.

Solution

Use the OpenSphere AudioManager. This is a singleton, and the play() function takes a label for the sound file to play:

AudioManager usage
1
2
    const audioManager = AudioManager.getInstance();
    audioManager.play('sound1');

There are three ways to provide the sound files - config settings, programmatically, or by user upload.

A config setting entry is shown below:

AudioManager sound file configuration
1
2
3
4
5
{
  "admin": { 
    "sounds": { "sound1" : "sounds/cowbell.wav" }
  }
}

A programmatic approach is shown below:

import {ROOT} from 'opensphere/src/os/os.js';
import AudioManager from 'opensphere/src/os/audio/audiomanager.js';

const audioManager = AudioManager.getInstance();
audioManager.addSound(ROOT + 'sounds/cowbell.wav', 'label');
audioManager.play('label');

User upload uses the normal Import Data dialog. Note that it only works in a standard browser environment if the target is a HTTP or HTTPS URL (different rules apply in a “wrapped” environment like [Electron](https://electronjs.org/)).

Discussion

The level of audio support, including the file formats and associated codecs that are supported, depends on browser capabilities.

In addition to the API shown earlier, AudioManager also supports muting the notifications. If your plugin makes use of audio notifications, we strongly suggest supporting global muting, as well as selective enable / disable of alerts.

audioManager.setMute(true);
const mute = audioManager.getMute(); // true - muted
audioManager.setMute(false); // now unmuted

Full code

Audio Notification Cookbook example - Full code
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
goog.declareModuleId('plugin.audioalert.AudioAlertPlugin');

import AudioManager from 'opensphere/src/os/audio/audiomanager.js';
import AbstractPlugin from 'opensphere/src/os/plugin/abstractplugin.js';
import PluginManager from 'opensphere/src/os/plugin/pluginmanager.js';


/**
 * Cookbook example for playing an audio alert.
 */
export default class AudioAlertPlugin extends AbstractPlugin {
  /**
   * Constructor.
   */
  constructor() {
    super();
    this.id = ID;
    this.errorMessage = null;
  }

  /**
   * @inheritDoc
   */
  init() {
    const audioManager = AudioManager.getInstance();
    audioManager.play('sound1');
  }
}

/**
 * @type {string}
 */
const ID = 'audioalert';

// add the plugin to the application
PluginManager.getInstance().addPlugin(new AudioAlertPlugin());