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
  • Examples
  • language
  • execute
  • register
  • setLanguageData
  • getLanguageData
• browserLoadConfig
• nodeLauncher
  • Examples
  • execute
  • register
• nodeLoadConfig
  • Parameters

browserLauncher

Launcher for clients running in browser runtime.

Examples

import launcher from '@soundworks/helpers/launcher.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 brwoser 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

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 customise some global syles variables (background-color, text color etc.) in src/clients/components/css/app.scss. You can also change the default language of the intialization 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 Function 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

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 correspondig 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 correspondig 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

import launcher from '@soundworks/helpers/launcher.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 worink directory of the subprocesses. (optional, default null)

Examples

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 Function 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 usefull in production settings if the application is e.g. managed by a daemon at the system level. (optional, default false)

Examples

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)

Credits

https://soundworks.dev/credits.html

License

BSD-3-Clause