OBS Polyemesis User Guide

Control Datarhei Restreamer directly from OBS Studio

What is OBS Polyemesis?
Architecture Overview
Installation
Quick Start
Configuration
Usage
Troubleshooting
FAQ

What is OBS Polyemesis?

OBS Polyemesis is a plugin that integrates Datarhei Restreamer control into OBS Studio, allowing you to:

✅ Start/stop Restreamer streams directly from OBS
✅ Monitor stream status in real-time
✅ Control multiple Restreamer instances
✅ Manage multistreaming configurations
✅ View stream health and statistics

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                         OBS Studio                               │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                  OBS Polyemesis Plugin                     │  │
│  │                                                            │  │
│  │  ┌──────────────┐  ┌───────────────┐  ┌──────────────┐  │  │
│  │  │   UI Dock    │  │  Config       │  │  API Client  │  │  │
│  │  │  (Qt/C++)    │◄─┤  Manager      │◄─┤   (REST)     │  │  │
│  │  │              │  │   (C)         │  │    (C)       │  │  │
│  │  └──────┬───────┘  └───────────────┘  └──────┬───────┘  │  │
│  │         │                                      │          │  │
│  └─────────┼──────────────────────────────────────┼──────────┘  │
│            │                                      │             │
└────────────┼──────────────────────────────────────┼─────────────┘
             │                                      │
             │         User Interactions            │ HTTPS/REST
             ▼                                      ▼
        ┌────────┐                        ┌──────────────────┐
        │  User  │                        │   Restreamer     │
        └────────┘                        │   HTTP API       │
                                          │  (Port 8080)     │
                                          └────────┬─────────┘
                                                   │
                                          ┌────────▼─────────┐
                                          │   Restreamer     │
                                          │   Streaming      │
                                          │    Engine        │
                                          └──────────────────┘
                                                   │
                                          ┌────────▼─────────┐
                                          │  YouTube/Twitch  │
                                          │  Other Platforms │
                                          └──────────────────┘

Component Flow

User Action → UI Dock → Config Manager → API Client → Restreamer API
                ▲                                            │
                │                                            │
                └────────────── Response ◄───────────────────┘

Installation

Prerequisites

OBS Studio 28.0 or newer
Operating System:
- Ubuntu 22.04+ / Debian 11+
- macOS 12+ (Intel or Apple Silicon)
- Windows 10/11 (64-bit)
Datarhei Restreamer instance (local or remote)

Option 1: Install from Release (Recommended)

Download the plugin:
- Go to Releases
- Download the appropriate package for your OS:
  - Linux: obs-polyemesis-X.Y.Z-linux-x86_64.tar.gz
  - macOS: obs-polyemesis-X.Y.Z-macos.pkg
  - Windows: obs-polyemesis-X.Y.Z-windows-x64.zip

Install the plugin:

Linux (Ubuntu/Debian):

