---

obsctl gives streamers, operators, and automation scripts one dependable control surface for OBS Studio. Use the responsive terminal dashboard while you are live, run precise one-shot commands from scripts, or keep the local daemon running as a user service.

╭─ OBSCTL // BROADCAST COMMAND CENTER ─────────────────────────────╮
│ ● daemon: connected   ● OBS: connected   scene: Main Camera      │
├─ LIVE TELEMETRY ─────────────────────────────────────────────────┤
│ CPU  3.2%    FPS 60.0    MEM 742MB    NET 5842kbps               │
├─ Scenes ────────────────┬─ Audio Matrix ─────────────────────────┤
│ ▶ Main Camera           │ ● Mic/Aux          72%  ███████░░░     │
│   Screen Share          │ ○ Desktop Audio    48%  █████░░░░░     │
╰─────────────────────────┴────────────────────────────────────────╯

✨ Why obsctl?

🚀 Quick start

Prerequisites

• Linux
• OBS Studio with obs-websocket 5.x enabled
• Crystal 1.20.2+ and Shards when building from source
• A UTF-8 terminal; a Nerd Font is recommended for the richest icon set

1. Build

git clone https://github.com/worxbend/obsctl.git
cd obsctl
shards install
make release
install -Dm755 bin/obsctl ~/.local/bin/obsctl

The release binary is written to bin/obsctl. Prebuilt Linux AMD64 archives are also available on the Releases page.

2. Initialize

obsctl init
obsctl validate-config

The default configuration lives at ~/.config/obsctl/config.yml. Override it with --config PATH or OBSCTL_CONFIG.

If OBS authentication is enabled, export its password before starting the server:

export OBS_WEBSOCKET_PASSWORD='your OBS WebSocket password'

No password? No problem—when the variable is absent, obsctl attempts the connection with an empty password.

3. Start the daemon and TUI

In one terminal:

obsctl server --headless

In another:

obsctl

Once connected, import live scene and audio names while preserving your local settings:

obsctl dump-config

[!TIP] Scene and audio names discovered from OBS work immediately. Running dump-config is useful for adding memorable aliases and shortcuts, but it is not required before using the TUI.

🎛️ The control room

The TUI is a thin local client: it subscribes to daemon state, OBS events, and logs, then renders them through CryTUI. It does not open another OBS WebSocket connection.

Keyboard map

Rapid volume keypresses update the display immediately and coalesce into one OBS command 120 ms after input stops. Terminal shrinking and expansion trigger a full safe repaint; normal frames return to cell-level incremental updates.

Command palette

Press / and use the same grammar as the CLI:

/scene "Main Camera"
/mute Mic/Aux
/vol "Desktop Audio" 65
/profile Streaming
/collection Gaming
/stream
/rec
/status
/reconnect

🧰 CLI & automation

The daemon-backed CLI is designed to be pleasant interactively and predictable inside scripts.

# Status
obsctl status
obsctl obs-status
obsctl server-status

# Scenes and audio
obsctl scene main
obsctl mute mic
obsctl unmute mic
obsctl toggle-mute mic
obsctl volume "Desktop Audio" 70

# Studio and output controls
obsctl stream
obsctl record
obsctl reconnect

# Configuration and lifecycle
obsctl validate-config
obsctl dump-config
obsctl reload-config
obsctl shutdown-server

Aliases, shortcuts, exact OBS names, and case-insensitive names are supported. Quote names containing spaces.

JSON mode

Add --json before or after a scriptable command:

obsctl --json status
obsctl scene main --json

Every JSON invocation writes exactly one envelope to stdout:

{
  "ok": true,
  "result": {"message": "scene set: Main Camera"},
  "error": null,
  "exit_code": 0
}

Failures use canonical error codes and matching process exit statuses, making them straightforward to handle in shell scripts and other tools. See the command reference for the full grammar, supported JSON commands, error codes, and status schema.

