Advanced OBS Studio Automation Suite

An Interactive Guide to the Lua Script & Control Dock

VDO.Ninja OBS Control Dock (Modified)

This is a modified version of the OBS Control Dock by Steve Seguin (creator of VDO.Ninja). It's a web-based interface for managing VDO.Ninja sources in OBS Studio via the OBS WebSocket plugin, enhanced to integrate seamlessly with the Advanced Scene Layouts Lua script.

Original OBS Controller: https://vdo.ninja/obs

Steve Seguin's GitHub: https://github.com/steveseguin

Key Features

VDO.Ninja Room Integration

Connect to your VDO.Ninja room to see and manage all active participants.

Dynamic Source Management

Automatically add, remove, and rename VDO.Ninja sources in your OBS scenes.

Screen Share Integration

Dedicated feature to manage VDO.Ninja screen shares. It creates sources with a "Reaction" prefix for the Lua script's Reaction Layout.

Highlight Source Management

Ability to "Highlight" a VDO.Ninja participant, renaming their source with a "Highlight" prefix to trigger the Lua script's Highlight Layout.

Stream Mapping

Advanced rules to automatically route specific streams (by Stream ID or Label) to different OBS scenes.

Installation and Setup

  1. Choose how to access the page:
    • Local Option: Download obs.html and copy the file path.
    • Hosted Option: Copy the URL https://morsethecode.github.io/OBS-Scripts/obs instead of downloading the file.
  2. Add as an OBS Dock:
    • In OBS: DocksCustom Browser Docks....
    • Choose Dock Name(e.g., "VDO.Ninja Control").
    • Choose URL (Can be the URL or the downloaded file path).
    • Click Apply, then Close.
    • Position the new dock.
  3. Configure the Dock:
    • OBS WebSocket: Enter URL (default ws://localhost:4455) and password. Click Connect.
    • Prefixes: Set Camera Prefix, Reaction Prefix, and Highlight Prefix.
    • VDO.Ninja: Enter room name and password (if any). Click Connect.
    • Target Scenes: Select main target scene, other scenes the sources will be copied to, and scenes exclusive for Highlights/Screen Shares.

Advanced Scene Layouts Lua Script

This robust Lua script offers a powerful set of tools to dynamically manage and organize your scenes within OBS Studio. It integrates three core functionalities: Grid Layout, Reaction Layout, and Highlight Layout, all with multi-language support to ensure an accessible and intuitive user experience. This section will guide you through its features and setup.

Key Features

Dynamic Grid Layout

Organizes multiple video sources into a customizable grid, perfect for multi-participant streams or varied content displays.

  • Flexible Settings: Adjust spacing, margins, and X/Y offsets.
  • Split-Screen Mode: Optimizes view for two cameras (e.g., interviews).

Visual Example (2x2 Grid):

Cam 1
Cam 2
Cam 3
Cam 4

Immersive Reaction Layout

Creates engaging reaction layouts with cameras positioned relative to a main content window (e.g., a window capture).

  • Camera Distribution: Place cameras on one side or symmetrically on both.
  • Custom Positioning: Control spacing and offsets.
  • Dedicated Prefixes: For reaction cameras and main content.

Visual Example (Cameras Left):

Cam 1
Cam 2
Main Content (e.g., Gameplay)

Visual Example (Cameras on Both Sides):

Cam 1
Main Content (e.g., Gameplay)
Cam 2

Dynamic Highlight Layout

Features a specific main source (e.g., primary speaker) in a larger frame, with other cameras arranged around it. Promotes a browser source to the main area.

  • Camera Distribution: Secondary cameras on one or both sides.
  • Fine Adjustments: Control spacing and X/Y offsets.

Visual Example (Highlight Center, Cameras on Sides):

Cam A
Cam B
Highlighted Speaker
Cam C
Cam D

Visual Example (Highlight Right, Cameras on Left):

Cam A
Cam B
Cam C
Cam D
Highlighted Speaker

Multi-Language Support

The user interface is available in English, Portuguese, Spanish, Chinese, Russian, Japanese, and German for broader accessibility.

Installation and Configuration

  1. Save the Script: Download the Advanced Scene Layouts.lua file.
  2. Open OBS Studio: Launch OBS.
  3. Add the Script:
    • Go to ToolsScripts.
    • Click the "+" button (bottom left).
    • Navigate to and select the downloaded .lua file.
  4. Configure the Script:
    • Select the script from the list to show its properties on the right.
    • Enable Layouts: Check boxes for Grid, Reaction, and/or Highlight layouts.
    • Assign Scenes: Select the target OBS scene for each enabled layout.
    • Set Prefixes: Define the General Camera Prefix, Highlight Main Source Prefix and Reacted Content Prefix (must be the same ones defined in the Control Dock)
    • Adjust & Customize: Use sliders for spacing, margins, and offsets.

Integrated Workflow

When used together, the Control Dock and the Lua script create a highly automated streaming environment. The Dock handles VDO.Ninja connections and OBS source management, while the Lua script takes care of the visual arrangement within your OBS scenes. This synergy allows for dynamic and professional-looking productions with minimal manual intervention.

How They Integrate

The core of the integration lies in source name prefixes.

  1. The Control Dock adds new VDO.Ninja participants to OBS. It assigns a base Camera Prefix to their source names (e.g., VDO_streamID123).
  2. When you use a feature like "Highlight" in the Control Dock, it renames the specific participant's source in OBS to use the configured Highlight Prefix (e.g., VDO.Highlight_streamID123). Similarly for screen shares using the "Reaction" prefix.
  3. The Lua Script, running in the background within OBS, constantly monitors the source names in your managed scene(s). When it detects a source name that matches one of its configured prefixes (Camera, Reaction, or Highlight), it automatically applies the corresponding layout rules, dynamically arranging the sources.

Key Takeaway: Consistent prefix configuration between the Control Dock and the Lua Script is essential for the automation to work correctly.

Example Workflow: Using the Highlight Feature

  1. Configuration:
    • In the Control Dock: Set Camera Prefix to VDO and Highlight prefix to Highlight.
    • In the Lua Script: Enable "Highlight Layout". Set "Highlight Scene" to the same Highlight Scene configured in the Control Dock. Set "Highlight Camera Prefix" to VDO and "Highlight Main Source Prefix" to VDO.Highlight.

    Note: The Dock prepends the camera prefix to the highlight prefix, so if you set VDO as Camera Prefix and Highlight as Highlight prefix, VDO.Highlight is the actual main source prefix that must be used in the Lua Script.

  2. In Action:
    • Multiple guests join your VDO.Ninja room. The Dock adds them to OBS as VDO_guest1, VDO_guest2, etc. The Lua script, not seeing a "main" highlighted source yet, arranges them using the Grid Layout settings by default in the target Highlight scene.
    • You decide to feature Guest 2. In the Control Dock's "Active Streams" list, click the Highlight button for Guest 2.
    • The Dock renames Guest 2's source in OBS from VDO_guest2 to VDO.Highlight_guest2 and triggers a transition to the target Highlight scene in OBS if you're not in it.
    • The Lua script detects the VDO.Highlight_ prefix. It immediately applies the Highlight Layout: VDO.Highlight_guest2 becomes the large, featured source, and other sources like VDO_guest1 are arranged as smaller cameras.
    • Clicking "Unhighlight" in the Dock reverses the renaming. The Lua script then reverts to the Grid Layout.