Client

client. Client

The Client class is the main entry point for the client-side of a soundworks application.

A Client instance allows to access soundworks components such as client.StateManager, client.PluginManager,client.Socket or client.ContextManager. Its is also responsible for handling the initialization lifecycles of the different soundworks components.

import { Client } from '@soundworks/core/client.js';
// create a new soundworks `Client` instance
const client = new Client({ role: 'player' });
// init and start the client
await client.start();

Constructor

new Client(config)

Source:
Parameters:
Name Type Description
config client.BrowserClientConfig | client.NodeClientConfig

Configuration of the soundworks client.
Throws:

Will throw if the given config object is invalid.

Members

config :client.BrowserClientConfig|client.NodeClientConfig

Description:

  • Configuration object.

Source:

Configuration object.

Type:

contextManager :client.ContextManager

Description:

  • Instance of the client.ContextManager class.

    The context manager can be safely used after client.init() has been fulfilled.

Source:
See:

Instance of the client.ContextManager class.

The context manager can be safely used after client.init() has been fulfilled.

Type:

id :number

Description:

  • Session id of the client (incremeted positive number), generated and retrieved by the server during client.init. The counter is reset when the server restarts.

Source:

Session id of the client (incremeted positive number), generated and retrieved by the server during client.init. The counter is reset when the server restarts.

Type:
  • number

pluginManager :client.PluginManager

Description:

  • Instance of the client.PluginManager class.

    The context manager can be safely used after client.init() has been fulfilled.

Source:
See:

Instance of the client.PluginManager class.

The context manager can be safely used after client.init() has been fulfilled.

Type:

role :string

Description:

  • Role of the client in the application.

Source:

Role of the client in the application.

Type:
  • string

socket :client.Socket

Description:

  • Instance of the client.Socket class that handle websockets communications with the server.

Source:
See:

Instance of the client.Socket class that handle websockets communications with the server.

Type:

stateManager :client.StateManager

Description:

  • Instance of the client.StateManager class.

    The context manager can be safely used after client.init() has been fulfilled.

Source:
See:

Instance of the client.StateManager class.

The context manager can be safely used after client.init() has been fulfilled.

Type:

status :string

Description:

  • Status of the client, 'idle', 'inited', 'started' or 'errored'.

Source:

Status of the client, 'idle', 'inited', 'started' or 'errored'.

Type:
  • string

target :string

Description:

  • Runtime platform on which the client is executed, i.e. 'browser' or 'node'.

Source:

Runtime platform on which the client is executed, i.e. 'browser' or 'node'.

Type:
  • string

uuid :string

Description:

  • Unique session uuid of the client (uuidv4), generated and retrieved by the server during client.Client#init.

Source:

Unique session uuid of the client (uuidv4), generated and retrieved by the server during client.Client#init.

Type:
  • string

Methods

(async) getAuditState() → {Promise.<client.SharedState>}

Description:

  • Attach and retrieve the global audit state of the application.

    The audit state is a client.SharedState instance that keeps track of global informations about the application such as, the number of connected clients, network latency estimation, etc. It is usefull for controller client roles to give the user an overview about the state of the application.

    The audit state is lazily attached to the client only if this method is called.

Source:
See:
Example
const auditState = await client.getAuditState();
auditState.onUpdate(() => console.log(auditState.getValues()), true);
Throws:

Will throw if called before client.init()

Returns:
Type
Promise.<client.SharedState>

(async) init()

Description:

  • The init method is part of the initialization lifecycle of the soundworks client. Most of the time, the init method will be implicitly called by the client.Client#start method.

    In some situations you might want to call this method manually, in such cases the method should be called before the client.Client#start method.

    What it does:

    • connect the sockets to be server
    • perform the handshake with soundworks server (retrieve id, etc.)
    • launch the state manager
    • initialize all registered plugin

    After await client.init() is fulfilled, the client.Client#stateManager, the client.Client#pluginManager and the client.Client#socket can be safely used.

Source:
Example
import { Client } from '@soundworks/core/client.js'

const client = new Client(config);
// optionnal explicit call of `init` before `start`
await client.init();
await client.start();

onStatusChange(callback) → {function}

Description:

  • Listen for the status change ('inited', 'started', 'stopped') of the client.

Source:
Parameters:
Name Type Description
callback function

Listener to the status change.
Returns:

Delete the listener.

Type
function

(async) start()

Description:

  • The start method is part of the initialization lifecycle of the soundworks client. The start method will implicitly call the client.Client#init method if it has not been called manually.

    What it does:

    • implicitly call client.Client#init if not done manually
    • start all created contexts. For that to happen, you will have to call client.init manually and instantiate the contexts between client.init() and client.start()
Source:
Example
import { Client } from '@soundworks/core/client.js'

const client = new Client(config);
await client.start();

(async) stop()

Description:

  • Stops all started contexts, plugins and terminates the socket connections.

    In most situations, you might not need to call this method. However, it can be usefull for unit testing or similar situations where you want to create and delete several clients in the same process.

Source:
Example
import { Client } from '@soundworks/core/client.js'

const client = new Client(config);
await client.start();

await new Promise(resolve => setTimeout(resolve, 1000));
await client.stop();