Handles for addressing scenes, inputs, sources, scene items and filters

[Agash]

Draft. Verified against a live OBS 32.2.2 on both transports.

Addresses #19.

What it does

await client.Scene("Intro").SetCurrentProgramAsync(ct);          // a string is a name
await client.Scene(sceneGuid).SetNameAsync("Outro", ct);         // a Guid is a uuid
await client.Input("Mic").Filter("EQ").SetEnabledAsync(true, ct);

SceneOperations intro = await client.Scene("Intro").ResolveAsync(ct);
SceneItemOperations logo = await client.Scene("Intro").ItemAsync("Logo", cancellationToken: ct);

client.Scenes.CurrentProgramSceneChanged += (_, e) => Act(e.EventData.Scene);   // already a uuid

Why a handle is the accurate type

From Request::AcquireSource upstream: a uuid wins outright, a name is read only when no uuid was sent, canvasUuid is consulted only on the name path, and neither field present is MissingRequestField. So today new SetCurrentProgramSceneRequestData() compiles and fails at runtime, and sending both silently ignores the name.

A handle is that choice made once. It holds identity only, never cached state.

Generated, not transcribed

The protocol never says "this request takes a scene". It says the request has an optional sceneName beside an optional sceneUuid, repeated across 68 requests. Reading that shape back out gives 66 requests across five operation types: Input 30, SceneItem 13, Scene 11, Filter 7, Source 5. DuplicateSceneItem's second scene falls out of the rule as a destinationScene parameter without anyone having thought about it, which is the test that it is a rule and not a list.

The same reading of events and responses gives 47 handles that cost no round trip, including CreateScene and CreateInput, which already answer with a uuid.

Two decisions worth reviewing

These are not overloads of the existing methods. That was the first attempt and it broke 48 call sites: M(XRequestData) and M(XHandle) are ambiguous the moment a caller writes M(new(...)), and that idiom is all over the surface and the README.

Guid, not a wrapper struct. OBS writes RFC 4122 uuids, so Guid's "D" format matches exactly. A raw Guid does not distinguish a scene from an input, but OBS does not either: obs_get_source_by_uuid takes any source uuid, and AcquireScene catches the mismatch with InvalidResourceType. Handles carry the uuid as the wire string and never parse it, so a value OBS sends that is not a Guid cannot break a response.

Numbers OBS does not bound

The request sweep caught GetOutputList failing outright: an idle virtual camera reported outputHeight as 2586032160. It comes from obs_output_get_width/_height, which are uint32_t and pass through unclamped, so an int could not hold it — and one bad field fails the whole response, not just itself. Intermittent, and only for whoever has a virtual camera or a capture plugin installed.

That prompted a sweep of the whole numeric table against the obs-websocket and obs-studio sources. The rule that came out of it: a field is safe as an int only where obs-websocket validates a range; where it copies a value out of libobs or a settings blob, the C type decides. Reclassified:

Field	Upstream
outputWidth/outputHeight (stub)	uint32_t, unclamped
render*Frames, output*Frames	uint32_t, monotonic — passes int32 at ~414 days at 60fps
webSocketSession*Messages	uint64_t
sceneItemId	int64_t, validated >= 0 with no upper bound
transitionDuration	int64_t out of private settings, not revalidated on read
alignment, boundsAlignment	uint32_t, validated to 0 .. uint32_t max

sceneIndex becomes nullable for the same class of reason: GetCanvasSceneList enumerates through a callback with no index to report and sends null.

Everything else stayed int on evidence, not assumption — the resolutions are validated 8..4096, the indices 0..8192, and the monitor fields are Qt int.

sceneItemId widening to long is the one API-visible cost, and it is why this is in the handle PR rather than a follow-up: SceneItemHandle is built around that type, and changing it now costs a compile error at ~20 call sites instead of a break after release.

Verified against OBS 32.2.2, both transports

The rename check is the one that matters:

resolved to fb07b481-..., both read 1 item(s); after a rename the uuid still resolves (True) and the name does not (True)

Also live: a scene item resolving by source name and navigating back to its scene, and a failed lookup naming what does exist. That last one is free, because resolving already fetched the list.

The settings-mode checks now build their own browser source and gain filter and remove them again, so a fresh OBS install runs the same suite. Verified by clearing OBS to a single input first: 0 failures, both transports, and nothing left behind afterwards.

340 tests, 0 warnings, full forced regeneration clean, zero unreadable payloads across the request sweep.

Not done

• SetCurrentProgramAsync is what the naming rule produces from SetCurrentProgramScene. Mechanically right, reads slightly oddly.
• No CanvasOperations: the canvases category holds only GetCanvasList, so there is nothing to scope. CanvasHandle still exists, because it scopes scene and source names.