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 informations on the soundworks wizard.

npm install --save @soundworks/helpers

API

Table of Contents

• browserLauncher
  • Examples
  • execute
  • register
  • language
  • language
  • setLanguageData
  • getLanguageData
• nodeLauncher
  • Examples
  • execute
  • register

browserLauncher

Launcher for clients running in browser runtime.

Examples

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

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 });

language

Return the locale strings

Type: object

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

Parameters

• lang

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)

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 filr. (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)

Examples

launcher.register(client);

Credits

https://soundworks.dev/credits.html

License

BSD-3-Clause