OSC Triggers

Fire OSC messages at specific timecode positions—perfect for cueing lighting, sound, and video.

🌐 Web UI ⌨️ CLI 🔌 HTTP API 📡 OSC

Overview

OSC Triggers let you send OSC messages to external systems when playback reaches a specific timecode. Use them to:

  • Cue lighting consoles at precise moments
  • Trigger sound effects in QLab or Ableton
  • Start video playback in sync with timecode
  • Control any OSC-capable device automatically

How It Works

Create triggers with a timecode position, an OSC destination, and a message. When playback passes that timecode, BPTimecode sends the message automatically.

🌐 Web UI

Creating a Trigger

  1. Select a timecode slot
  2. Click the Triggers tab
  3. Click + Add Trigger
  4. Enter the timecode position (e.g., 00:01:30:00)
  5. Configure the OSC destination (IP and port)
  6. Enter the OSC address and arguments
  7. Click Save

Trigger List

The Triggers tab shows all triggers for the selected slot, sorted by timecode. Each trigger displays:

  • Timecode position
  • OSC destination and message
  • Enable/disable toggle
  • Last fired indicator

Editing & Deleting

Click any trigger to edit its settings. Use the trash icon to delete.

⌨️ CLI

List Triggers

bptimecode trigger list --slot 1

Create a Trigger

bptimecode trigger create --slot 1 \
  --timecode 00:01:30:00 \
  --dest 192.168.1.100:53000 \
  --address /go \
  --args "1"

Options

Option Description
--slot Slot ID, number, or name
--timecode Timecode position (HH:MM:SS:FF)
--dest OSC destination (host:port)
--address OSC address to send
--args OSC arguments (space-separated)
--name Optional label for the trigger

Delete a Trigger

bptimecode trigger delete --slot 1 --id abc123

Enable/Disable

bptimecode trigger disable --slot 1 --id abc123
bptimecode trigger enable --slot 1 --id abc123

🔌 HTTP API

Endpoints

Method Endpoint Description
GET /api/v1/slots/:id/triggers List triggers for slot
POST /api/v1/slots/:id/triggers Create a trigger
PATCH /api/v1/slots/:id/triggers/:triggerId Update a trigger
DELETE /api/v1/slots/:id/triggers/:triggerId Delete a trigger

Create a Trigger

curl -X POST http://localhost:5050/api/v1/slots/1/triggers \
  -H "Content-Type: application/json" \
  -d '{
    "timecode": {"hours": 0, "minutes": 1, "seconds": 30, "frames": 0},
    "destination": {"host": "192.168.1.100", "port": 53000},
    "address": "/go",
    "arguments": [1],
    "name": "Cue 1 Go"
  }'

Response

{
  "id": "abc123",
  "timecode": "00:01:30:00",
  "destination": {"host": "192.168.1.100", "port": 53000},
  "address": "/go",
  "arguments": [1],
  "name": "Cue 1 Go",
  "enabled": true
}

📡 OSC

Triggers can also be managed via OSC:

Addresses

Address Arguments Description
/bptimecode/slot/:ref/trigger/create timecode, destHost, destPort, address, [args...] Create a trigger
/bptimecode/slot/:ref/trigger/delete triggerId Delete a trigger
/bptimecode/slot/:ref/trigger/enable triggerId Enable a trigger
/bptimecode/slot/:ref/trigger/disable triggerId Disable a trigger

Example

# Create a trigger at 00:01:30:00 that sends /go to 192.168.1.100:53000
oscsend localhost 5051 /bptimecode/slot/1/trigger/create \
  s "00:01:30:00" s "192.168.1.100" i 53000 s "/go"

Use Cases

🎭 Theater: Cueing QLab

Send /go commands to QLab at specific moments during a show:

  • 00:05:00:00 → /go (House to half)
  • 00:05:30:00 → /go (Blackout)
  • 00:06:00:00 → /go (Scene 1 lights)

💡 Concerts: Lighting Cues

Trigger lighting presets on your console via OSC:

  • Send /preset/1 at verse timecodes
  • Send /preset/2 at chorus timecodes
  • Sync strobe effects to specific frames

🎬 Film: Sync Playback

Trigger video playback systems in sync with timecode:

  • Start background video at 00:00:00:00
  • Trigger overlay graphics at specific marks
  • Sync multiple video players
← MTC (MIDI) OSC Reference →