websocket-obs-java

A java library for the OBS-Studio websocket plugin by Palakis.

---

Notice: Last 1.X.X Release! Stay Tuned for 2.0.0...

As announced for the Palakis OBS Websocket plugin, Release 4.9.1 will be its last release before 5.X.X. The next major release will introduce breaking changes, overhauling its protocol to make room for many improvements.

For us, this means we will focus on updating this library so that it is compatible. We will also do a small overhaul ourselves to improve maintainability (addressing serialization boilerplate, and lifecycle management).

The next release for websocket-obs-java will be 2.0.0, and all further work on the develop branch (at version 1.3.0) will stop, except for major bugs/issues. Like the 5.X.X release for Palakis, ours will also introduce breaking changes.

You can view the release notes for 1.3.0 here.

---

Getting started

First include the library in your project using Maven:

<!-- https://mvnrepository.com/artifact/net.twasi/obs-websocket-java -->
<dependency>
  <groupId>net.twasi</groupId>
  <artifactId>obs-websocket-java</artifactId>
  <version>1.3.0</version> <!-- Last Obs Websocket 4.X.X Compatible Release -->
</dependency>

To get started just instantiate the OBSRemoteController:

OBSRemoteController controller = new OBSRemoteController("ws://localhost:4444", false);

if (controller.isFailed()) { // Awaits response from OBS
  // Here you can handle a failed connection request
}
// Now you can start making requests

If you don't want your program to wait for a connection you could alternatively register an onConnect callback:

controller.registerConnectCallback(response -> {
	log.debug(response.getObsStudioVersion());

	// Other requests...
});

Websocket server with authentication

If your OBS websocket server is secured with a password, pass the password as a string to the controller:

OBSRemoteController controller = new OBSRemoteController("ws://localhost:4444", false, "myPassword");

Catch any authentication errors by registering a callback for this:

controller.registerConnectionFailedCallback(message -> {
    log.error("Failed to connect: " + message);
})

---

Supported requests and events

A list of supported requests and events can be found in the corresponding enum class files:

• RequestType class file
• EventType class file

A description of every request and event can be found in the plugin's Protocol.MD file.

---

Examples

Examples can be found here. Just uncomment the requests you want to test or copy.

---

Logging

This project ships with SLF4J, and uses the SLF4J-Simple binding by default so logs are printed directly to the console.

If you wish to override this, for example with Logback, you must exclude SLF4J in your POM and add the dependency to the binding you want (depends on the vendor)

<dependencies>
    <dependency>
        <groupId>net.twasi</groupId>
        <artifactId>obs-websocket-java</artifactId>
        <version>1.0.6-tinatiel-1-0-0</version>
        <!-- Exclude the default logging implementation -->
        <exclusions>
            <exclusion>
                <groupId>org.slf4j</groupId>
                <artifactId>slf4j-simple</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    
    <!-- Add your desired logging implementation -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.1.7</version>
    </dependency>
</dependencies>

Contribution

If you miss an endpoint feel free to make a pull request. Any help is appreciated.

📘 Notice to Developers: Repository Transfer 📘

On June 21st, 2021, this repository was transferred from the Twasi Organization to the obs-websocket-community-projects Organization. This was done to better align this library with the greater Palakis' OBS Websocket plugin community, and provide better administrative tools.

Remotes will continue to operate as normal, due to GitHub automatic redirects. However, to avoid confusion GitHub strongly recommends you update those remotes.

If you haven't updated your remote, you can check like so; the below example shows an old remote:

C:\Users\...\websocket-obs-java>git remote -v
origin  https://github.com/Twasi/websocket-obs-java.git (fetch)
origin  https://github.com/Twasi/websocket-obs-java.git (push)

You can update and verify your remote is correct like this:

C:\Users\...\websocket-obs-java>git remote set-url origin https://github.com/obs-websocket-community-projects/websocket-obs-java.git
(no output)
C:\Users\...\websocket-obs-java>git remote -v
origin  https://github.com/obs-websocket-community-projects/websocket-obs-java.git (fetch)
origin  https://github.com/obs-websocket-community-projects/websocket-obs-java.git (push)

See Transferring a repository for more information.

Building

If you've forked the repository and want to run the install goal to use your fork in your own project, please be aware the artifacts generated require being signed via GPG.

Once you've installed GPG and created a key-pair, you'll be prompted for your passphrase everytime you run the build. You can automate this by supplying gpg.passphrase property during the build, for example:

mvn verify -Dgpg.passphrase=YOURPASSPHRASE

In IntelliJ, you can supply the property via File > Settings > Build, Execution, Deployment > Maven > Runner > Properties. Once the gpg.passphrase property has been set there, you won't be prompted everytime you run the build.

---

Thanks to Palakis for the great plugin!