soundworks

Appearance

soundworks | helpers ​

Set of common helpers for soundworks applications.

Manual Installation ​

Note that the @soundworks/helpers package is automatically installed when you create an application using the @soundworks/create wizard, so most of the time you should not care to install this package manually.

See https://soundworks.dev/guides/getting-started.html for more information on the soundworks wizard.

npm install --save @soundworks/helpers

API ​

Table of Contents ​

browserLauncher ​

Launcher for clients running in browser runtime.

Examples ​

javascript
import launcher from '@soundworks/helpers/browser.js'

language ​

Set the language to be used in the initialization screens.

By default, picks language from the browser and fallback to english if not supported. For now, available languages are 'fr' and 'en'.

Type: string

execute ​

Allow to launch multiple clients at once in the same browser window by adding ?emulate=numberOfClient at the end of the url e.g. http://127.0.0.1:8000?emulate=10 to run 10 clients in parallel

Parameters ​

  • bootstrap Function Bootstrap function to execute.

  • options object Configuration object. (optional, default {})

    • options.numClients number Number of parallel clients. (optional, default 1)
    • options.width string If numClient > 1, width of the container. (optional, default '20%')
    • options.height string If numClient > 1, height of the container. (optional, default '500px')

Examples ​

javascript
launcher.execute(main, {
  numClients: parseInt(new URLSearchParams(window.location.search).get('emulate')) || 1,
});

register ​

Register the client in the launcher.

The launcher will do a bunch of stuff for you:

  • Display default initialization screens. If you want to change the provided initialization screens, you can import all the helpers directly in your application by doing npx soundworks --eject-helpers. You can also customize some global styles variables (background-color, text color etc.) in src/clients/components/css/app.scss. You can also change the default language of the initialization screen by setting, the launcher.language property, e.g.: launcher.language = 'fr'
  • By default the launcher automatically reloads the client when the socket closes or when the page is hidden. Such behavior can be quite important in performance situation where you don't want some phone getting stuck making noise without having any way left to stop it... Also be aware that a page in a background tab will have all its timers (setTimeout, etc.) put in very low priority, messing any scheduled events.

Parameters ​

  • client Client The soundworks client.

  • options object Configuration object. (optional, default {})

    • options.initScreensContainer HTMLElement The HTML container for the initialization screens. (optional, default null)
    • options.reloadOnVisibilityChange boolean Define if the client should reload on visibility change. (optional, default true)
    • options.reloadOnSocketError boolean Define if the client should reload on socket error and disconnection. (optional, default true)

Examples ​

javascript
launcher.register(client, { initScreensContainer: $container });

setLanguageData ​

Set the text to be used for a given language. Allows to override an existing language as well as define a new one.

Parameters ​

  • lang string Key corresponding to the language (e.g. 'fr', 'en', 'es')
  • data object Key/value pairs defining the text strings to be used.

getLanguageData ​

Retrieve the data for a given language.

Parameters ​

  • lang string Key corresponding to the language (e.g. 'fr', 'en', 'es') (optional, default null)

browserLoadConfig ​

Returns the browser client configuration as retrieved by the server

Returns ClientConfig

nodeLauncher ​

Launcher for clients running in Node.js runtime.

Examples ​

javascript
import launcher from '@soundworks/helpers/node.js'

execute ​

The "execute" function allows to fork multiple clients in the same terminal window by defining the EMULATE env process variable e.g. EMULATE=10 npm run watch-process thing to run 10 clients side-by-side

Parameters ​

  • bootstrap function Bootstrap function to execute.

  • options object Configuration object. (optional, default {})

    • options.numClients number Number of parallel clients. (optional, default 1)
    • options.moduleURL string Module url of the calling file, used as current working directory of the subprocesses. (optional, default null)

Examples ​

javascript
launcher.execute(bootstrap, {
  numClients: process.env.EMULATE ? parseInt(process.env.EMULATE) : 1,
  moduleURL: import.meta.url,
});

register ​

Register the soundworks client into the launcher

Automatically restarts the process when the socket closes or when an uncaught error occurs in the program.

Parameters ​

  • client Client The soundworks client.

  • options object Configuration object. (optional, default {})

    • options.restartOnError boolean Define if the client should restart on uncaught errors. (optional, default false)
    • options.restartOnSocketClose boolean Define if the client should restart on socket disconnection. (optional, default true)
    • options.exitParentProcess boolean If true, exit the parent "launcher" process on both error and socket close, may be useful in production settings if the application is e.g. managed by a daemon at the system level. (optional, default false)

Examples ​

javascript
launcher.register(client);

nodeLoadConfig ​

Load configuration from files located in /config directory

Parameters ​

  • ENV String Name of the environment corresponding to the config/env-${name}.{yaml|json} file. (optional, default 'default')
  • callerURL String Module url of the calling file, used to automatically retrieve the role of node clients. (optional, default null)

Returns (ClientConfig | ServerConfig)

configureHttpRouter ​

According to the clients definitions provided in config.app.clients, the server will automatically create a dedicated route for each role declaring a browser runtime. For example, given the config object of the example above that defines two different client roles for browser (i.e. player and controller):

config.app.clients = {
  player: { runtime: 'browser', default: true },
  controller: { runtime: 'browser' },
}

The server will listen to the following URLs:

  • http://127.0.0.1:8000/ for the player role, which is defined as the default client.
  • http://127.0.0.1:8000/controller for the controller role.

Parameters ​

  • server Server The soundworks server instance

Examples ​

javascript
import { Server } from '@soundworks/core/server.js';
import { configureHttpRouter, loadConfig } from '@soundworks/helpers/server.js';

const server = new Server(loadConfig());
configureHttpRouter(server);

Credits ​

https://soundworks.dev/credits.html

License ​

BSD-3-Clause