Obs.NET 0.1.1

Obs.NET

A full-featured OBS Studio WebSocket v5 client library for .NET.

Features

• Modern async/await API for controlling OBS Studio
• 146 request types covering scenes, sources, filters, recording, streaming, and more
• 57 strongly-typed events for all OBS state changes
• Automatic reconnection with configurable retry logic
• SHA256 authentication support
• .NET 8.0, .NET 9.0, and .NET 10.0 support

Installation

dotnet add package Obs.NET

Or via the NuGet Package Manager:

Install-Package Obs.NET

Quick Start

using Obs.NET;

// Create client with default options (localhost:4455)
await using var client = new ObsWsClient();

// Or configure options
await using var client = new ObsWsClient(new ObsWsClientOptions
{
    Host = "localhost",
    Port = 4455,
    Password = "your-password"
});

// Connect to OBS
await client.ConnectAsync();

// Get current scene
var sceneList = await client.GetSceneListAsync();
Console.WriteLine($"Current scene: {sceneList?.CurrentProgramSceneName}");

// Switch scenes
await client.SetCurrentProgramSceneAsync("Scene 2");

// Start recording
await client.StartRecordAsync();

// Stop recording
var result = await client.StopRecordAsync();
Console.WriteLine($"Recording saved to: {result?.OutputPath}");

Examples

The Obs.NET.Example project contains runnable examples demonstrating various library features.

Running Examples

# List all available examples
dotnet run --project src/Obs.NET.Example -- --list-examples

# Run the simple example (beginner-friendly, minimal dependencies)
dotnet run --project src/Obs.NET.Example -- --example simple

# Run with connection options
dotnet run --project src/Obs.NET.Example -- --example simple --host 192.168.1.100 --password mypassword

Available Examples

See src/Obs.NET.Example/Examples.md for detailed documentation on running and creating examples.

Configuration Options

var options = new ObsWsClientOptions
{
    // Connection settings
    Host = "localhost",           // OBS WebSocket host
    Port = 4455,                  // OBS WebSocket port (default: 4455)
    Password = "your-password",   // Optional password for authentication

    // Timeout and retry settings
    RequestTimeout = TimeSpan.FromSeconds(30),   // Request timeout
    ReconnectDelay = TimeSpan.FromSeconds(5),    // Delay between reconnection attempts
    MaxReconnectAttempts = 5,                    // Max reconnection attempts

    // Event subscriptions (default: All)
    EventSubscriptions = EventSubscription.All
};

Event Handling

Subscribe to strongly-typed events:

// Scene changes
client.CurrentProgramSceneChangedEventReceived += async (e) =>
{
    Console.WriteLine($"Scene changed to: {e.SceneName}");
};

// Recording state
client.RecordStateChangedEventReceived += async (e) =>
{
    Console.WriteLine($"Recording state: {e.OutputState}");
};

// Stream state
client.StreamStateChangedEventReceived += async (e) =>
{
    Console.WriteLine($"Stream state: {e.OutputState}");
};

// Connection state
client.ConnectionStateChanged += async (state) =>
{
    Console.WriteLine($"Connection state: {state}");
};

Available Request Categories

Event Subscriptions

Control which events you receive to optimize performance:

var options = new ObsWsClientOptions
{
    // Subscribe to specific event categories
    EventSubscriptions = EventSubscription.Scenes | EventSubscription.Inputs
};

// Available subscriptions:
// - EventSubscription.None
// - EventSubscription.General
// - EventSubscription.Config
// - EventSubscription.Scenes
// - EventSubscription.Inputs
// - EventSubscription.Transitions
// - EventSubscription.Filters
// - EventSubscription.Outputs
// - EventSubscription.SceneItems
// - EventSubscription.MediaInputs
// - EventSubscription.Ui
// - EventSubscription.All (default)
// - EventSubscription.InputVolumeMeters (high volume)
// - EventSubscription.InputActiveStateChanged (high volume)
// - EventSubscription.InputShowStateChanged (high volume)

Connection States

public enum ConnectionState
{
    Disconnected,    // Not connected
    Connecting,      // Connection in progress
    Connected,       // WebSocket connected, not yet authenticated
    Authenticated    // Fully connected and authenticated
}

Requirements

• .NET 8.0, .NET 9.0, or .NET 10.0
• OBS Studio 28.0+ with obs-websocket 5.0+

OBS WebSocket Setup

1. Open OBS Studio
2. Go to Tools > WebSocket Server Settings
3. Enable the WebSocket server
4. (Optional) Set a password for authentication
5. Note the port number (default: 4455)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

See THIRD-PARTY-NOTICES.md for attribution of third-party materials.

Acknowledgments

• OBS Project for OBS Studio
• obs-websocket for the WebSocket API