obs-websocket-js

The library is written in TypeScript and includes published type definitions that match the current version of obs-websocket. You can use the following named exports to enforce strict typing for events, requests, and responses:

• OBSEventTypes: For typing event payloads.
• OBSRequestTypes: For typing request parameters.
• OBSResponseTypes: For typing response payloads.

While function parameters often enforce typings automatically, these exports are useful for explicit type annotations in event handlers and request objects.

import OBSWebSocket, {OBSEventTypes, OBSRequestTypes, OBSResponseTypes} from 'obs-websocket-js';

function onProfileChanged(event: OBSEventTypes['CurrentProfileChanged']) {
  event.profileName
}

obs.on('CurrentProfileChanged', onProfileChanged);

const req: OBSRequestTypes['SetSceneName'] = {
  sceneName: 'old-and-busted',
  newSceneName: 'new-hotness'
};
obs.call('SetSceneName', req);

Use the standard event emitter API to listen for events emitted by the OBS Websocket server.

Methods:

• on(event, handler): Register a listener.
• once(event, handler): Register a listener that triggers once.
• off(event, handler): Remove a listener.
• addListener(event, handler): Alias for on.
• removeListener(event, handler): Alias for off.

Example:

function onCurrentSceneChanged(event) {
  console.log('Current scene changed to', event.sceneName);
}

obs.on('CurrentSceneChanged', onCurrentSceneChanged);

// Using once
obs.once('ExitStarted', () => {
  console.log('OBS started shutdown');
});

Internal Client Events

The client also emits these internal events:

• ConnectionOpened: Connection opened (no data).
• ConnectionClosed: Connection closed (returns OBSWebSocketError).
• ConnectionError: Connection closed due to an error.
• Hello: Server sent Hello message (returns Hello data).
• Identified: Client connected and identified (returns Identified data).

obs.on('CurrentSceneChanged', (event) => {
  console.log('Current scene changed to', event.sceneName);
});

Execute multiple requests in a single message to improve efficiency. The server executes the requests based on provided options and returns a list of results once all are finished.

Signature: callBatch(requests: RequestBatchRequest[], options?: RequestBatchOptions): Promise<ResponseMessage[]>

Parameters:

• requests: An array of request objects (same structure as call).
• options (optional):
  • executionType: Mode of execution.
  • haltOnFailure (boolean): If true, stops the batch if one request fails.

Note on Types: obs-websocket-js does not automatically infer response types for batch results. You must cast the responseData to the appropriate type manually.

Example:

const results = await obs.callBatch([
  { requestType: 'GetVersion' },
  { requestType: 'SetCurrentPreviewScene', requestData: { sceneName: 'Scene 5' } }
]);

// Manual type casting for safety
const version = (results[0].responseData as OBSResponseTypes['GetVersion']).obsVersion;

Use the connect method to establish a connection. It returns a Promise that resolves with data from the Hello and Identified messages, or rejects with a connection error.

Signature: connect(url?: string, password?: string, identificationParams?: object): Promise

Parameters:

• url (string, optional): The Websocket URL (e.g., ws://127.0.0.1:4455 or wss://... for secure connections).
• password (string, optional): Authentication password.
• identificationParams (object, optional): Parameters for the Identify message, such as rpcVersion to ensure compatibility.

Example:

try {
  const { obsWebSocketVersion, negotiatedRpcVersion } = await obs.connect('ws://192.168.0.4:4455', 'password', {
    rpcVersion: 1
  });
  console.log(`Connected to server ${obsWebSocketVersion} (using RPC ${negotiatedRpcVersion})`);
} catch (error) {
  console.error('Failed to connect', error.code, error.message);
}

import OBSWebSocket, {EventSubscription} from 'obs-websocket-js';
const obs = new OBSWebSocket();

await obs.connect('ws://127.0.0.1:4455', 'super-sekret', { rpcVersion: 1 });