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
  • Server
  • Client
• Available features
• API
  • Classes
  • PluginPlatformInitClient
  • PluginPlatformInitServer
• Credits
• License

Installation

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

Usage

Server

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

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

Client

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

const audioContext = new AudioContext();

const client = new Client(config);
// pass the audio context to the plugin will automatically generate a landing page 
// for resuming the audio context
client.pluginManager.register('platform-init', platformInitPlugin, { 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 throught the @ircam/devicemotion package.

npm install --save @ircam/devicemotion

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

const client = new Client(config);

client.pluginManager.register('platform-init', platformInitPlugin, { 
  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 arbitraty logic by passing a function to the onCheck and onActivate options:

let onCheckCalled = false;
let onActivateCalled = false;

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

API

Classes

PluginPlatformInitClient

Client-side representation of the soundworks' platform init plugin.

Kind: global class

• PluginPlatformInitClient
  • new PluginPlatformInitClient()
  • .onUserGesture()
  • .get(featureId)

new PluginPlatformInitClient()

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

Available options:

• audioContext {AudioContext} - instance audio context 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.

Example

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

pluginPlatformInitClient.onUserGesture()

Method to be executed by the application on the first user gesture. Calling this method several times will result in a no-op after the first call.

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

Kind: instance method of PluginPlatformInitClient
Example

myView.addEventListener((e) => {
  platformPlugin.onUserGesture(e);
});

pluginPlatformInitClient.get(featureId)

Returns the poayload associated to a given feature.

Kind: instance method of PluginPlatformInitClient

| Param | Type | Description | | --- | --- | --- | | featureId | String | Id of the feature as given when the plugin was registered |

PluginPlatformInitServer

Client-side representation of the soundworks' platform init plugin.

Kind: global class

Credits

https://soundworks.dev/credits.html

License

BSD-3-Clause