Metadata-Version: 2.4
Name: dcc-mcp-obs
Version: 1.2.0
Summary: Native OBS Studio control for the DCC-MCP ecosystem
Author-email: Long Hao <hal.long@outlook.com>
License: GPL-2.0-or-later
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: dcc-mcp-core<1.0.0,>=0.20.14
Requires-Dist: psutil<8,>=5.9
Requires-Dist: websocket-client<2,>=1.8
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: jsonschema<5,>=4.23; extra == 'dev'
Requires-Dist: pytest-cov<7,>=5; extra == 'dev'
Requires-Dist: pytest<9,>=8; extra == 'dev'
Requires-Dist: pyyaml<7,>=6; extra == 'dev'
Requires-Dist: ruff<1,>=0.12; extra == 'dev'
Requires-Dist: tomli<3,>=2; (python_version < '3.11') and extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Requires-Dist: websockets<16,>=15; extra == 'dev'
Description-Content-Type: text/markdown

# dcc-mcp-obs

Native, typed OBS Studio control for the DCC-MCP ecosystem.

This product is an OBS plugin plus a DCC-MCP sidecar. The C++ plugin runs
inside the exact OBS process, owns host lifecycle and UI-thread dispatch, and
registers bounded vendor requests through the official OBS WebSocket 5.x API.
The out-of-process sidecar exposes those contracts through MCP, the Gateway,
an Install SOP v1 CLI, and a bundled Agent skill. Release standalone bundles
carry a private Python runtime; they do not require a system Python install.

OBS WebSocket is the authenticated transport. It is not used as an
unrestricted request escape hatch, and this product exposes no arbitrary
script or raw WebSocket tool.

## First slice

- Exact native plugin, OBS version, PID, instance ID, readiness, and event sequence
- Bounded scene discovery and current-scene readback
- Bounded source discovery for the current or an exact named scene
- Typed scene switching, scene-item CRUD, transitions, and Studio Mode
- Exact Windows PID/HWND window-capture source creation and readback
  preview/program operations with verified readback
- A built-in privacy-safe Agent keyboard/mouse activity overlay source
- A native top-level `DCC MCP` menu for status, overlay setup, Gateway Admin,
  and plugin information
- Recording status
- Start, stop, pause, and resume recording
- Typed streaming, replay-buffer, virtual-camera, and named-output controls
- Reviewed source/input/property/filter contracts plus exact audio and media controls
- A separate typed status readback after every mutation
- Stable redacted errors, bounded UI dispatch, and exact-instance drift rejection

The machine-readable [capability matrix](contracts/obs-capabilities-v1.json)
tracks delivered and remaining product domains. Operations are represented as
shipped tools only after their typed contracts land.

## Delivered control surfaces

