Pi OBS Controls Skill Package

A complete, feature-rich skill package for Pi to control OBS Studio programmatically via WebSocket v5+.

This package enables Pi to manage scenes, control streaming/recording, toggle virtual cameras, adjust audio volumes, change source visibilities, capture screenshots, apply filters, and much more.

🚀 Features

• Scene Management: List, switch, create, and remove scenes.
• Recording & Streaming: Start, stop, pause, and resume. Retrieve stream/recording health and status.
• Audio Controls: Mute/unmute and adjust volumes (in decibels) for microhpones and media inputs.
• Source Management: Locate scene items, toggle visibility, add new inputs, and auto-fit/resize sources to canvas.
• Filters & Transitions: List and manage source filters, switch transitions, and set transition durations.
• Studio Mode: Toggle Studio Mode, set preview scenes, and trigger transitions.
• Replay Buffer & Screenshots: Save replay buffers, and take/save high-quality screenshots from any source.
• Custom Python SDK: Under the hood, this uses a robust, asynchronous Python client built on top of websockets.

📦 Installation

To install this package in your Pi environment, run:

# Install via npm (recommended)
pi install npm:@nukman-salim/pi-obs-controls

# Or install directly from Git
pi install git:github.com/YOUR_USERNAME/pi-obs-controls

⚙️ Setup & Prerequisites

1. Enable OBS WebSocket

1. Open OBS Studio.
2. Go to Tools ➔ WebSocket Server Settings.
3. Check Enable WebSocket Server.
4. Take note of the Server Port (default: 4455) and the Server Password.

2. Install Python Dependencies

The skill requires the websockets Python library:

pip install websockets

3. Add Credentials

Create a .env file in the directory where you run Pi (or your skill execution environment) with your OBS WebSocket credentials:

OBS_HOST=localhost
OBS_PORT=4455
OBS_PASSWORD=your_secure_password

🛠️ Usage with Pi

Once installed, your Pi coding agent will automatically register the obs-controls skill. You can command Pi using natural language:

• "Switch my active scene in OBS to 'Main Camera'."
• "Start recording and toggle my microphone off."
• "Show me the list of all current audio inputs and their volumes."
• "Fit the 'Webcam' source in scene 'Gaming' to a 1920x1080 canvas."
• "Take a screenshot of the OBS 'Game Capture' source and save it."

🐍 Standalone Python Usage

You can also import and use the underlying client directly in your own Python projects:

import asyncio
from skills.obs_controls.obs_controls import OBSWebSocketClient

async def main():
    # Initializes using environment variables (OBS_HOST, OBS_PORT, OBS_PASSWORD)
    client = OBSWebSocketClient()
    
    await client.connect()
    
    # Switch scene and start recording
    await client.set_current_scene("Main")
    await client.start_recording()
    
    # Check status
    status = await client.get_full_status()
    print(f"Active Scene: {status['current_scene']}")
    
    # Toggle mic mute
    await client.toggle_input_mute("Microphone")
    
    await client.disconnect()

if __name__ == "__main__":
    asyncio.run(main())

📂 API Reference (Summary of Key Helpers)

Scene & Source Control

• set_current_scene(name) / get_scene_list()
• set_source_visibility(scene, source_name, visible: bool)
• fit_source_to_canvas(scene, source, width, height)
• resize_source_percent(scene, source, percent)

Recording & Streaming

• start_recording() / stop_recording() / pause_recording() / resume_recording()
• start_streaming() / stop_streaming() / toggle_streaming()
• start_virtual_cam() / stop_virtual_cam() / toggle_virtual_cam()

Audio Control

• set_input_mute(name, mute: bool) / toggle_input_mute(name)
• set_input_volume(name, db) (e.g. -10.0 dB)

Screenshots

• save_source_screenshot(source, file_path, format="png", width=1920, height=1080)

📄 License

This package is open source and available under the MIT License.