obs-relay API Reference

curl http://localhost:8080/health

curl http://localhost:8080/obs/version

curl http://localhost:8080/obs/scenes

curl http://localhost:8080/obs/scene/current

# Switch to your live scene
curl -X POST http://localhost:8080/obs/scene/Live

# Switch to BRB screen
curl -X POST http://localhost:8080/obs/scene/BRB

# Scene names with spaces need URL encoding
curl -X POST http://localhost:8080/obs/scene/My%20Scene

# Enable studio mode
curl -X POST "http://localhost:8080/obs/studio/enable?enabled=true"

# Disable studio mode
curl -X POST "http://localhost:8080/obs/studio/enable?enabled=false"

# Workflow: set up preview, then cut when ready
curl -X POST "http://localhost:8080/obs/studio/enable?enabled=true"
# ... configure your preview scene in OBS ...
curl -X POST http://localhost:8080/obs/studio/transition

curl http://localhost:8080/presets

# Go live
curl -X POST http://localhost:8080/presets/live/activate

# BRB (also auto-mutes Mic per preset config)
curl -X POST http://localhost:8080/presets/brb/activate

# Standby / holding screen
curl -X POST http://localhost:8080/presets/standby/activate

# Intermission (activates linked playlist)
curl -X POST http://localhost:8080/presets/intermission/activate

# End of show slate
curl -X POST http://localhost:8080/presets/end_card/activate

curl http://localhost:8080/playlists

curl http://localhost:8080/playlists/status

# Create a simple content block playlist from local files
curl -X POST http://localhost:8080/playlists/create \
  -H "Content-Type: application/json" \
  -d '{
    "name": "friday-night",
    "items": [
      "/media/intro.mp4",
      "/media/episode-01.mp4",
      "/media/bumper.mp4",
      "/media/episode-02.mp4",
      "/media/outro.mp4"
    ],
    "loop": false,
    "save": true
  }'

# Create a looping ambient playlist from HTTP streams
curl -X POST http://localhost:8080/playlists/create \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ambient-loop",
    "items": [
      "https://example.com/streams/ambient-a.mp4",
      "https://example.com/streams/ambient-b.mp4"
    ],
    "loop": true
  }'

curl -X POST http://localhost:8080/playlists/upload \
  -F "file=@/path/to/my-show.m3u"

# Activate main playlist from track 0
curl -X POST http://localhost:8080/playlists/main/activate

# Switch to intermission playlist (Pluto.tv channel change)
curl -X POST http://localhost:8080/playlists/intermission/activate

# Activate main playlist but start at track 3 (0-indexed)
curl -X POST "http://localhost:8080/playlists/main/activate?position=3"

# Switch to a pre-show holding playlist
curl -X POST http://localhost:8080/playlists/pre-show/activate

curl -X POST http://localhost:8080/playlists/next

curl -X POST http://localhost:8080/playlists/prev

# Jump to track 0 (first track / restart)
curl -X POST http://localhost:8080/playlists/seek/0

# Jump to track 4 (fifth item)
curl -X POST http://localhost:8080/playlists/seek/4

curl -X DELETE http://localhost:8080/playlists/old-show

# Set Mic to unity gain (full volume)
curl -X POST http://localhost:8080/obs/source/Mic/volume \
  -H "Content-Type: application/json" \
  -d '{ "volume_db": 0 }'

# Reduce Desktop Audio by 6dB (roughly half)
curl -X POST http://localhost:8080/obs/source/Desktop%20Audio/volume \
  -H "Content-Type: application/json" \
  -d '{ "volume_db": -6 }'

# Near-silence (duck background music during speech)
curl -X POST http://localhost:8080/obs/source/Background%20Music/volume \
  -H "Content-Type: application/json" \
  -d '{ "volume_db": -40 }'

# Mute the microphone (e.g. going to BRB)
curl -X POST http://localhost:8080/obs/source/Mic/mute \
  -H "Content-Type: application/json" \
  -d '{ "muted": true }'

# Unmute when returning from BRB
curl -X POST http://localhost:8080/obs/source/Mic/mute \
  -H "Content-Type: application/json" \
  -d '{ "muted": false }'

curl http://localhost:8080/obs/stream/status

curl -X POST http://localhost:8080/obs/stream/start

curl -X POST http://localhost:8080/obs/stream/stop

# Connect with wscat (npm install -g wscat)
wscat -c ws://localhost:8080/ws

# JavaScript browser / Node.js
const ws = new WebSocket('ws://localhost:8080/ws');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log('Event:', msg.event, msg.data);
};

ws.onopen = () => {
  // Send a command
  ws.send(JSON.stringify({
    cmd: 'activate_preset',
    params: { name: 'brb' }
  }));
};

curl http://localhost:8080/osc/status