{"id":29692019,"url":"https://github.com/obs-websocket-community-projects/obs-websocket-java","last_synced_at":"2025-07-23T07:09:13.920Z","repository":{"id":43888377,"uuid":"129634747","full_name":"obs-websocket-community-projects/obs-websocket-java","owner":"obs-websocket-community-projects","description":"A java library for https://github.com/obsproject/obs-websocket","archived":false,"fork":false,"pushed_at":"2023-01-03T16:44:11.000Z","size":3787,"stargazers_count":64,"open_issues_count":7,"forks_count":27,"subscribers_count":6,"default_branch":"develop","last_synced_at":"2024-05-02T00:13:37.324Z","etag":null,"topics":["java","obs","obs-studio","websocket-client"],"latest_commit_sha":null,"homepage":"","language":"Java","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":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-15T17:37:30.000Z","updated_at":"2024-05-02T00:13:37.324Z","dependencies_parsed_at":"2023-02-01T08:01:10.518Z","dependency_job_id":null,"html_url":"https://github.com/obs-websocket-community-projects/obs-websocket-java","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/obs-websocket-community-projects/obs-websocket-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obs-websocket-community-projects%2Fobs-websocket-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obs-websocket-community-projects%2Fobs-websocket-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obs-websocket-community-projects%2Fobs-websocket-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obs-websocket-community-projects%2Fobs-websocket-java/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-java/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obs-websocket-community-projects%2Fobs-websocket-java/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266634000,"owners_count":23959674,"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","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["java","obs","obs-studio","websocket-client"],"created_at":"2025-07-23T07:09:13.291Z","updated_at":"2025-07-23T07:09:13.902Z","avatar_url":"https://github.com/obs-websocket-community-projects.png","language":"Java","readme":"# OBS WebSocket Java\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/images/obs-ws-java.png\" width=\"120\" align=\"center\"/\u003e\n  \u003cbr/\u003e\n  A Java library for the \u003ca href=\"https://github.com/obsproject/obs-websocket\"\u003eOBS-Studio WebSocket plugin\u003c/a\u003e initiated by \u003ca href=\"https://github.com/Palakis\"\u003ePalakis\u003c/a\u003e.\n\u003c/p\u003e\n\n## Software Requirements\n\n- OBS version 27+\n- OBS Websocket version 5+\n\n\u003e Note: Streamlabs OBS (SLOBS) is not supported\n\n## Dependencies\n\nInclude the library in your project from [Maven Central](https://mvnrepository.com/artifact/io.obs-websocket.community/client):\n\n### Maven\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.obs-websocket.community\u003c/groupId\u003e\n  \u003cartifactId\u003eclient\u003c/artifactId\u003e\n  \u003cversion\u003e2.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Gradle\n```groovy\ndependencies {\n    implementation 'io.obs-websocket.community:client:2.0.0'\n}\n```\n\n## Basic Usage \u0026 Examples\nThe _OBSRemoteController_ is the client entrypoint, providing methods to interact with OBS. Construct an (immutable) instance via the _builder_ and then connect.\n\n```java\nOBSRemoteController controller = OBSRemoteController.builder()\n  // set options, register for events, etc.\n  // continue reading for more information\n  .build();\ncontroller.connect();\n```\n\nTake a look at the [**example\nproject**](example/src/main/java/io/obswebsocket/community/client/example/Example.java) for a full\nexample.\n\nA description of every request and event can be found in the plugin's\n[**protocol.md**](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md)\nfile.\n\n### Authentication / OBS Details\n\nBy default, the builder connects to `localhost` on port `4455` without a password, and will wait 3 seconds for an initial response from OBS.\n\n\u003e Version 5+ of OBS Websockets requires a password by default, so we recommend setting a password.\n\n```java\nOBSRemoteController controller = OBSRemoteController.builder()\n  .host(\"localhost\")                  // Default host\n  .port(4455)                         // Default port\n  .password(\"your secure password\")   // Provide your password here\n  .connectionTimeout(3)               // Seconds the client will wait for OBS to respond\n  .build();\n```\n\n### OBS Event Registration\nListeners for OBS events can also be registered on the builder by specifying the event class and a callback that accepts the event.\n\n```java\nOBSRemoteController controller = OBSRemoteController.builder()\n  // with a method reference; better practice.\n  .registerEventListener(\n    StudioModeStateChangedEvent.class, someInstance::someMethod\n  )\n  // with an anonymous lambda; useful for exploring/debugging.\n  .registerEventListener(\n    CurrentProfileChangedEvent.class, (event) -\u003e System.out.println(event)\n  )\n  // ...     \n.build();\n```\n\n### Connecting and Client Lifecycle Events\nConnecting is non-blocking and by default the client will not connect until you call `connect()`. \n\nThere are many lifecycle-related events available, however we recommend registering at least the `onReady` callback, as this is invoked once the client is ready to accept requests.\n\n```java\n// Build the controller\nOBSRemoteController controller = OBSRemoteController.builder()\n  // ...\n  .lifecycle()\n    .onReady(someClassInstance::yourMethodMakingRequests)\n    .and()\n  .autoConnect(false) // Default; do not connect when built\n  // ...     \n.build();\n\n// Connect to OBS\ncontroller.connect();\n```\n\nWe do **not** recommend interacting with the controller outside the `onReady` callback; the main thread will likely complete before the client is ready to accept requests, and this will throw an error.\n```java\n// Build the controller\nOBSRemoteController controller = OBSRemoteController.builder()\n  // ...     \n.build();\n\n// Connect to OBS\ncontroller.connect();\n\n// Do NOT do this!\n// This will cause an ERROR and shut-down the client\ncontroller.getVersion(version -\u003e System.out.println(version));\n```\n\nIf you want to block main until the controller is ready, you can use a CompletableFuture; however, this is a poor practice so we do not show it here.\n\n### Error Handling\nWhen the OBS Websocket encounters a significant problem (failed authentication, unknown message type, etc) it will close the connection. These events can be observed in the  `onClose` lifecycle event. \n\nIndividual requests will include a status code(SourceNotFound, HotkeyNotFound, etc) as part of the response and do not result in the connection being closed.\n\nThe `onError` communicator and controller lifecycle events are reserved for exceptional events (null pointers and other exceptions) and for failure to connect to OBS (for example, if OBS Websocket isn't installed, if OBS isn't running, or it isn't accessible over the network).\n\n## Logging\nThis project ships with SLF4J as the logging facade.\n\nAs with any project using SLF4J, you are expected to setup a logger implementation. There\nare many examples of how to do this online; for your convenience we demonstrate below how to \nconfigure Maven to use Logback:\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n       \u003cgroupId\u003eio.obs-websocket.community\u003c/groupId\u003e\n        \u003cartifactId\u003eclient\u003c/artifactId\u003e\n        \u003cversion\u003e...\u003c/version\u003e\n      \u003c/dependency\u003e\n    \u003c/dependency\u003e\n    \n    \u003c!-- Add your desired logging implementation --\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003ech.qos.logback\u003c/groupId\u003e\n        \u003cartifactId\u003elogback-classic\u003c/artifactId\u003e\n        \u003cversion\u003e1.1.7\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\nOr with Gradle:\n```groovy\ndependencies {\n    implementation('io.obs-websocket.community:client:2.0.0')\n    implementation 'ch.qos.logback:logback-classic:1.1.7'\n}\n```\n\n## Migrating from Twasi 1.X.X\n\nVersions 1.X.X of this library were published under `Twasi` and were intended for OBS Websocket\n4.X.X.\n\nThe current version of the library (2.0.0+) is published under `io.obs-websocket.community`,\nrequires OBS Websocket 5.0.0+, and is not backwards compatible with 1.X.X.\n\nThere are several key differences to be aware of, for full details please see\nthe [current protocol](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md)\nfor OBS Websocket.\n\n### 📘 Notice to Developers: Repository Transfer 📘\nOn June 21st, 2021, this repository was transferred from the `Twasi` Organization to the \n`obs-websocket-community-projects` Organization. This was done to better align this library with the \ngreater OBS Websocket plugin community, and provide better administrative tools.\n\nRemotes will continue to operate as normal, due to GitHub automatic redirects. However, to avoid \nconfusion GitHub strongly recommends you update those remotes. \n\nIf you haven't updated your remote, you can check like so; the below example shows an old remote:\n```\nC:\\Users\\...\\websocket-obs-java\u003egit remote -v\norigin  https://github.com/Twasi/websocket-obs-java.git (fetch)\norigin  https://github.com/Twasi/websocket-obs-java.git (push)\n```\nYou can update and verify your remote is correct like this:\n```\nC:\\Users\\...\\websocket-obs-java\u003egit remote set-url origin https://github.com/obs-websocket-community-projects/websocket-obs-java.git\n(no output)\nC:\\Users\\...\\websocket-obs-java\u003egit remote -v\norigin  https://github.com/obs-websocket-community-projects/websocket-obs-java.git (fetch)\norigin  https://github.com/obs-websocket-community-projects/websocket-obs-java.git (push)\n```\nSee [Transferring a repository](https://docs.github.com/en/github/administering-a-repository/managing-repository-settings/transferring-a-repository)\nfor more information.\n\n\n### Requests, Events, and Subscriptions\n\nMost events and requests changed between the two libraries, due to changes in the OBS Websocket\nprotocol. You can view\nthe [current protocol](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md)\nfor the full list of available requests and events.\n\nOne new feature for events is `Subscriptions`. This feature reduces the performance impact for both\nOBS and your client by only sending event notifications you intend to receive (some events send\nmessages several times per second, continuously).\n\n### Building\n\nWhile the protocol requires subscriptions to be specified when identifying with OBS, you are not\nrequired to do this; our client library computes this for you based on what events you've registered\nlisteners for.\n\n### Authentication and Error Handling\n\nPrior to OBS Websocket 5+, authentication was optionally driven by the client. Now, the server\ndrives the conversation; it sends a `Hello` response on first connect, requires the client to\nrespond with an `Identify`, and then either drops the connection (failed authentication) or responds\nwith an `Identified` success response.\n\nThis process is mirrored in the order of lifecycle events on the client. During successful\nauthentication the sequence would look like this:\n\n```\nonConnect -\u003e onHello -\u003e onIdentified -\u003e onReady\n```\nAnd in the case of failed authentication, the server closes the connection:\n```\nonConnect -\u003e onHello -\u003e onClose -\u003e onDisconnect\n```\n\nNote that this is a change in this library from 1.X.X, which conflated connecting and authenticating in a single step, and relegated authentication failures to the error callback.\n\nThe `onConnect` callback only denotes that OBS could be reached over the network and **not** that\nit is authenticated and ready to accept requests.\n\nThe `onError` callback is only be used to monitor for critical exceptions (null pointers, failure to\nreach OBS, etc...), and not any authentication failures. Any call to `onError` will cause the client to\nautomatically disconnect/stop.\n\nSee the protocol at\n[OBS Websocket 5 Protocol](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md)\nfor more detailed information, including WebSocketCloseCode and enumerations.\n\n### Blocking/Non-Blocking Connections\nIn 1.X.X, there was an `isFailed` blocking method available that could be called to block the main thread until the client was ready to send requests to OBS.\n\nThis has since been removed, as blocking the main thread is a poor way to handle program flow. Please use the `onReady` lifecycle event callback instead, as described above.\n\n---\n\n## Contributing / Issues\nFeedback and help are greatly appreciated! \n\nIf you want to contribute on this project, we ask you to:\n 1) [File a GitHub Issue](https://github.com/obs-websocket-community-projects/obs-websocket-java/issues/new/choose) to track it\n 2) Fork the repo and make a pull-request\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) for more information.\n\n---\n\n## Support\nJoin our [Discord Server](https://discord.gg/F7spyEQWjM), we'll try to answer your questions as soon as possible!\n\n---\n\n**Thanks to OBS WebSocket team for the great plugin!**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobs-websocket-community-projects%2Fobs-websocket-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobs-websocket-community-projects%2Fobs-websocket-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobs-websocket-community-projects%2Fobs-websocket-java/lists"}