🏗️ Architecture

flowchart LR
    OBS["🎥 OBS Studio<br/>obs-websocket 5.x"]
    D["🧠 obsctl server<br/>single connection owner"]
    T["🎛️ CryTUI dashboard"]
    C["⚙️ CLI / scripts"]
    S["🛠️ systemd --user"]

    OBS <-->|WebSocket| D
    D <-->|Unix socket IPC| T
    D <-->|Unix socket IPC| C
    S -. supervises .-> D

The daemon is the authoritative state owner. This boundary provides:

• exactly one OBS WebSocket connection per user session;
• shared state and event delivery across every local client;
• centralized reconnect, validation, logging, and secret handling;
• short-lived CLI processes without repeated OBS handshakes.

The Unix socket lives under $XDG_RUNTIME_DIR/obsctl/ when an XDG runtime directory is available, with a user-specific /tmp/obsctl-$UID/ fallback. Control remains local—there is no network-facing obsctl API.

🔧 Configuration

A minimal configuration looks like this:

version: 1

connection:
  host: 127.0.0.1
  port: 4455
  password_env: OBS_WEBSOCKET_PASSWORD

reconnect:
  enabled: true
  endless: true

ui:
  theme: default
  advanced_ui: true
  show_icons: true
  locale: en

scenes:
  - name: Main Camera
    alias: main
    shortcut: "1"

audio:
  inputs:
    - name: Mic/Aux
      alias: mic
      shortcut: m

Important behavior:

• secrets belong in environment variables; plaintext password values produce a secret-safe warning;
• unknown top-level fields are rejected instead of being silently discarded;
• config rewrites are atomic and preserve backups;
• dump-config refuses to create ambiguous aliases or shortcuts;
• OBSCTL_LOCALE overrides ui.locale; supported UI locales are en and uk;
• custom themes can override any subset of the semantic color palette.

See the complete configuration reference.

🛠️ Run as a user service

No root daemon is required. Install a systemd --user unit using the current binary path:

obsctl service install
obsctl service start
obsctl service status

Other lifecycle commands:

obsctl service stop
obsctl service restart
obsctl service uninstall

The generated unit lives at ~/.config/systemd/user/obsctl.service.

🩺 Troubleshooting

Show connection and retry diagnostics

obsctl --log-level debug server --headless

Server logs are mirrored to stderr and persisted at ~/.local/state/obsctl/obsctl.log. Passwords and generated authentication strings are redacted from both sinks. WebSocket resets include the close code, reason, reconnect attempt, and next delay.

The CLI says the server is unavailable

Start it directly:

obsctl server --headless

Or install/start the user service. Thin client commands exit with status 3 when the daemon or OBS connection is unavailable.

OBS was offline during startup

Reconnect is enabled by default. Check obsctl server-status, then request an immediate attempt with obsctl reconnect. If reconnect.enabled: false, restart the server after OBS becomes available.

🧑‍💻 Development

shards install
make format
make test
make build
make release
make lint

The local test suite is deterministic and does not require OBS Studio. It uses a fake obs-websocket server, Unix-socket integration tests, memory rendering, ANSI assertions, and real PTY lifecycle probes.

Optional cross-implementation fixture verification against a sibling ../obsctl-rs checkout:

make contract-rs-compat

Strict compatibility mode requires a recognized fixture root in both repositories. See docs/protocol.md for the contract model.

📚 Documentation

🤝 Contributing

Issues, focused bug reports, documentation improvements, and pull requests are welcome. For behavior changes, include a regression test at the narrowest useful layer and run the development checks above before opening a PR.

Useful reports include:

• your OBS Studio and obs-websocket versions;
• terminal name, dimensions, font, and $TERM for rendering issues;
• sanitized obsctl.log excerpts for connection problems;
• the exact command, expected result, and actual result.

Please never include OBS passwords or generated authentication strings.

📜 License

obsctl is released under the MIT license.

---