{"id":13588497,"url":"https://github.com/obs-websocket-community-projects/obs-websocket-js","last_synced_at":"2025-04-08T06:32:08.221Z","repository":{"id":38327610,"uuid":"74250207","full_name":"obs-websocket-community-projects/obs-websocket-js","owner":"obs-websocket-community-projects","description":"Consumes https://github.com/obsproject/obs-websocket","archived":false,"fork":false,"pushed_at":"2024-02-25T23:17:46.000Z","size":3892,"stargazers_count":648,"open_issues_count":45,"forks_count":94,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-05-23T05:09:45.580Z","etag":null,"topics":["javascript","nodejs","obs","obs-studio","obs-websocket","websocket-client"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/obs-websocket-community-projects.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-20T03:20:13.000Z","updated_at":"2024-08-11T18:20:53.192Z","dependencies_parsed_at":"2024-06-18T12:39:02.796Z","dependency_job_id":"be4bc201-32be-492e-9e4b-1ddd7d2bbc60","html_url":"https://github.com/obs-websocket-community-projects/obs-websocket-js","commit_stats":{"total_commits":251,"total_committers":22,"mean_commits":"11.409090909090908","dds":0.6055776892430279,"last_synced_commit":"7c9c934ecb48267584977236d9e147ed3dff5fa0"},"previous_names":["haganbmj/obs-websocket-js"],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obs-websocket-community-projects%2Fobs-websocket-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obs-websocket-community-projects%2Fobs-websocket-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obs-websocket-community-projects%2Fobs-websocket-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obs-websocket-community-projects%2Fobs-websocket-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/obs-websocket-community-projects","download_url":"https://codeload.github.com/obs-websocket-community-projects/obs-websocket-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244624746,"owners_count":20483390,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","nodejs","obs","obs-studio","obs-websocket","websocket-client"],"created_at":"2024-08-01T15:06:45.013Z","updated_at":"2025-04-08T06:32:08.202Z","avatar_url":"https://github.com/obs-websocket-community-projects.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# obs-websocket-js\n\n\u003cp align=\"center\"\u003e\u003ci\u003e\nobs-websocket-js allows Javascript-based connections to the Open Broadcaster Software plugin \u003ca href=\"https://github.com/obsproject/obs-websocket\"\u003eobs-websocket\u003c/a\u003e.\n\u003c/i\u003e\n  \u003cbr\u003e\n  Created by \u003ca href=\"https://github.com/haganbmj\"\u003eBrendan Hagan\u003c/a\u003e\n  \u003cbr\u003e\n  Maintained by \u003ca href=\"https://github.com/obs-websocket-community-projects\"\u003eOBS Websocket Community\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/obs-websocket-community-projects/obs-websocket-js/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/checks-status/obs-websocket-community-projects/obs-websocket-js/master\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/obs-websocket-js\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/obs-websocket-js.svg?style=flat\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/obs-websocket-js\"\u003e\u003cimg src=\"https://img.shields.io/npm/dt/obs-websocket-js.svg\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/npm/l/obs-websocket-js.svg\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cb\u003e\n  \u003ca href=\"https://github.com/obs-websocket-community-projects/obs-websocket-js/releases\"\u003eDownload\u003c/a\u003e |\n  \u003ca href=\"https://github.com/obs-websocket-community-projects/obs-websocket-js/tree/master/samples\"\u003eSamples\u003c/a\u003e |\n  \u003ca href=\"https://github.com/obs-websocket-community-projects/obs-websocket-js/releases\"\u003eChangelog\u003c/a\u003e\n\u003c/b\u003e\u003c/p\u003e\n\n# Version Warning!\n\n\u003e You are currently reading the documentation for v5. [For v4 documentation look here](https://github.com/obs-websocket-community-projects/obs-websocket-js/tree/v4)\n\n---\n\n## Installation\n\n### Via package manager\n\nUsing a package manager like npm / yarn is the recommended installation method when you're planning to use obs-websocket-js in node.js, building a web app that you'll bundle with webpack or rollup, or for using type definitions.\n\n```sh\nnpm install obs-websocket-js\nyarn add obs-websocket-js\n```\n\n### Standalone file / CDN build\n\nStandalone js file is available from jsdeliver \u0026 unpkg CDN's:\n\n```\nhttps://cdn.jsdelivr.net/npm/obs-websocket-js\nhttps://unpkg.com/obs-websocket-js\n```\n\n## Usage\n\n### Builds\n\ndist folder of the npm package includes 2 different builds to support [different message encodings supported by obs-websocket](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#connection-steps).\n\n| Connection Encoding | JSON | Msgpack |\n|---|---|---|\nUsed by default | By web bundles | By node.js\nManually opting into | `import OBSWebSocket from 'obs-web-socket/json'` | `import OBSWebSocket from 'obs-web-socket/msgpack'`\nBenefits | Easier debugging, smaller bundle | Connection uses less bandwidth\nDownsides | Connection uses more bandwidth | Harder to debug, bigger bundle size\n\nIn addition each version has both modern and legacy builds. Modern bundlers will opt into modern build which uses [most modern JS features while also being supported by most modern browsers](https://github.com/developit/microbundle#-modern-mode-). If you need support for older browsers, make sure to configure your bundler to also transpile dependencies with babel or other such .\n\n### Creating an OBS Websocket client\n\n`OBSWebSocket` is available as a named export in ES Modules:\n\n```ts\nimport { OBSWebSocket } from 'obs-websocket-js';\n\nconst obs = new OBSWebSocket();\n```\n\nWhen using commonjs `require()` it is available under the `OBSWebSocket` object key:\n\n```ts\nconst { OBSWebSocket } = require('obs-websocket-js');\nconst OBSWebSocket = require('obs-websocket-js').OBSWebSocket;\n\nconst obs = new OBSWebSocket();\n```\n\n### Connecting\n\n```ts\nconnect(url = 'ws://127.0.0.1:4455', password?: string, identificationParams = {}): Promise\n```\n\nTo connect to obs-websocket server use the `connect` method.\n\nParameter | Description\n---|---\n`url`\u003cbr /\u003e`string (optional)` | Websocket URL to connect to, including protocol. (For example when connecting via a proxy that supports https use `wss://127.0.0.1:4455`)\n`password`\u003cbr /\u003e`string (optional)` | Password required to authenticate with obs-websocket server\n`identificationParams`\u003cbr /\u003e`object (optional)` | Object with parameters to send with the [Identify message](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#identify-opcode-1)\u003cbr /\u003eUse this to include RPC version to guarantee compatibility with server\n\nReturns promise that resolves to data from [Hello](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#hello-opcode-0) and [Identified](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#identified-opcode-2) messages or rejects with connection error (either matching obs-websocket [WebSocketCloseCode](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#websocketclosecode) or with code -1 when non-compatible server is detected).\n\n```ts\nimport OBSWebSocket, {EventSubscription} from 'obs-websocket-js';\nconst obs = new OBSWebSocket();\n\n// connect to obs-websocket running on localhost with same port\nawait obs.connect();\n\n// Connect to obs-ws running on 192.168.0.4\nawait obs.connect('ws://192.168.0.4:4455');\n\n// Connect to localhost with password\nawait obs.connect('ws://127.0.0.1:4455', 'super-sekret');\n\n// Connect expecting RPC version 1\nawait obs.connect('ws://127.0.0.1:4455', undefined, {rpcVersion: 1});\n\n// Connect with request for high-volume event\nawait obs.connect('ws://127.0.0.1:4455', undefined, {\n  eventSubscriptions: EventSubscription.All | EventSubscription.InputVolumeMeters,\n  rpcVersion: 1\n});\n\n// A complete example\ntry {\n  const {\n    obsWebSocketVersion,\n    negotiatedRpcVersion\n  } = await obs.connect('ws://192.168.0.4:4455', 'password', {\n    rpcVersion: 1\n  });\n  console.log(`Connected to server ${obsWebSocketVersion} (using RPC ${negotiatedRpcVersion})`)\n} catch (error) {\n  console.error('Failed to connect', error.code, error.message);\n}\n```\n\n### Reidentify\n\n```ts\nreidentify(data: {}): Promise\n```\n\nTo update session parameters set by initial identification use `reidentify` method.\n\nParameter | Description\n---|---\n`data`\u003cbr /\u003e`object` | Object with parameters to send with the [Reidentify message](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#reidentify-opcode-3)\n\nReturns promise that resolves when the server has acknowledged the request\n\n```ts\nawait obs.reidentify({\n  eventSubscriptions: EventSubscription.General | EventSubscription.InputShowStateChanged\n});\n```\n\n### Disconnecting\n\n```ts\ndisconnect(): Promise\n```\n\nDisconnects from obs-websocket server. This keeps any registered event listeners.\n\nReturns promise that resolves when connection is closed\n\n```ts\nawait obs.disconnect();\n```\n\n### Sending Requests\n\n```ts\ncall(requestType: string, requestData?: object): Promise\n```\n\nSending requests to obs-websocket is done via `call` method.\n\nParameter | Description\n---|---\n`requestType`\u003cbr /\u003e`string` | Request type ([see obs-websocket documentation](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#requests))\n`requestData`\u003cbr /\u003e`object (optional)` | Request data ([see obs-websocket documentation for the request](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#requests))\n\nReturns promise that resolves with response data (if applicable) or rejects with error from obs-websocket.\n\n```ts\n// Request without data\nconst {currentProgramSceneName} = await obs.call('GetCurrentProgramScene');\n\n// Request with data\nawait obs.call('SetCurrentProgramScene', {sceneName: 'Gameplay'});\n\n// Both together now\nconst {inputMuted} = obs.call('ToggleInputMute', {inputName: 'Camera'});\n```\n\n### Sending Batch Requests\n\n```ts\ncallBatch(requests: RequestBatchRequest[], options?: RequestBatchOptions): Promise\u003cResponseMessage[]\u003e\n```\n\nMultiple requests can be batched together into a single message sent to obs-websocket using the `callBatch` method. The full request list is sent over the socket at once, obs-websocket executes the requests based on the `options` provided, then returns the full list of results once all have finished.\n\nParameter | Description\n---|---\n`requests`\u003cbr /\u003e`RequestBatchRequest[]` | The list of requests to be sent ([see obs-websocket documentation](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#requests)). Each request follows the same structure as individual requests sent to [`call`](#sending-requests).\n`options`\u003cbr /\u003e`RequestBatchOptions (optional)` | Options controlling how obs-websocket will execute the request list.\n`options.executionType`\u003cbr /\u003e`RequestBatchExecutionType (optional)` | The mode of execution obs-websocket will run the batch in\n`options.haltOnFailure`\u003cbr /\u003e`boolean (optional)` | Whether obs-websocket should stop executing the batch if one request fails\n\nReturns promise that resolve with a list of `results`, one for each request that was executed.\n\n```ts\n// Execute a transition sequence to a different scene with a specific transition.\nconst results = await obs.callBatch([\n  {\n    requestType: 'GetVersion',\n  },\n  {\n    requestType: 'SetCurrentPreviewScene',\n    requestData: {sceneName: 'Scene 5'},\n  },\n  {\n    requestType: 'SetCurrentSceneTransition',\n    requestData: {transitionName: 'Fade'},\n  },\n  {\n    requestType: 'Sleep',\n    requestData: {sleepMillis: 100},\n  },\n  {\n    requestType: 'TriggerStudioModeTransition',\n  }\n])\n```\n\nCurrently, obs-websocket-js is not able to infer the types of ResponseData to any specific request's response. To use the data safely, cast it to the appropriate type for the request that was sent.\n\n```ts\n(results[0].responseData as OBSResponseTypes['GetVersion']).obsVersion //=\u003e 28.0.0\n```\n\n### Receiving Events\n\n```ts\non(event: string, handler: Function)\nonce(event: string, handler: Function)\noff(event: string, handler: Function)\naddListener(event: string, handler: Function)\nremoveListener(event: string, handler: Function)\n```\n\nTo listen for events emitted by obs-websocket use the event emitter API methods.\n\nParameter | Description\n---|---\n`event`\u003cbr /\u003e`string` | Event type ([see obs-websocket documentation](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#events))\n`handler`\u003cbr /\u003e`Function` | Function that is called when event is sent by the server. Receives data as the first argument ([see obs-websocket documentation for the event](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#events))\n\n\n```ts\nfunction onCurrentSceneChanged(event) {\n  console.log('Current scene changed to', event.sceneName)\n}\n\nobs.on('CurrentSceneChanged', onCurrentSceneChanged);\n\nobs.once('ExitStarted', () =\u003e {\n  console.log('OBS started shutdown');\n\n  // Just for example, not necessary should you want to reuse this instance by re-connect()\n  obs.off('CurrentSceneChanged', onCurrentSceneChanged);\n});\n```\n\n\u003e Internally [eventemitter3](https://github.com/primus/eventemitter3) is used and it's documentation can be referenced for advanced usage\n\n#### Internal events\n\nIn addition to obs-websocket events, following events are emitted by obs-websocket-js client itself:\n\n* `ConnectionOpened` - When connection has opened (no data)\n* `ConnectionClosed` - When connection closed (called with `OBSWebSocketError` object)\n* `ConnectionError` - When connection closed due to an error (generally above is more useful)\n* `Hello` - When server has sent Hello message (called with [Hello data](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#hello-opcode-0))\n* `Identified` - When client has connected and identified (called with [Identified](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#identified-opcode-2) data)\n\n## Typescript Support\n\nThis library is written in typescript and typescript definitions are published with the package. Each package is released with typescript definitions matching the currently released version of obs-websocket. This data can be reused from `OBSEventTypes`, `OBSRequestTypes` and `OBSResponseTypes` named exports, though in most cases function parameters will enforce the typings correctly.\n\n```ts\nimport OBSWebSocket, {OBSEventTypes, OBSRequestTypes, OBSResponseTypes} from 'obs-websocket-js';\n\nfunction onProfileChanged(event: OBSEventTypes['CurrentProfileChanged']) {\n  event.profileName\n}\n\nobs.on('CurrentProfileChanged', onProfileChanged);\nobs.on('VendorEvent', ({vendorName, eventType, eventData}) =\u003e {\n  if (vendorName !== 'fancy-plugin') {\n    return;\n  }\n});\n\nconst req: OBSRequestTypes['SetSceneName'] = {\n  sceneName: 'old-and-busted',\n  newSceneName: 'new-hotness'\n};\nobs.call('SetSceneName', req);\nobs.call('SetInputMute', {\n  inputName: 'loud noises',\n  inputMuted: true\n});\n```\n\n## Debugging\n\nTo enable debug logging, set the `DEBUG` environment variable:\n\n```sh\n# Enables debug logging for all modules of osb-websocket-js\nDEBUG=obs-websocket-js:*\n\n# on Windows\nset DEBUG=obs-websocket-js:*\n```\n\nIf you have multiple libraries or application which use the `DEBUG` environment variable, they can be joined with commas:\n\n```sh\nDEBUG=foo,bar:*,obs-websocket-js:*\n\n# on Windows\nset DEBUG=foo,bar:*,obs-websocket-js:*\n```\n\nBrowser debugging uses `localStorage`\n\n```js\nlocalStorage.debug = 'obs-websocket-js:*';\n\nlocalStorage.debug = 'foo,bar:*,obs-websocket-js:*';\n```\n\nFor more information, see the [`debug`](https://github.com/visionmedia/debug) package documentation.\n\n## Upgrading\n\n* [Upgrading from 4.x to 5.x](https://github.com/obs-websocket-community-projects/obs-websocket-js/releases/tag/v5.0.0)\n* [Upgrading from 2.x to 3.x](https://github.com/obs-websocket-community-projects/obs-websocket-js/tree/v4#upgrading-from-2x-to-3x)\n* [Upgrading from 1.x to 2.x](https://github.com/obs-websocket-community-projects/obs-websocket-js/tree/v4#upgrading-from-1x-to-2x)\n\n## Projects Using **obs-websocket-js**\n\n[Share your project in github discussions!](https://github.com/obs-websocket-community-projects/obs-websocket-js/discussions/categories/show-and-tell)\n\n## [Contributing Guidelines](.github/CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobs-websocket-community-projects%2Fobs-websocket-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobs-websocket-community-projects%2Fobs-websocket-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobs-websocket-community-projects%2Fobs-websocket-js/lists"}