OBS Studio 28+ ships obs-websocket v5 built in: a WebSocket server (default port 4455,
password-protected) that exposes almost everything the UI can do — scenes, inputs, scene
items, filters, transitions, outputs, media and UI state — as JSON requests. A job script
runs in a local Python process and talks to the running OBS through
scripts/obs_client.py, a standard-library-only v5 client: nothing
to pip install, nothing to load inside OBS. Everything here was run against OBS 32.2.2
with obs-websocket 5.7.4 (macOS). Check obsWebSocketVersion in the ping reply; on
another version, GetVersion → availableRequests is the source of truth.
- scripts/obs-run.sh — run a
.py(or-c 'inline');--pingchecks the connection,--statedumps scenes with items, inputs, outputs and settings. - scripts/obs-start.sh — launch OBS (optionally with
--collection/--profile/--scene) and wait for the websocket. - scripts/obs_collection.py — build a whole scene collection
from a compact spec and either
applyit live orinstallit as a file. - scripts/example-scene-setup.py — a complete build → verify job to copy the shape from.
The control loop
- Ping:
bash scripts/obs-run.sh --ping→{"ok": true, "obsVersion": "32.2.2", "obsWebSocketVersion": "5.7.4", …}. On{"ok": false, …}the error says which case you are in:- OBS not running →
bash scripts/obs-start.sh. - Connection refused while OBS runs → the server is off. Only the user can switch it on: Tools ▸ WebSocket Server Settings ▸ Enable WebSocket server (then OK/Apply). Never start a second OBS instance.
4009 authentication failed→ the password in the local config is not the one in use (e.g. OBS on another machine); ask for it and setOBS_PASSWORD. Never print it.
- OBS not running →
- Look before you build:
bash scripts/obs-run.sh --state— collection, profile, program scene, canvas size (video.baseWidth/Height— positions are in these pixels), every scene's items top-to-bottom, inputs, and record/stream/virtualcam/replay status. - Write a job into the scratchpad, from the cheatsheet and recipes.md.
- Run it:
OUT=/abs/outdir bash scripts/obs-run.sh /abs/job.py --arg scene=Main. Output streams back; a failed request raisesObsRequestErrorwith its status code and OBS's comment, and the run exits 1. Parameters arrive as strings inARGS;OUTis where screenshots go. - Verify (below), then iterate. The
ensure_*helpers create-or-update, so a job can simply be re-run after a fix.
Reference routing
| Task | Read |
|---|---|
| A worked pattern: stream layout, lower third, webcam, recording with chapters, replay buffer, audio, media, transitions, hotkeys, Advanced Scene Switcher | recipes.md |
| Request names, fields, status codes, events, input/filter kinds and their settings | api-reference.md |
| Several scenes at once, a reusable layout, a collection file | scene-collection.md |
Injected namespace
obs (a connected ObsClient), OUT, ARGS, ObsRequestError, obs_color, and these
bound methods as bare functions:
| Helper | Does |
|---|---|
call(type, **fields) |
one request → its responseData dict; raises on failure |
try_call(type, **fields) |
same, but None on failure (existence checks) |
batch([(type, {fields}), …], halt_on_failure=, execution_type=, raise_on_error=) |
many requests, one round trip |
wait_event(type, timeout, match=lambda d: …) |
block for an event (buffered events count) |
screenshot(source, path, width=) |
scene or input → PNG/JPG file here; waits a few frames first |
ensure_scene(name) |
create unless it exists |
ensure_input(scene, name, kind, settings) |
create, or update settings (and add to the scene) → sceneItemId |
ensure_filter(source, name, kind, settings) |
create, or update and re-enable |
set_transform(scene, source, **fields) |
positionX/Y, scaleX/Y, rotation, alignment, bounds*, crop* |
item_id(scene, source), scene_names(), input_names(kind=None) |
lookups |
input_kind(*candidates) |
first kind this OBS build supports |
text_settings(kind, text, size=, color=, face=) |
text-source settings for FreeType (macOS/Linux) or GDI+ (Windows) |
obs_color("#RRGGBB[AA]") |
the ABGR integer every OBS color setting expects |
Cheatsheet
W, H = (lambda v: (v["baseWidth"], v["baseHeight"]))(call("GetVideoSettings"))
ensure_scene("Main")
ensure_input("Main", "BG", "color_source_v3", {"color": obs_color("#0b1f3a"), "width": W, "height": H})
kind = input_kind("text_ft2_source_v2", "text_gdiplus_v3")
ensure_input("Main", "Title", kind, text_settings(kind, "Live now", size=72))
set_transform("Main", "Title", positionX=W / 2, positionY=80, alignment=4) # 4 = top-center
ensure_input("Main", "Logo", "image_source", {"file": "/abs/logo.png"})
set_transform("Main", "Logo", positionX=W - 40, positionY=40, alignment=6, scaleX=0.5, scaleY=0.5) # top-right
ensure_filter("Logo", "Fade", "color_filter_v2", {"opacity": 0.8})
call("SetCurrentProgramScene", sceneName="Main")
screenshot("Main", f"{OUT}/main.png", width=960)
- Alignment is a bitmask for the item's anchor point: left 1, right 2, top 4, bottom 8,
center 0 — top-left 5, bottom-left 9, bottom-right 10, top-right 6.
positionX/Yplaces that anchor in canvas pixels. - Stacking: new items go on top.
SetSceneItemIndexwith0= bottom,len(items) - 1= top.GetSceneItemListreturns bottom-to-top;GetSceneListreturns scenes in reverse Scenes-dock order, and that dock order cannot be changed remotely. - Fit to a box:
boundsType="OBS_BOUNDS_SCALE_INNER", boundsWidth=…, boundsHeight=…instead of computing scale. - Outputs:
StartRecord/StopRecord(returnsoutputPath),PauseRecord,CreateRecordChapter,StartReplayBuffer/SaveReplayBuffer,StartVirtualCam,SetInputMute,SetInputVolume(inputVolumeDb=…). Wait onRecordStateChangedrather than sleeping — the start is asynchronous.
Verification
- Look at it:
screenshot(scene, path, width=960)and Read the PNG. Screenshot the scene, not the program output — it works for scenes that aren't live. A transparent region in a nested scene shows as white or checkered in the PNG; that is alpha, not a bug. - Read the state back:
--state,GetSceneItemList,GetInputSettings,GetSourceFilterList. A successful call is not proof — settings merge (overlay=True) and a typo'd settings key is accepted silently. - Recordings: take the path from
StopRecord, then check it withffprobe.
Gotchas
- Names are global and case-sensitive. An input belongs to every scene it is added to;
creating a second input with an existing name fails with 601. Prefix names per layout
(
"Stream · Title") and useensure_*or check withinput_names()first. A wrong name → 600. - Kinds differ per platform: text is
text_ft2_source_v2on macOS/Linux andtext_gdiplus_v3on Windows; capture kinds arescreen_capture/macos-avcaptureon macOS,monitor_capture/dshow_inputon Windows. Ask withinput_kind()orGetInputKindList; get the settings withGetInputDefaultSettings. - Removals are deferred: after
RemoveScene/RemoveInputthe name can still be listed for a moment (and re-creating it fails with 601). Re-read after a short pause before verifying or reusing the name. - Colors are ABGR integers (
0xAABBGGRR), not#RRGGBB— always go throughobs_color. color_filter_v2works in linear light: evenbrightness: -0.05clips a dark source to black. Usesaturation,contrastoropacityfor gentle tweaks.- Screenshot right after a change can show the previous frame —
screenshot()waits 150 ms by default. Raisesettle=for browser sources and media, which take longer to load. A browser source that stays blank in the preview too is a CEF problem on that machine, not your settings (recipes.md). - Collection files: OBS reads the list only at startup and rewrites the open one from
memory, so never edit the open collection's JSON. When the user asks for a collection
(not just scenes) and OBS is running,
obs_collection.py apply spec.json --new-collectionis the install: it creates the collection, builds it, and OBS saves the file. Switching collections is harmless — the previous one stays intact and one click away — so do it rather than building into the open collection. Alsobuildthe file intoOUTas the deliverable. File-onlyinstallis for a closed OBS (scene-collection.md). - macOS capture needs permission: without Screen Recording (and Camera/Microphone) permission for OBS, capture sources render black. Only the user can grant it, in System Settings ▸ Privacy & Security.
- Localized UI: default scene/transition names follow the UI language ("Jelenet",
"Áttűnés" in Hungarian). Read the names from
--state; never assume "Scene" or "Fade".
Safety
- Streaming publishes. Never call
StartStream,StopStream,ToggleStreamorSetStreamServiceSettingswithout the user's explicit go-ahead in this conversation, and never readGetStreamServiceSettingsinto the output — it holds the stream key. - The open collection is the user's show. Build into new, prefixed scenes and inputs, and
ask before
RemoveScene,RemoveInput,RemoveSceneItem,RemoveSourceFilter, switching collection or profile, or changingSetVideoSettings/SetProfileParameter. SetCurrentProgramScenechanges what viewers see if the user is live — checkstream.outputActivein--statefirst, and in studio mode preferSetCurrentPreviewScene.- Recordings land in the user's recording folder: tell them the path, and delete only test files you made yourself.
Security
- obs-websocket gives any client that has the password full control of OBS, including starting a stream and reading the stream key. Keep authentication on; the server listens on every interface, so on a shared network the password is the only barrier.
- The client reads the password from OBS's own config
(
…/obs-studio/plugin_config/obs-websocket/config.json) whenOBS_PASSWORDis unset, and never prints it. Never paste it into output, job scripts or files. - Job scripts are ordinary Python running as the user. Keep them in the scratchpad.