Set of common helpers for soundworks
applications.
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
Launcher for clients running in browser runtime.
import launcher from '@soundworks/helpers/launcher.js'
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
-
bootstrap
Function Bootstrap function to execute. -
options
object Configuration object. (optional, default{}
)
launcher.execute(main, {
numClients: parseInt(new URLSearchParams(window.location.search).get('emulate')) || 1,
});
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.) insrc/clients/components/css/app.scss
. You can also change the default language of the intialization screen by setting, thelauncher.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.
-
client
Function The soundworks client. -
options
object Configuration object. (optional, default{}
)-
options.initScreensContainer
HTMLElement The HTML container for the initialization screens. (optional, defaultnull
) -
options.reloadOnVisibilityChange
boolean Define if the client should reload on visibility change. (optional, defaulttrue
) -
options.reloadOnSocketError
boolean Define if the client should reload on socket error and disconnection. (optional, defaulttrue
)
-
launcher.register(client, { initScreensContainer: $container });
Return the locale strings
Type: object
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
-
lang
Set the text to be used for a given language. Allows to override an existing language as well as define a new one.
-
lang
string Key correspondig to the language (e.g. 'fr', 'en', 'es') -
data
object Key/value pairs defining the text strings to be used.
Retrieve the data for a given language.
-
lang
string Key correspondig to the language (e.g. 'fr', 'en', 'es') (optional, defaultnull
)
Launcher for clients running in Node.js runtime.
import launcher from '@soundworks/helpers/launcher.js'
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
-
bootstrap
Function Bootstrap function to execute. -
options
object Configuration object. (optional, default{}
)
launcher.execute(bootstrap, {
numClients: process.env.EMULATE ? parseInt(process.env.EMULATE) : 1,
moduleURL: import.meta.url,
});
Register the soundworks client into the launcher
Automatically restarts the process when the socket closes or when an uncaught error occurs in the program.
launcher.register(client);