//! A faithful mock of the OBS WebSocket v5 server, used for live testing
//! without a running OBS Studio.
//!
//! It implements the wire protocol exactly (Hello with optional challenge
//! authentication, Identify, correlated Request/Response, RequestBatch) and
//! answers every request with a plausible success response backed by a small
//! state machine (scenes, inputs, recording/streaming flags, ...). The
//! `mock-obs` example runs it standalone; the integration test in
//! `tests/live.rs` starts it in-process.
use anyhow::{anyhow, Context, Result};
use base64::Engine;
use futures_util::{SinkExt, StreamExt};
use serde_json::{Value, json};
use sha2::{Digest, Sha256};
use tokio::net::{TcpListener, TcpStream};
use tokio_tungstenite::{accept_async, tungstenite::Message};
/// A running mock OBS WebSocket server.
pub struct MockServer {
pub port: u16,
/// Keeps the accept-loop task alive for the lifetime of this struct.
#[allow(dead_code)]
handle: tokio::task::JoinHandle<()>,
}
impl MockServer {
/// Start a mock OBS WebSocket server on an ephemeral local port.
pub async fn start(password: Option<String>) -> Result<Self> {
let listener = TcpListener::bind("127.0.0.1:0").await?;
let port = listener.local_addr()?.port();
let handle = tokio::spawn(async move {
if let Err(e) = accept_loop(listener, password).await {
eprintln!("mock OBS server error: {e}");
}
});
Ok(Self { port, handle })
}
/// The `ws://` URL clients should connect to.
pub fn url(&self) -> String {
format!("ws://127.0.0.1:{}", self.port)
}
}
async fn accept_loop(listener: TcpListener, password: Option<String>) -> Result<()> {
loop {
let (stream, _) = listener.accept().await?;
let password = password.clone();
tokio::spawn(async move {
if let Err(e) = handle_conn(stream, password).await {
eprintln!("mock OBS connection error: {e}");
}
});
}
}
async fn handle_conn(stream: TcpStream, password: Option<String>) -> Result<()> {
let mut ws = accept_async(stream).await.context("websocket handshake")?;
let mut state = MockState::default();
// Hello (op 0)
let salt = random_token(16);
let challenge = random_token(24);
let auth = if password.is_some() {
json!({ "challenge": challenge, "salt": salt })
} else {
Value::Null
};
let hello = json!({
"op": 0,
"d": {
"obsWebSocketVersion": "5.5.2",
"rpcVersion": 1,
"obsStudioVersion": "30.2.3",
"authentication": auth,
}
});
ws.send(Message::Text(hello.to_string().into())).await?;
// Wait for Identify (op 1)
let identify = loop {
match next_json(&mut ws).await? {
Some(msg) if msg.get("op").and_then(|v| v.as_u64()) == Some(1) => break msg,
Some(_) => continue,
None => return Err(anyhow!("connection closed before Identify")),
}
};
if let (Some(pw), Some(auth_obj)) = (&password, auth.as_object()) {
let expected = auth_string(
pw,
auth_obj["salt"].as_str().unwrap_or(""),
auth_obj["challenge"].as_str().unwrap_or(""),
);
let given = identify["d"]["authentication"].as_str().unwrap_or("");
if given != expected {
ws.send(Message::Close(None)).await.ok();
return Err(anyhow!("authentication failed"));
}
}
// Identified (op 2)
let identified = json!({ "op": 2, "d": { "negotiatedRpcVersion": 1 } });
ws.send(Message::Text(identified.to_string().into())).await?;
// Serve requests.
while let Some(msg) = next_json(&mut ws).await? {
let op = msg.get("op").and_then(|v| v.as_u64());
match op {
Some(6) => {
let resp = answer(&msg, &mut state);
ws.send(Message::Text(resp.to_string().into())).await?;
}
Some(8) => {
// RequestBatch (op 8) -> RequestBatchResponse (op 9)
let d = &msg["d"];
let requests = d["requests"].as_array().cloned().unwrap_or_default();
let mut results = Vec::new();
for req in &requests {
let wrapped = json!({ "op": 6, "d": req });
let mut sub = answer(&wrapped, &mut state);
sub["d"]["requestId"] = req["requestId"].clone();
results.push(sub["d"].clone());
}
let batch_resp = json!({ "op": 9, "d": { "requestId": d["requestId"], "results": results } });
ws.send(Message::Text(batch_resp.to_string().into())).await?;
}
Some(5) => { /* Event, nothing to do for a client -> server message */ }
_ => {}
}
if matches!(msg.get("op").and_then(|v| v.as_u64()), Some(2)) {
break;
}
}
Ok(())
}
/// Build a RequestResponse (op 7) for one Request (op 6) message.
fn answer(msg: &Value, state: &mut MockState) -> Value {
let d = &msg["d"];
let request_type = d["requestType"].as_str().unwrap_or("");
let request_data = d["requestData"].clone();
let response_data = mock_response(state, request_type, &request_data);
let request_status = if response_data.get("__error").is_some() {
json!({
"result": false,
"code": 500,
"comment": response_data["__error"].as_str().unwrap_or("mock error"),
})
} else {
json!({ "result": true, "code": 100 })
};
json!({
"op": 7,
"d": {
"requestType": request_type,
"requestId": d["requestId"].clone(),
"requestStatus": request_status,
"responseData": response_data,
}
})
}
/// State that makes consecutive mock answers coherent.
#[derive(Default)]
struct MockState {
current_scene: String,
scenes: Vec<String>,
preview_scene: String,
inputs: Vec<String>,
recording: bool,
recording_paused: bool,
streaming: bool,
virtual_cam: bool,
replay_buffer: bool,
studio_mode: bool,
transition: String,
transition_duration: u64,
}
fn mock_response(state: &mut MockState, req: &str, data: &Value) -> Value {
let s = |k: &str| data.get(k).and_then(|v| v.as_str()).unwrap_or("").to_string();
match req {
"GetVersion" => json!({
"obsVersion": "30.2.3",
"obsWebSocketVersion": "5.5.2",
"rpcVersion": 1,
"availableRequests": ["GetVersion", "GetStats", "GetSceneList"],
"supportedImageFormats": ["png", "jpg", "bmp", "webp"],
"platform": "linux",
"platformDescription": "mock",
}),
"GetStats" => json!({
"cpuUsage": 2.5,
"memoryUsage": 900.0,
"availableDiskSpace": 500_000_000_000u64,
"activeFps": 60.0,
"averageFrameTime": 16.6,
"renderSkippedFrames": 0,
"renderTotalFrames": 1000,
"outputSkippedFrames": 0,
"outputTotalFrames": 1000,
"webSocketSessionIncomingMessages": 5,
"webSocketSessionOutgoingMessages": 5,
}),
"GetSceneList" => json!({
"currentProgramSceneName": state.current_scene,
"scenes": state.scenes.iter().map(|s| json!({ "sceneName": s, "sceneIndex": 0 })).collect::<Vec<_>>(),
}),
"GetCurrentProgramScene" => json!({ "currentProgramSceneName": state.current_scene }),
"SetCurrentProgramScene" => { state.current_scene = s("sceneName"); json!({}) }
"GetCurrentPreviewScene" => json!({ "currentPreviewSceneName": state.preview_scene }),
"SetCurrentPreviewScene" => { state.preview_scene = s("sceneName"); json!({}) }
"CreateScene" => {
let name = s("sceneName");
if !name.is_empty() {
state.scenes.push(name);
}
json!({})
}
"RemoveScene" => { state.scenes.retain(|x| *x != s("sceneName")); json!({}) }
"GetSceneItemList" => json!({ "sceneItems": [ { "inputKind": "dummy", "isGroup": false, "sceneItemBlendMode": "OBS_BLEND_NORMAL", "sceneItemEnabled": true, "sceneItemId": 1, "sceneItemIndex": 0, "sceneItemLocked": false, "sceneItemTransform": { "alignment": 5, "boundsAlignment": 0, "boundsHeight": 0.0, "boundsType": "OBS_BOUNDS_NONE", "boundsWidth": 0.0, "cropBottom": 0, "cropLeft": 0, "cropRight": 0, "cropTop": 0, "height": 1080.0, "positionX": 0.0, "positionY": 0.0, "rotation": 0.0, "scaleX": 1.0, "scaleY": 1.0, "sourceHeight": 1080.0, "sourceWidth": 1920.0, "width": 1920.0 }, "sourceName": "Test Source" } ] }),
"GetSceneItemId" => json!({ "sceneItemId": 1 }),
"CreateSceneItem" => json!({ "sceneItemId": 2 }),
"GetSceneItemTransform" => json!({ "sceneItemTransform": { "positionX": 0.0, "positionY": 0.0, "rotation": 0.0, "scaleX": 1.0, "scaleY": 1.0, "cropTop": 0, "cropBottom": 0, "cropLeft": 0, "cropRight": 0 } }),
"GetInputList" => json!({ "inputs": state.inputs.iter().map(|n| json!({ "inputName": n, "inputKind": "dummy", "inputUuid": format!("uuid-{n}") })).collect::<Vec<_>>() }),
"GetSpecialInputs" => json!({ "desktop1": "Desktop Audio", "desktop2": "Desktop Audio 2", "mic1": "Mic/Aux", "mic2": "Mic/Aux 2" }),
"CreateInput" => {
let name = s("inputName");
if !name.is_empty() {
state.inputs.push(name);
}
json!({ "sceneItemId": 3 })
}
"GetInputKindList" => json!({ "inputKinds": ["dummy", "ffmpeg_source", "text_ft2_source"] }),
"GetSourceFilterKindList" => json!({ "sourceFilterKinds": ["color_filter", "sharpness_filter"] }),
"GetSourceFilterList" => json!({ "filters": [ { "filterEnabled": true, "filterIndex": 0, "filterKind": "color_filter", "filterName": "Test Filter", "filterSettings": {} } ] }),
"GetMonitorList" => json!({ "monitors": [ { "monitorHeight": 1080, "monitorIndex": 0, "monitorName": "Mock Monitor", "monitorPositionX": 0, "monitorPositionY": 0, "monitorWidth": 1920 } ] }),
"GetTransitionList" | "GetSceneTransitionList" => json!({ "currentSceneTransitionName": state.transition, "transitions": [ { "transitionKind": "cut_transition", "transitionName": "Cut", "transitionConfigurable": false, "transitionFixed": true } ] }),
"GetTransitionKindList" => json!({ "transitionKinds": ["cut_transition", "fade_transition", "swipe_transition", "stinger_transition"] }),
"GetCanvasList" => json!({ "canvases": [ { "canvasName": "Default", "canvasUuid": "mock-canvas", "canvasWidth": 1920, "canvasHeight": 1080, "sceneCount": 1 } ] }),
"GetGroupList" => json!({ "groups": [ { "groupName": "Mock Group", "groupUuid": "mock-group", "groupIndex": 0, "groupItems": [] } ] }),
"GetGroupSceneItemList" => json!({ "sceneItems": [] }),
"GetInputAudioTracks" => json!({ "inputAudioTracks": { "1": true, "2": false } }),
"GetInputDeinterlaceMode" => json!({ "inputDeinterlaceMode": "OBS_DEINTERLACE_MODE_DISABLE" }),
"GetInputDeinterlaceFieldOrder" => json!({ "inputDeinterlaceFieldOrder": "OBS_DEINTERLACE_FIELD_ORDER_TOP" }),
"GetInputPropertiesListPropertyItems" => json!({ "propertyItems": [ { "itemName": "Item 1", "itemValue": "1", "itemEnabled": true } ] }),
"GetSceneItemEnabled" => json!({ "sceneItemEnabled": true }),
"GetSceneItemIndex" => json!({ "sceneItemIndex": 0 }),
"GetSceneItemLocked" => json!({ "sceneItemLocked": false }),
"GetSceneItemBlendMode" => json!({ "sceneItemBlendMode": "OBS_BLEND_NORMAL" }),
"GetSceneItemSource" => json!({ "sourceName": "Test Source", "sourceUuid": "mock-source", "sourceType": "OBS_SOURCE_TYPE_INPUT" }),
"GetSceneItemPrivateSettings" => json!({ "sceneItemSettings": {} }),
"GetSourcePrivateSettings" => json!({ "sourceSettings": {} }),
"GetCurrentSceneTransitionCursor" => json!({ "transitionCursor": 0.5 }),
"GetSceneSceneTransitionOverride" => json!({ "transitionName": null, "transitionDuration": null }),
"DuplicateSceneItem" => json!({ "sceneItemId": 9 }),
"SetSceneName" => json!({}),
"SetTBarPosition" => json!({}),
"PressInputPropertiesButton" => json!({}),
"GetCurrentSceneTransition" => json!({ "transitionName": state.transition, "transitionKind": "cut_transition", "transitionSettings": {}, "transitionDuration": state.transition_duration }),
"SetCurrentSceneTransition" => { state.transition = s("transitionName"); json!({}) }
"GetCurrentSceneTransitionDuration" => json!({ "transitionDuration": state.transition_duration }),
"SetCurrentSceneTransitionDuration" => {
state.transition_duration = data.get("transitionDuration").and_then(|v| v.as_u64()).unwrap_or(300);
json!({})
}
"GetRecordStatus" => json!({ "outputActive": state.recording, "outputPaused": state.recording_paused, "outputTimecode": "00:00:10.000", "outputDuration": 10000 }),
"StartRecord" => { state.recording = true; json!({}) }
"StopRecord" => { state.recording = false; json!({ "outputPath": "/tmp/mock-recording.mp4" }) }
"ToggleRecord" => { state.recording = !state.recording; json!({ "outputActive": state.recording }) }
"PauseRecord" => { state.recording_paused = true; json!({}) }
"ResumeRecord" => { state.recording_paused = false; json!({}) }
"ToggleRecordPause" => { state.recording_paused = !state.recording_paused; json!({}) }
"GetStreamStatus" => json!({ "outputActive": state.streaming, "outputReconnecting": false, "outputTimecode": "00:00:10.000", "outputDuration": 10000, "outputCongestion": 0.0, "outputBytes": 1000, "outputSkippedFrames": 0, "outputTotalFrames": 1000 }),
"StartStream" => { state.streaming = true; json!({}) }
"StopStream" => { state.streaming = false; json!({}) }
"ToggleStream" => { state.streaming = !state.streaming; json!({ "outputActive": state.streaming }) }
"GetVirtualCamStatus" => json!({ "outputActive": state.virtual_cam }),
"ToggleVirtualCam" => { state.virtual_cam = !state.virtual_cam; json!({ "outputActive": state.virtual_cam }) }
"StartVirtualCam" => { state.virtual_cam = true; json!({}) }
"StopVirtualCam" => { state.virtual_cam = false; json!({}) }
"GetReplayBufferStatus" => json!({ "outputActive": state.replay_buffer }),
"ToggleReplayBuffer" => { state.replay_buffer = !state.replay_buffer; json!({ "outputActive": state.replay_buffer }) }
"StartReplayBuffer" => { state.replay_buffer = true; json!({}) }
"StopReplayBuffer" => { state.replay_buffer = false; json!({}) }
"GetStudioModeEnabled" => json!({ "studioModeEnabled": state.studio_mode }),
"SetStudioModeEnabled" => { state.studio_mode = data.get("studioModeEnabled").and_then(|v| v.as_bool()).unwrap_or(false); json!({}) }
"GetOutputList" => json!({ "outputs": [ { "outputActive": false, "outputKind": "ffmpeg_muxer", "outputName": "adv_file_output", "outputReconnecting": false, "outputWidth": 1920, "outputHeight": 1080 } ] }),
"GetOutputStatus" => json!({ "outputActive": false, "outputReconnecting": false, "outputTimecode": "00:00:00.000", "outputDuration": 0, "outputCongestion": 0.0, "outputBytes": 0, "outputSkippedFrames": 0, "outputTotalFrames": 0 }),
"GetOutputSettings" => json!({ "outputSettings": { "path": "/tmp/mock.mp4" } }),
"GetInputSettings" => json!({ "inputSettings": { "url": "https://example.com/stream.m3u8" }, "inputKind": "dummy" }),
"GetInputMute" => json!({ "inputMuted": false }),
"GetInputVolume" => json!({ "inputVolumeMul": 1.0, "inputVolumeDb": 0.0 }),
"GetInputAudioBalance" => json!({ "inputAudioBalance": 0.5 }),
"GetInputAudioSyncOffset" => json!({ "inputAudioSyncOffset": 0 }),
"GetInputAudioMonitorType" => json!({ "monitorType": "OBS_MONITORING_TYPE_NONE" }),
"GetMediaInputStatus" => json!({ "mediaState": "OBS_MEDIA_STATE_PLAYING", "mediaDuration": 10000, "mediaCursor": 1000 }),
"GetSourceActive" => json!({ "videoActive": true, "videoShowing": true }),
"GetSourceScreenshot" => json!({ "imageData": "iVBORw0KGgo=" }),
"GetHotkeyList" => json!({ "hotkeys": ["OBSBasic.StartStreaming", "OBSBasic.StopStreaming", "OBSBasic.StartRecording"] }),
"GetPersistentData" => json!({ "slotValue": { "hello": "world" } }),
"GetProfileParameter" => json!({ "parameterValue": "mock" }),
"GetProfileList" => json!({ "currentProfileName": "Mock", "profiles": ["Mock"] }),
"GetSceneCollectionList" => json!({ "currentSceneCollectionName": "Mock", "sceneCollections": ["Mock"] }),
"GetRecordDirectory" => json!({ "recordDirectory": "/tmp" }),
"GetVideoSettings" => json!({ "fpsNumerator": 60, "fpsDenominator": 1, "baseWidth": 1920, "baseHeight": 1080, "outputWidth": 1920, "outputHeight": 1080 }),
"GetStreamServiceSettings" => json!({ "streamServiceType": "rtmp_common", "streamServiceSettings": { "server": "rtmp://example.com/live", "key": "mock-key" } }),
"GetLastReplayBufferReplay" => json!({ "savedReplayPath": "/tmp/replay.mp4" }),
"Sleep" => json!({}),
_ => json!({}),
}
}
async fn next_json(ws: &mut tokio_tungstenite::WebSocketStream<TcpStream>) -> Result<Option<Value>> {
loop {
match ws.next().await {
Some(Ok(Message::Text(t))) => {
return serde_json::from_str(&t)
.map(Some)
.map_err(|e| anyhow!("invalid JSON: {e}"))
}
Some(Ok(Message::Close(_))) | None => return Ok(None),
Some(Ok(_)) => continue,
Some(Err(e)) => return Err(anyhow!("read error: {e}")),
}
}
}
fn random_token(len: usize) -> String {
use std::time::{SystemTime, UNIX_EPOCH};
static COUNTER: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
let n = COUNTER.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
let t = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_nanos())
.unwrap_or(0);
// Deterministic-ish pseudo-random bytes from timestamp + counter hashed.
let mut out = String::new();
let mut acc = (t as u128) ^ ((n as u128) << 64);
while out.len() < len {
acc = acc.wrapping_mul(6364136223846793005).wrapping_add(1442695040888963407);
let byte = (acc >> 56) as u8;
let c = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"[byte as usize % 64];
out.push(c as char);
}
out
}
/// Compute the obs-websocket authentication string (shared with the client).
pub fn auth_string(password: &str, salt: &str, challenge: &str) -> String {
let secret = Sha256::digest(format!("{password}{salt}").as_bytes());
let secret_b64 = base64::engine::general_purpose::STANDARD.encode(secret);
let auth = Sha256::digest(format!("{secret_b64}{challenge}").as_bytes());
base64::engine::general_purpose::STANDARD.encode(auth)
}
/// Run the mock server standalone until killed; used by the mock-obs example.
pub async fn run_standalone(password: Option<String>) -> Result<()> {
let server = MockServer::start(password).await?;
println!("mock OBS WebSocket listening on {}", server.url());
loop {
tokio::time::sleep(std::time::Duration::from_secs(3600)).await;
}
}