soundworks | plugin platform init
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
- Usage
- Available features
- API
- ClientPluginPlatformInit
- ServerPluginPlatformInit
- Credits
- License
Installation
npm install @soundworks/plugin-platform-init --save
Usage
Server
// 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
// 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.
npm install --save @ircam/devicemotion
// 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:
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
- todo: implement
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
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
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