tar -xzf obs-polyemesis-*-linux-x86_64.tar.gz
sudo cp -r obs-polyemesis /usr/lib/obs-plugins/
sudo cp -r data/* /usr/share/obs/obs-plugins/obs-polyemesis/

macOS:

# Double-click the .pkg file and follow the installer
# Or via terminal:
sudo installer -pkg obs-polyemesis-*.pkg -target /

Windows:

1. Extract the ZIP file
2. Copy the contents to: C:\Program Files\obs-studio\
3. Merge folders when prompted

Restart OBS Studio

Option 2: Build from Source

See BUILDING.md for detailed build instructions.

Quick Start

1. Set Up Restreamer

If you don't have Restreamer running:

# Using Docker
docker run -d \
  --name restreamer \
  -p 8080:8080 \
  -p 8181:8181 \
  -p 1935:1935 \
  datarhei/restreamer:latest

Access Restreamer at: http://localhost:8080

2. Configure OBS Polyemesis

Open OBS Studio
Find the Restreamer Control Dock:
- Menu: Docks → Restreamer Control
- The dock will appear in your OBS layout

Connect to Restreamer:

┌─────────────────────────────────────────┐
│      Restreamer Connection Setup        │
├─────────────────────────────────────────┤
│                                         │
│  URL:  http://localhost:8080           │
│                                         │
│  API Key: [your-api-key-here]         │
│                                         │
│  [Test Connection]  [Save]             │
│                                         │
└─────────────────────────────────────────┘

Get Your API Key:
- Go to Restreamer web interface
- Navigate to: Settings → API
- Copy the API key
- Paste it into OBS Polyemesis

3. Start Streaming

Configure Your Stream in Restreamer:
- Add your streaming platforms (YouTube, Twitch, etc.)
- Set up video/audio sources
- Save the configuration

Control from OBS:

┌─────────────────────────────────────────┐
│        Restreamer Control Panel         │
├─────────────────────────────────────────┤
│                                         │
│  Status: ● Connected                   │
│                                         │
│  Active Streams:                       │
│  ┌─────────────────────────────────┐  │
│  │ ▶ YouTube - Main Channel        │  │
│  │   ● Live (00:45:23)             │  │
│  ├─────────────────────────────────┤  │
│  │ ▶ Twitch - Gaming               │  │
│  │   ● Live (00:45:23)             │  │
│  └─────────────────────────────────┘  │
│                                         │
│  [Start All] [Stop All] [Refresh]     │
│                                         │
└─────────────────────────────────────────┘

Click "Start All" to begin streaming to all platforms

Configuration

Connection Settings

The plugin stores configuration in:

Linux: ~/.config/obs-studio/plugin_config/obs-polyemesis/config.json
macOS: ~/Library/Application Support/obs-studio/plugin_config/obs-polyemesis/config.json
Windows: %APPDATA%\obs-studio\plugin_config\obs-polyemesis\config.json

Example configuration:

{
  "restreamer_url": "http://localhost:8080",
  "api_key": "your-api-key-here",
  "auto_connect": true,
  "poll_interval_ms": 2000,
  "timeout_ms": 5000
}

Configuration Options

Option	Description	Default
`restreamer_url`	Restreamer API URL	`http://localhost:8080`
`api_key`	Authentication key	Required
`auto_connect`	Connect on OBS startup	`true`
`poll_interval_ms`	Status update frequency	`2000` (2 seconds)
`timeout_ms`	API request timeout	`5000` (5 seconds)

Multi-Instance Setup

You can control multiple Restreamer instances:

┌────────────────────────────────────────────────────┐
│  Instance 1: Production (http://prod:8080)         │
│  Status: ● Connected                              │
│  Streams: YouTube, Twitch, Facebook               │
├────────────────────────────────────────────────────┤
│  Instance 2: Backup (http://backup:8080)          │
│  Status: ● Connected                              │
│  Streams: YouTube (backup), Twitch (backup)       │
└────────────────────────────────────────────────────┘

Usage

Stream Control Workflow

Start OBS Studio
       │
       ▼
Plugin Auto-Connects to Restreamer
       │
       ▼
View Stream Status in Dock
       │
       ├──► Start Individual Stream  ──► Stream Goes Live
       │
       ├──► Start All Streams  ──────► All Streams Go Live
       │
       ├──► Stop Stream  ──────────────► Stream Stops
       │
       └──► Monitor Status  ───────────► View Live Stats

Common Tasks

Start a Specific Stream

Click the stream in the list
Click ▶ Start button
Monitor status indicator

Stop All Streams

Click Stop All button
Confirm in dialog
All streams stop simultaneously

Monitor Stream Health

The dock shows real-time status:

● Green  = Stream is live and healthy
● Yellow = Stream is starting/buffering
● Red    = Stream error or stopped
● Gray   = Disconnected from Restreamer

Troubleshooting

Connection Issues

Problem: Cannot connect to Restreamer

Solutions:

Verify Restreamer is running:

curl http://localhost:8080/api/v3/config

Check firewall settings:

# Linux
sudo ufw allow 8080/tcp

# macOS
# System Preferences → Security & Privacy → Firewall

Verify API key is correct
Check OBS logs:
- Linux: ~/.config/obs-studio/logs/
- macOS: ~/Library/Application Support/obs-studio/logs/
- Windows: %APPDATA%\obs-studio\logs\

Stream Won't Start

Problem: Stream fails to start from OBS

Solutions:

Verify stream is configured in Restreamer web interface
Check Restreamer logs:
```
docker logs restreamer
```
Test stream manually in Restreamer interface
Verify network connectivity to streaming platforms

Plugin Not Loading

Problem: Plugin doesn't appear in OBS

Solutions:

Verify installation path is correct
Check OBS version compatibility (28.0+)
Review OBS logs for errors
Reinstall the plugin

Performance Issues

Problem: OBS becomes slow with plugin enabled

Solutions:

Increase poll_interval_ms to reduce API calls:
```
{"poll_interval_ms": 5000}
```
Disable auto-connect if not needed
Update to latest plugin version

FAQ

Q: Does this replace OBS's built-in streaming?

A: No. This plugin controls Restreamer, which is a separate multistreaming service. OBS still handles your video capture and encoding.

Q: Can I use this with OBS Websocket?

A: Yes, they work independently.

Q: Does this work with Restreamer Core?

A: Yes, both Restreamer and Restreamer Core are supported.

Q: What's the latency impact?

A: Minimal. The plugin only controls Restreamer via API; it doesn't affect video encoding or transmission.

Q: Can I run Restreamer on a different machine?

A: Yes! Just update the restreamer_url to point to your Restreamer instance:

{"restreamer_url": "http://192.168.1.100:8080"}

Q: Is HTTPS supported?

A: Yes, use HTTPS URLs:

{"restreamer_url": "https://restreamer.example.com"}

Q: How do I update the plugin?

A: Download the latest release and reinstall. Your configuration is preserved.

Q: Where can I get help?

GitHub Issues - Bug reports
Discussions - Questions
Wiki - Advanced guides

Advanced Usage

Custom API Endpoints

The plugin uses these Restreamer API endpoints:

GET  /api/v3/config              - Get configuration
GET  /api/v3/process             - List streams
POST /api/v3/process/{id}/start  - Start stream
POST /api/v3/process/{id}/stop   - Stop stream
GET  /api/v3/process/{id}/state  - Get stream state

Logging

Enable debug logging:

Set environment variable before starting OBS:
```
export OBS_POLYEMESIS_DEBUG=1
obs
```
Check logs for detailed API communication

Performance Tuning

For high-load scenarios:

{
  "poll_interval_ms": 10000,
  "timeout_ms": 10000,
  "max_retries": 3,
  "connection_pool_size": 5
}

Getting Started Checklist

Next Steps

Read CONTRIBUTING.md to contribute
See BUILDING.md to build from source
Check CHANGELOG.md for updates
Visit Restreamer Documentation

Need help? Open an issue on GitHub

Uh oh!

FilesExpand file tree

USER_GUIDE.md

Latest commit

History

USER_GUIDE.md

File metadata and controls

OBS Polyemesis User Guide

Table of Contents

What is OBS Polyemesis?

Architecture Overview

Component Flow

Installation

Prerequisites

Option 1: Install from Release (Recommended)

Option 2: Build from Source

Quick Start

1. Set Up Restreamer

2. Configure OBS Polyemesis

3. Start Streaming

Configuration

Connection Settings

Configuration Options

Multi-Instance Setup

Usage

Stream Control Workflow

Common Tasks

Start a Specific Stream

Stop All Streams

Monitor Stream Health

Troubleshooting

Connection Issues

Stream Won't Start

Plugin Not Loading

Performance Issues

FAQ

Q: Does this replace OBS's built-in streaming?

Q: Can I use this with OBS Websocket?

Q: Does this work with Restreamer Core?

Q: What's the latency impact?

Q: Can I run Restreamer on a different machine?

Q: Is HTTPS supported?

Q: How do I update the plugin?

Q: Where can I get help?

Advanced Usage

Custom API Endpoints

Logging

Performance Tuning

Getting Started Checklist

Next Steps