Client

Client

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

A soundworks client can run seamlessly in a browser or in a Node.js runtime.

It provides an access to the different soundworks components such as the ClientStateManager, ClientPluginManager, ClientSocket and the ClientContextManager.

import { Client } from '@soundworks/core/client.js';
// create a `Client` instance
const client = new Client({
  role: 'player',
  env: {
    useHttps: false,
    serverAddress: 'localhost',
    port: 8000,
  },
});
// start the client
await client.start();

Constructor

new Client(config)

Source:
Parameters:
Name Type Description
config ClientConfig

Configuration of the soundworks client.
Throws:

Will throw if the given config object is invalid.

Members

config :ClientConfig

Description:

  • Configuration object.

Source:

Configuration object.

Type:

contextManager :ClientContextManager

Description:

  • Instance of the ClientContextManager class.

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

Source:
See:

Instance of the ClientContextManager 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 integer 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 integer generated and retrieved by the server during client.init. The counter is reset when the server restarts.

Type:
  • number

pluginManager :ClientPluginManager

Description:

  • Instance of the ClientPluginManager class.

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

Source:
See:

Instance of the ClientPluginManager 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 :ClientSocket

Description:

  • Instance of the client.Socket class.

Source:
See:

Instance of the client.Socket class.

Type:

stateManager :ClientStateManager

Description:

  • Instance of the ClientStateManager class.

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

Source:
See:

Instance of the ClientStateManager class.

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

Type:

status :'idle'|'inited'|'started'|'errored'

Description:

  • Status of the client.

Source:

Status of the client.

Type:
  • 'idle' | 'inited' | 'started' | 'errored'

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#init.

Source:

Unique session uuid of the client (uuidv4).

Generated and retrieved by the server during Client#init.

Type:
  • string

version :string

Description:

  • Package version.

Source:

Package version.

Type:
  • string

Methods

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

Description:

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

    The audit state is a 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.<SharedState>

(async) init()

Description:

  • The init method is part of the initialization lifecycle of the soundworks client. Most of the time, this method will be implicitly executed by the 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#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#stateManager, the Client#pluginManager and the 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:

Function that delete the listener when executed.

Type
function

(async) start()

Description:

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

    What it does:

    • implicitly call 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();