soundworks | plugin position

soundworks plugin for locating people in an area.

When registered the soundworks launcher will automatically provide an interface so that people can give give their approximate position on a map or area.

Table of Contents

• Installation
• Usage
  • Server
  • Client
• API
  • Classes
  • PluginPositionClient
  • PluginPositionServer
• Credits
• License

Installation

npm install @soundworks/plugin-position --save

Usage

Server

// index.js
import { Server } from '@soundworks/core/server.js';
import pluginPosition from '@soundworks/plugin-position/server.js';

const server = new Server();
server.pluginManager.register('position', pluginPosition, {
  // these values define the coordinates system of the area, they have
  // no special meaning and could be in any unit you find useful for
  // your application, defaults to [0, 1]
  xRange: [0, 2],
  yRange: [-1, 1],
  // define a background image that will be displayed by the launcher view
  backgroundImage: 'public/path/to/map.png'
}, []);

await server.start();

Client

// index.js
import { Client } from '@soundworks/core/client.js';
import pluginPosition from '@soundworks/plugin-position/client.js';

const client = new Client();
client.pluginManager.register('position', pluginPosition, {}, []);

await client.start();

const position = await client.pluginManager.get('position');
const clientPosition = position.getPosition();

API

Classes

PluginPositionClient

Client-side representation of the soundworks' position plugin.

Kind: global class

• PluginPositionClient
  • new PluginPositionClient()
  • .setPosition(x, y)
  • .getPosition() ⇒ Object
  • .setNormalizedPosition(x, y)
  • .getNormalizedPosition() ⇒ Object

new PluginPositionClient()

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

Available options:

• randomize {Boolean} - Autoamtically give a random position to the client. Useful for testing

Example

client.pluginManager.register('position', positionPlugin, { randomize: true });

pluginPositionClient.setPosition(x, y)

Set the x and y position of the client in the given ranges units.

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 PluginPositionClient

| Param | Type | Description | | --- | --- | --- | | x | Number | x position in the given ranges units. | | y | Number | y position in the given ranges units. |

pluginPositionClient.getPosition() ⇒ Object

Retrieve the given position in the given ranges units.

Kind: instance method of PluginPositionClient
Returns: Object - - x / y position of the client.

pluginPositionClient.setNormalizedPosition(x, y)

Set the x and y position of the client in normalized units.

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 PluginPositionClient

| Param | Type | Description | | --- | --- | --- | | x | Number | x position in normalized units. | | y | Number | y position in normalized units. |

pluginPositionClient.getNormalizedPosition() ⇒ Object

Retrieve the given position in normalized units.

Kind: instance method of PluginPositionClient
Returns: Object - - normalized x / y position of the client.

PluginPositionServer

Server-side representation of the soundworks' position plugin.

Kind: global class

new PluginPositionServer()

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

Available options:

• xRange {Array} - Range of the area in the x axis.
• yRange {Array} - Range of the area in the y axis.
• backgroundImage {String} - Path to a background image to be displayed by the launcher view.

Example

server.pluginManager.register('position', positionPlugin, {
  xRange: [0, 2],
  yRange: [-1, 1],
  backgroundImage: 'public/path/to/map.png',
});

Credits

https://soundworks.dev/credits.html

License

BSD-3-Clause