- [Streaming, replay buffer, virtual camera, and typed output controls](https://github.com/dcc-mcp/dcc-mcp-obs/issues/2)
- [Inputs, properties, filters, audio, and media](docs/typed-source-controls.md)
- [Typed scene graph controls](docs/scene-graph.md)
- [Exact Windows window capture](docs/window-capture.md)
- [Built-in Agent input overlay](docs/agent-input-overlay.md)

## Full-control roadmap

- [Profiles, scene collections, bounded hotkeys, screenshots, and operator status](https://github.com/dcc-mcp/dcc-mcp-obs/issues/3)
- [Disposable real-OBS acceptance](docs/real-obs-acceptance.md)

## Requirements

- OBS Studio 28 or newer with OBS WebSocket 5.x enabled
- A matching Windows, macOS, or Linux standalone release bundle

Python 3.10+ and `dcc-mcp-core>=0.20.14,<1.0.0` are required only for the
optional PyPI/source installation path. pip resolves Core automatically.

## Install

Download and extract the matching `*-standalone` archive from the GitHub
Release. It contains the sidecar, its private runtime, and the exact native
plugin bundle. Close OBS, then run:

```console
dcc-mcp-obs.exe install-bundled
dcc-mcp-obs.exe --host-pid <obs-pid>
```

On macOS and Linux, use `./dcc-mcp-obs` instead of the `.exe` name. For
developers and users who intentionally prefer the Python package, the existing
installation path remains supported:

```console
python -m pip install dcc-mcp-obs
dcc-mcp-obs-install install \
  --plugin-archive dcc-mcp-obs-plugin.zip \
  --sha256 <release-sha256>
dcc-mcp-obs-install verify
```

Both installer paths emit one Install SOP v1 JSON object. `--dry-run` performs bundle
and ownership preflight without changing the OBS plugin directory. See
[installation details](docs/install.md).

On POSIX systems, a successful filesystem result is a synchronous point-in-time
verification, not a persistent namespace or writer lock. The report publishes
`POSIX_REVERIFY_BEFORE_USE` in `next_steps`; re-run `status` or `verify`
immediately before relying on the files.

## Password and endpoint

Configure the OBS WebSocket password in the operator-owned environment:

```console
set DCC_MCP_OBS_WEBSOCKET_PASSWORD=your-password
```

The first release accepts only `ws://127.0.0.1:<port>` and defaults to port
4455. A password is never returned in tool results, receipts, public errors, or
logs. Use `DCC_MCP_OBS_WEBSOCKET_URL` only to select another loopback port.

Run the sidecar against one exact OBS process. Use the standalone executable
shown above, or this command for a PyPI installation:

```console
dcc-mcp-obs --host-pid <obs-pid>
```

## Agent discovery

The bundled `obs-control` skill includes English and Chinese discovery aliases
for OBS, Open Broadcaster Software, recording, streaming, replay buffer,
virtual camera, outputs, scene/source inspection, pause, resume, 录屏, 直播,
回放缓冲, 虚拟摄像头, 场景图, 场景切换, 按键展示, 键盘, 鼠标, 转场, and
Studio Mode, properties, filters, audio, and media. Agents search
and load the skill before calling the typed tools. Scene-graph mutations are
available only through the native typed contract and require verified
postconditions.

Generic input settings are never forwarded. The public reviewed settings
contract is version `1.0`: `color_source_v3` exposes only bounded `width`,
`height`, and `color`, while `gain_filter` exposes only bounded `db`. Source,
filter, audio, and media mutations use exact names and bounded reconciliation.
See [typed source controls](docs/typed-source-controls.md).

For recorded Agent demonstrations, `create_agent_input_overlay` attaches a
built-in input source to each selected scene. Use a distinct source name per
simultaneously operating Agent, then `set_agent_input_overlay_layout` can choose
one of eight edge anchors plus bounded opacity and margin after inspecting the
game frame. `emit_agent_input_activity` displays the Agent identity and only an
allowlisted shortcut, mouse button, wheel direction, or typing count. It never
captures global input or accepts arbitrary text. See the
[Agent input overlay contract](docs/agent-input-overlay.md).

`start_scene_recordings` atomically starts one video-only MP4 per exact game
scene. Each output uses the single enabled `window_capture` source's native
width and height, includes that scene's Agent input overlay, and is named
`<game> <yyyy-MM-dd HH-mm-ss>.mp4` in the current OBS profile recording
directory. Supply only game scenes; editor and VS Code scenes are not part of
the recording plan. The typed session readback exposes exact dimensions,
paths, activity, byte/frame counters, and errors for every output.

The native plugin adds a top-level `DCC MCP` menu to OBS. `Server Status...`
shows the exact plugin and OBS versions, bridge readiness, active outputs, and
current scene. `Add Agent Input Overlay` attaches the shared built-in source to
the current scene. `Open Gateway Admin` opens only the loopback Gateway URL
(`127.0.0.1`, port 9765 by default or a valid `DCC_MCP_GATEWAY_PORT`). The menu
is registered idempotently on OBS's UI thread and removed during plugin unload.

Use `request_graceful_shutdown` instead of terminating the OBS process. The
native plugin refuses the request while recording, streaming, replay buffer,
or virtual camera output is active, returns a terminal queued acknowledgement,
and then asks the OBS frontend to exit normally. Callers verify process and
plugin-instance disappearance outside the closed connection.

OBS control is native-plugin/WebSocket first. Unsupported visual-only actions
may use DCC-MCP `ui-control` with project-owned DCC-CUA only after exact PID
and HWND binding, a fresh snapshot, and post-action readback. There is no
generic Computer Use fallback.

## Development

```console
python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check .
python -m ruff format --check .
dcc-mcp-cli lint src/dcc_mcp_obs/skills/obs-control --warnings-as-errors
```

The native build uses the official OBS plugin template toolchain and OBS
31.1.1 SDK inputs pinned with SHA-256 hashes:

```console
cmake --preset windows-x64
cmake --build --preset windows-ci-x64
```

Equivalent CI builds run on Windows, macOS, and Linux.

## Validation boundary

Unit tests, adversarial fake protocol sessions, native compilation, and package
smoke tests remain separate from host acceptance. The disposable real-OBS gate
launches the packaged plugin and installed wheel on Windows, macOS, and Linux,
verifies exact process/session binding and state readback, and publishes only
privacy-safe evidence. See [the acceptance contract](docs/real-obs-acceptance.md).

## License

GPL-2.0-or-later. The native module links to OBS Studio and vendors the official
OBS WebSocket plugin API header with its original notice.
