# Pi OBS Controls Skill Package

[![pi-package](https://img.shields.io/badge/pi--package-ready-brightgreen)](https://pi.dev/packages)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

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:

```bash
# 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:
```bash
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:

```ini
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:

```python
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](LICENSE).