OBS WebSocket CLI (Quarkus + Picocli)

A lightweight command-line client for controlling OBS Studio recording via the OBS WebSocket v5 protocol.

Useful for Wayland based compositors to map system hotkeys to OBS Actions, for example in KDE KWIN.

Built with:

• Quarkus
• Picocli
• WebSockets Next (Quarkus)
• Jackson (Quarkus)

---

Features

• Connects to OBS via WebSocket (ws:// or wss://).
• Handles the Hello → Identify → Identified handshake (with or without authentication).
• Supports recording control actions:
  • ToggleRecord
  • StartRecord
  • StopRecord
  • PauseRecord
  • ResumeRecord
• Reads connection settings from application.properties, overridable via environment variables.

---

Configuration

Default values live in src/main/resources/application.properties:

obs.host=127.0.0.1
obs.port=4455
obs.path=/
obs.tls=false
obs.password=
obs.wait-seconds=2

Environment Variable Overrides

Quarkus automatically maps environment variables in UPPERCASE with underscores:

• OBS_HOST
• OBS_PORT
• OBS_PATH
• OBS_TLS
• OBS_PASSWORD
• OBS_WAIT_SECONDS

Example:

export OBS_HOST=192.168.1.50
export OBS_PASSWORD=supersecret

---

Build

JAR

./mvnw package

This produces a runnable JAR in target/ (e.g. target/obs-ws-cli-1.0.0-runner.jar).

Native Binary

./mvnw package -Dnative -Dquarkus.native.container-build=true

This produces a native binary in target/ (e.g. target/obs-ws-cli-1.0.0-runner).

---

Usage

java -jar target/*-runner.jar --action <Action>

Where <Action> is one of:

• ToggleRecord
• StartRecord
• StopRecord
• PauseRecord
• ResumeRecord

Examples

Start recording (with password set via env):

OBS_PASSWORD=secret java -jar target/*-runner.jar --action StartRecord

Pause recording:

java -jar target/*-runner.jar --action PauseRecord

Toggle recording on/off:

java -jar target/*-runner.jar --action ToggleRecord

---

OBS Setup

1. In OBS Studio, install/enable obs-websocket v5 (OBS 28+ has it built in).
2. Go to Tools → WebSocket Server Settings:
   • Enable server.
   • Default port: 4455.
   • Optionally set a password.
3. Run this CLI with matching obs.host, obs.port, and obs.password.

---

Exit Codes

• 0 → Success, got a valid response.
• 1 → Internal error (exception, interrupted, etc).
• 2 → Timed out waiting for a response.

---