obs-mcp 0.2.0

OBS Studio control server for AI assistants via MCP and the OBS WebSocket protocol
Documentation
//! 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;
    }
}