obs-ss-plugin-webui/docs/OBS_SETUP.md

OBS Source Switcher Setup Guide

This document explains how to configure OBS Studio to work with the Source Switcher Plugin UI.

Prerequisites

1. OBS Studio installed
2. OBS WebSocket plugin (usually included with OBS 28+)
3. OBS Source Switcher plugin installed

Required Source Switcher Names

You must create exactly 7 Source Switcher sources in OBS with these specific names:

Source Switcher Name	Screen Position	Text File
ss_large	Main/Large screen	large.txt
ss_left	Left screen	left.txt
ss_right	Right screen	right.txt
ss_top_left	Top left corner	topLeft.txt
ss_top_right	Top right corner	topRight.txt
ss_bottom_left	Bottom left corner	bottomLeft.txt
ss_bottom_right	Bottom right corner	bottomRight.txt

Setup Instructions

1. Configure OBS WebSocket

1. In OBS, go to Tools → WebSocket Server Settings
2. Enable the WebSocket server
3. Set a port (default: 4455)
4. Optionally set a password
5. Note these settings for your .env.local file

2. Create Source Switcher Sources

For each screen position:

1. In OBS, click the + button in Sources
2. Select Source Switcher
3. Name it exactly as shown in the table above (e.g., ss_large)
4. Configure the Source Switcher:
   • Mode: Text File
   • File Path: Point to the corresponding text file in your files directory
   • Switch Behavior: Choose your preferred transition

3. Configure Text File Monitoring

Each Source Switcher should monitor its corresponding text file:

• ss_large → monitors {FILE_DIRECTORY}/large.txt
• ss_left → monitors {FILE_DIRECTORY}/left.txt
• etc.

Where {FILE_DIRECTORY} is the path configured in your .env.local file (default: ./files)

4. Add Browser Sources

When you add streams through the UI, browser sources are automatically created in OBS with these settings:

• Width: 1600px
• Height: 900px
• Audio: Controlled via OBS (muted by default)

How It Works

1. Stream Selection: When you select a stream for a screen position in the UI
2. File Update: The app writes the OBS source name to the corresponding text file
3. Source Switch: The Source Switcher detects the file change and switches to that source
4. Group Organization: Streams are organized into OBS groups based on their teams

Troubleshooting

Source Switcher not switching

• Verify the text file path is correct
• Check that the file is being updated (manually open the .txt file)
• Ensure Source Switcher is set to "Text File" mode

Sources not appearing

• Check OBS WebSocket connection in the footer
• Verify WebSocket credentials in .env.local
• Ensure the source name doesn't already exist in OBS

Missing screen positions

• Verify all 7 Source Switchers are created with exact names
• Check for typos in source names (they must match exactly)

Environment Variables

Configure these in your .env.local file:

# OBS WebSocket Settings
OBS_WEBSOCKET_HOST=127.0.0.1
OBS_WEBSOCKET_PORT=4455
OBS_WEBSOCKET_PASSWORD=your_password_here

# File Directory (where text files are stored)
FILE_DIRECTORY=./files