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
  • Examples
  • onUserGesture
  • get
• ServerPluginPlatformInit

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

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

License

BSD-3-Clause