Automatic Scene Switching & OBS Control

VPE connects to OBS via the WebSocket v5 protocol. This gives it full control over scenes, sources, filters, transitions, audio, and recording — everything you can do manually, VPE can do programmatically.

When VPE decides an action is needed (based on events and policies), it sends commands to OBS in real-time. The response time from event detection to OBS action is under 120ms.

VPE discovers your OBS setup automatically. It scans for sources prefixed with 'VPE_' and maps them to effect types. You can also use the source mapper to assign existing sources manually.

VPE can switch scenes based on any event in your stream. Common triggers include: raids (switch to welcome scene), donations above a threshold (switch to celebration), extended silence (switch to BRB), and scheduled segments (switch to specific scene at a time).

Triggers are defined in policy files. Each rule specifies a condition ('when a raid happens') and an action ('switch to Raid Welcome scene'). Multiple rules can coexist — VPE's priority system ensures the most important one wins.

You can also trigger scene switches based on stream context. For example, if chat energy drops below a threshold for 3 minutes, VPE can switch to an engagement scene with polls or viewer interactions.

Beyond scene switching, VPE can show/hide individual sources, apply filters, and control source properties. This is how alerts, overlays, and notifications work.

Create sources in OBS with the 'VPE_' prefix (e.g., 'VPE_alert_overlay', 'VPE_donation_ticker'). VPE discovers these automatically and maps them to effect channels.

Effects have configurable duration and behavior. An overlay might show for 8 seconds then auto-hide. A ticker might stay visible until replaced by a higher-priority message. VPE manages all of this.

VPE supports custom transitions between scenes. Instead of a hard cut, you can assign stinger transitions that play a video (e.g., your branded transition animation) during scene switches.

Transitions are assigned per-trigger. A raid might use an energetic stinger, while a BRB switch uses a gentle fade. Configure these in the OBS connector plugin settings.

VPE respects OBS transition durations. It won't fire another scene switch while a transition is still playing — this prevents visual glitches and ensures smooth streaming.

VPE can mute/unmute audio sources, adjust volumes, and route sound effects to specific OBS audio channels. This is separate from your microphone and desktop audio.

Sound effects (SFX) queue by default — if multiple SFX trigger in quick succession, they play in order rather than cutting each other off. Up to 4 can queue.

Music effects replace the current track — new music swaps in seamlessly. This means VPE can dynamically change background music based on stream mood without overlapping tracks.

Not ready to let VPE control OBS live? Enable dry-run mode in the OBS connector settings. In this mode, VPE builds and logs all OBS commands without sending them.

Dry-run mode is perfect for testing new policies. You can see exactly what VPE would do in the terminal output, without any risk to your live stream.

Switch between dry-run and live mode at any time — even mid-stream. This is useful for gradually trusting VPE with more control as you see it make correct decisions.