OpenVR WebSocket API

Overview

OpenVR exposes a local WebSocket server for remote control and playback updates. You can connect, read the handshake, send commands, and listen for playback events.

Connect

Default URL:

ws://127.0.0.1:8086

The port can be changed in the app. If it is changed, use that port instead.

Message format

All messages are JSON objects sent as text frames. The type field tells you what the message is.

Handshake (server -> client)

Sent once right after a client connects.

{
  "type": "handshake",
  "server": "openvr",
  "version": "1.0",
  "timestamp": 1712878340.123,
  "playbackState": {
    "url": "https://example.com/video.mp4",
    "preferredName": "Example Video",
    "position": 12.34,
    "isPlaying": false,
    "rate": 1.0
  }
}

Fields:

• timestamp is seconds since the Unix epoch.
• playbackState can be an empty object {} when nothing is loaded.
• Any field inside playbackState can be null if unknown.

Commands (client -> server)

Commands are routed to the app’s command center.

Seek

{ "type": "command", "command": "seek", "payload": { "position": 3.0 } }

Play

{ "type": "command", "command": "play" }

Pause

{ "type": "command", "command": "pause" }

Load media

{
  "type": "command",
  "command": "loadMedia",
  "payload": {
    "url": "https://example.com/stream.m3u8",
    "preferredName": "Example Stream"
  }
}

Playback events (server -> client)

Playback updates are sent as type: "playback" events.

mediaPathChanged

{
  "type": "playback",
  "event": "mediaPathChanged",
  "payload": {
    "url": "https://example.com/video.mp4",
    "preferredName": "Example Video"
  }
}

isPlaying

{
  "type": "playback",
  "event": "isPlaying",
  "payload": {
    "isPlaying": true,
    "position": 12.34
  }
}

rateChanged

{
  "type": "playback",
  "event": "rateChanged",
  "payload": {
    "rate": 1.5
  }
}

seeked

{
  "type": "playback",
  "event": "seeked",
  "payload": {
    "position": 3.0
  }
}

Notes:

• url, preferredName, and position can be null when not available.