Tutorials & Integration Examples

Real-world examples to get you up and running quickly

💡

Sync Lighting with Art-Net Timecode

Control your lighting console or software (MA, Hog, ETC, etc.) by sending Art-Net timecode from BPTimecode. Perfect for synchronized light shows, concerts, and corporate events.

1

Configure Art-Net Output

Create or edit your config.yaml to include Art-Net output:

# config.yaml
artnet:
  enabled: true
  outputs:
    - name: "Lighting Console"
      host: "192.168.1.100"  # Your console's IP
      port: 6454             # Standard Art-Net port
2

Start BPTimecode

bptimecode serve --config config.yaml
3

Create and Route a Slot

Use the API to create a slot and route it to Art-Net:

# Create a slot at 30fps
curl -X POST http://localhost:8080/api/slots \
  -H "Content-Type: application/json" \
  -d '{"name": "Main Show", "frameRate": 30}'

# Route slot 1 to Art-Net output "Lighting Console"
curl -X POST http://localhost:8080/api/routing \
  -H "Content-Type: application/json" \
  -d '{"slotId": 1, "output": "artnet", "target": "Lighting Console"}'
4

Control Playback

# Start playback
curl -X POST http://localhost:8080/api/slots/1/play

# Jump to a specific timecode and play
curl -X POST http://localhost:8080/api/slots/1/goto \
  -H "Content-Type: application/json" \
  -d '{"timecode": "01:00:00:00", "action": "play"}'
💡 Pro Tip: Set up presets for common cue points. This lets you instantly jump to specific moments in your show.
⏰

Automated Scheduled Playback with Cron

Use cron jobs to automatically start timecode at specific times. Perfect for recurring broadcasts, scheduled performances, or automated testing.

1

Create a Control Script

Create a script to control BPTimecode:

#!/bin/bash
# /opt/bptimecode/start-show.sh

# Jump to beginning and start playback
curl -s -X POST http://localhost:8080/api/slots/1/goto \
  -H "Content-Type: application/json" \
  -d '{"timecode": "00:00:00:00", "action": "play"}'

echo "Show started at $(date)"
2

Make It Executable

chmod +x /opt/bptimecode/start-show.sh
3

Add Cron Job

Edit your crontab with crontab -e:

# Start show every day at 7:00 PM
0 19 * * * /opt/bptimecode/start-show.sh >> /var/log/bptimecode-show.log 2>&1

# Stop playback at 10:00 PM
0 22 * * * curl -s -X POST http://localhost:8080/api/slots/1/stop
💡 Pro Tip: Use systemd timers instead of cron for more reliable scheduling with better logging and dependency management.
🎛ī¸

StreamDeck with Bitfocus Companion

Control BPTimecode from your Elgato StreamDeck using Bitfocus Companion's HTTP module or OSC module for tactile, one-touch control.

1

Add Generic HTTP Module

In Companion, add a new connection:

  • Search for Generic HTTP
  • Set Base URL to http://your-bptimecode-ip:8080
2

Create Buttons

Configure buttons with these HTTP actions:

â–ļī¸ Play: POST /api/slots/1/play
⏚ī¸ Stop: POST /api/slots/1/stop
⏸ī¸ Pause: POST /api/slots/1/pause
⏎ī¸ Reset: POST /api/slots/1/goto with body {"timecode": "00:00:00:00"}
3

Alternative: Use OSC

For lower latency, use the Generic OSC module:

# OSC commands for BPTimecode
/slot/1/play
/slot/1/stop
/slot/1/pause
/slot/1/goto 01:00:00:00
🍓

Dedicated Timecode Server on Raspberry Pi

Turn a Raspberry Pi 4 or newer into a dedicated timecode distribution system. Low cost, low power, always-on timecode for your studio or venue.

1

Install BPTimecode

SSH into your Pi and run:

curl -fsSL https://timecode.bpshowtools.com/install.sh | bash

The installer automatically detects ARM64 architecture.

2

Create a Systemd Service

sudo tee /etc/systemd/system/bptimecode.service > /dev/null << 'EOF'
[Unit]
Description=BPTimecode Server
After=network.target

[Service]
Type=simple
User=pi
ExecStart=/usr/local/bin/bptimecode serve --port 8080
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
3

Enable and Start

sudo systemctl daemon-reload
sudo systemctl enable bptimecode
sudo systemctl start bptimecode

# Check status
sudo systemctl status bptimecode
4

Access from Network

Access the web UI from any device on your network:

http://raspberrypi.local:8080
💡 Pro Tip: For mission-critical shows, use a read-only filesystem with raspi-config to prevent SD card corruption.
🎭

QLab Integration via OSC

Trigger BPTimecode from QLab cues using OSC. Perfect for theater productions, corporate presentations, and any show controlled from QLab.

1

Configure OSC in BPTimecode

# config.yaml
osc:
  enabled: true
  listenPort: 53000
2

Add OSC Destination in QLab

  • Open QLab Settings → Network
  • Add new OSC destination
  • Set host to BPTimecode IP address
  • Set port to 53000
3

Create Network Cues

Use Network cues with these OSC messages:

# Start playback from a specific timecode
/slot/1/goto "01:00:00:00" play

# Simple play/stop
/slot/1/play
/slot/1/stop

# Jump to preset
/preset/recall "Act2Start"
💡 Pro Tip: Use QLab's pre-wait to fire timecode cues slightly ahead of your video/audio cues to account for network latency.

Need Help?

Can't find what you're looking for? Check the full documentation or ask on GitHub.

All Documentation Ask a Question