OBS Integration

Overview

The OBS Integration module provides OBS WebSocket connectivity for remote control of OBS Studio from the Lumio dashboard. It supports scene switching, stream/recording start/stop, and connection status monitoring. OBS configuration (port, password, remote host) is stored in the integration_configs table with the password encrypted at rest. The module includes a connection testing feature that attempts a WebSocket handshake with a 10-second timeout.

Architecture

Backend

• GraphQL (apps/api/src/graphql/obs.rs) -- Queries for OBS config, status, and remote connection status. Mutations for saving/deleting config, testing connection, and controlling stream/recording/scenes.
• REST (apps/api/src/routes/obs_integration.rs) -- REST endpoints for OBS config CRUD, credential retrieval, status, and connection testing.
• OBS Remote Client (crates/lo-obs-remote/) -- ObsRemoteClient handles WebSocket connections to OBS Studio, including authentication with the encrypted password.
• Configuration Storage -- OBS config is stored as JSONB in the integration_configs table with platform = "obs". The password field is encrypted using AES-256.

Frontend

• OBS settings page with port, password, and remote mode configuration.
• Stream/recording control buttons.
• Scene switcher with list of available scenes.
• Connection status indicator.

API

GraphQL Queries

Query	Permission	Description
obsConfig	obs:read	Full OBS config: port, remote_enabled, remote_host, has_password flag, timestamps. Never exposes the actual password.
obsStatus	obs:read	Lightweight status: configured flag, port, remote settings
obsRemoteStatus	obs:read	Remote connection status from OBS worker: connected flag, stream/recording status, scene list, current scene. (Placeholder -- reads from WorkerManager/Redis in production.)

GraphQL Mutations

Mutation	Permission	Description
saveObsConfig(port?, password?, remoteEnabled?, remoteHost?)	obs:edit	Save (upsert) OBS config. Port defaults to 4455. Password is encrypted before storage.
deleteObsConfig	obs:delete	Delete OBS integration config
testObsConnection	obs:edit	Test WebSocket connection to OBS. Only available when remote mode is enabled. 10-second timeout. Returns success/error.
obsControlStream(action)	obs:edit	Control streaming: "start" or "stop"
obsControlRecording(action)	obs:edit	Control recording: "start" or "stop"
obsSwitchScene(sceneName)	obs:edit	Switch the active OBS scene

REST Endpoints

Method	Path	Permission	Description
GET	/v1/integrations/obs	obs:read	Get OBS config
PUT	/v1/integrations/obs	obs:edit	Save OBS config
DELETE	/v1/integrations/obs	obs:delete	Delete OBS config
GET	/v1/integrations/obs/credentials	obs:read	Get OBS credentials (decrypted, for internal use)
GET	/v1/integrations/obs/status	obs:read	Get OBS connection status
POST	/v1/integrations/obs/test	obs:edit	Test OBS WebSocket connection

Permissions

Permission	Description
obs:read	Read OBS configuration and status
obs:edit	Edit OBS configuration, test connection, control stream/recording/scenes
obs:delete	Delete OBS configuration

Database

Table	Database	Description
integration_configs	PostgreSQL	id, account_id, platform ("obs"), label ("OBS Studio"), enabled, config (JSONB), created_at, updated_at. Unique on (account_id, platform).

Config JSONB Structure

{
  "port": 4455,
  "password": "encrypted_string_or_null",
  "remote_enabled": false,
  "remote_host": "192.168.1.100"
}

• port -- OBS WebSocket port (default 4455)
• password -- Encrypted OBS WebSocket password (null if not set)
• remote_enabled -- Whether remote (non-localhost) connections are enabled
• remote_host -- Remote host address (only used when remote_enabled is true)

Data Flow

1. User configures OBS settings (port, optional password, optional remote host).
2. Password is encrypted via crypto::encrypt() and stored as part of the JSONB config.
3. User can test the connection, which attempts a WebSocket handshake to ws://{host}:{port} with decrypted password.
4. Stream/recording/scene commands are sent via the WorkerManager to the OBS Remote Client.
5. OBS Remote Client communicates with OBS Studio over the OBS WebSocket protocol.

Plan Restriction

OBS remote mode (remote_enabled: true) is only available on the Pro plan and above (obs_remote_allowed in PlanLimits).

Key Files

Path	Description
apps/api/src/graphql/obs.rs	GraphQL queries and mutations
apps/api/src/routes/obs_integration.rs	REST endpoints
apps/api/src/routes/obs_remote.rs	Remote control routes
crates/lo-obs-remote/	OBS WebSocket client
apps/api/src/crypto.rs	Password encryption/decryption