soundworks

Appearance

soundworks | plugin platform init ​

npm version

soundworks plugin to handle initialization of browser client features that require a user interaction such as resuming audio context, etc.

Tutorial: https://soundworks.dev/tutorials/plugin-platform-init.html

Table of Contents ​

Installation ​

sh
npm install @soundworks/plugin-platform-init --save

Usage ​

Server ​

js
// src/server/index.js
import { Server } from '@soundworks/core/server.js';
import ServerPluginPlatformInit from '@soundworks/plugin-platform-init/server.js';

const server = new Server(config);
//
server.pluginManager.register('platform-init', ServerPluginPlatformInit);

Client ​

js
// src/clients/**/index.js
import { Client } from '@soundworks/core/client.js';
import ClientPluginPlatformInit from '@soundworks/plugin-platform-init/client.js';

const client = new Client(config);
const audioContext = new AudioContext();
// pass the audio context to the plugin
client.pluginManager.register('platform-init', ClientPluginPlatformInit, { audioContext });

await client.start();

console.log(audioContext.state === 'running');

Available features ​

By default, the @soundworks/plugin-platform-init provide a way to resume audio context (as shown above) but also to access microphone, camera streams, and motion sensors through the @ircam/devicemotion package.

sh
npm install --save @ircam/devicemotion
js
// src/clients/**/index.js
import { Client } from '@soundworks/core/client.js';
import ClientPluginPlatformInit from '@soundworks/plugin-platform-init/client.js';
import devicemotion from '@ircam/devicemotion';

const client = new Client(config);

client.pluginManager.register('platform-init', ClientPluginPlatformInit, {
  microphone: true,
  camera: true,
  devicemotion,
});

await client.start();

const platformInit = await client.pluginManager.get('platform-init');

const micStream = platformInit.get('microphone');
const cameraStream = platformInit.get('camera');
devicemotion.addEventListener(e => console.log(e));

Note that these additional features require a https connection.

You can also add any arbitrary logic by passing a function to the onCheck and onActivate options:

js
let onCheckCalled = false;
let onActivateCalled = false;

client.pluginManager.register('platform-init', ClientPluginPlatformInit, {
  onCheck: (plugin) => {
    onCheckCalled = true;
    return Promise.resolve();
  },
  onActivate: (plugin) => {
    onActivateCalled = true;
    return Promise.resolve();
  }
});

API ​

Table of Contents ​

ClientPluginPlatformInit ​

Extends ClientPlugin

Client-side representation of the platform init plugin.

The constructor should never be called manually. The plugin will be instantiated by soundworks when registered in the pluginManager

Available options:

  • audioContext {AudioContext} - Instance of AudioContext to be resumed aliases: ['webaudio', 'audio-context', 'audioContext']
  • devicemotion {DeviceMotion} - @ircam/devicemotion module. aliases: ['devicemotion', 'device-motion']
  • micro {Boolean} - create a microphone stream with all feature (i.e. echoCancellation, noiseReduction, autoGainControl) set to false.
    • aliases: ['mic', 'micro']
    • todo: implement deviceId
  • video {Boolean} - create a camera stream
    • todo: implement deviceId
  • onCheck {Function} - function executed when the plugin is started to check for example if the feature is available. The provided function should return a Promise.
  • onActive {Function} - function executed on the user gesture to init a feature. The provided function should return a Promise.

Examples ​

javascript
client.pluginManager.register('platform-init', platformInitPlugin, { audioContext });

onUserGesture ​

Method to be called by the application on the first user gesture, i.e. a 'click' event (cf. https://developers.google.com/web/updates/2017/09/autoplay-policy-changes)

Calling this method several times will result in a no-op after the first call.

By default, this method is automatically called by the launcher. Therefore, in most cases, you should not have to call it manually.

Parameters ​

  • event

Examples ​

javascript
myView.addEventListener('click', (e) => platformPlugin.onUserGesture(e));

get ​

Returns the payload associated to a given feature.

Parameters ​

  • featureId String Id of the feature as given during plugin registration

ServerPluginPlatformInit ​

Extends ServerPlugin

Server-side representation of the platform init plugin.

Credits ​

https://soundworks.dev/credits.html

License ​

BSD-3-Clause