path: root/docs/superpowers/plans/2026-10-17-obs-pill.md

# OBS Pill Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** An island pill that exists while OBS runs; a click opens its panel (record, pause, webcam visibility, scene list), and the sliver pulses while recording.

**Architecture:** `Obs.qml` singleton speaks obs-websocket v5 over QML `WebSocket` (QtWebSockets), reading the password from OBS's own config; the SHA256 auth string comes from `obs-auth.sh` (openssl). `ObsPill.qml` shows a dot and elapsed time at rest and morphs into a controls panel on click, as the status pill does for sound. `Island.qml` places the pill right of the status pill and draws the pulse over the sliver.

**Tech Stack:** Quickshell 0.3.1 QML, QtWebSockets, openssl, node (for `test_logic.js`).

Spec: `docs/superpowers/specs/2026-10-17-obs-pill-design.md`.

**Spec deviations, found while planning:**
- QML `WebSocket` exposes no close code, so an auth failure (4009) cannot be told apart from OBS closing. The singleton logs "closed before Identified" once per run of failures instead.
- Responses route on `requestType`, which obs-websocket echoes in every response; no prefixed `requestId` is needed.

## Files

- Create `desktop/island/obs-auth.sh`: stdin `password+salt` line, `challenge` line; stdout the auth string.
- Create `desktop/island/Obs.qml`: singleton, protocol and state.
- Create `desktop/island/ObsPill.qml`: the pill and its panel.
- Modify `desktop/island/Logic.js`, `desktop/island/test_logic.js`: `obsElapsed`.
- Modify `desktop/island/Island.qml`: hover, mask, placement, sliver pulse.
- Modify `desktop/island/README.md`, `AGENTS.md`: docs.

## Constraints every task must respect

- GPLv2 header on every new file (copy from `privacy.sh` / `Privacy.qml`).
- Glyphs render with `Theme.iconFamily`. Checked present in Inconsolata Nerd Font: `\uf111` fa-circle, the only glyph used.
- Never run `qs` detached or `reload.sh` from a tool call (AGENTS.md). New files in `island/` need `./reload.sh desktop` from the user's terminal to be indexed.
- Process name is `qs`; never `pkill -f`.

---

### Task 1: Logic helpers

**Files:** Modify `desktop/island/Logic.js`, `desktop/island/test_logic.js`

- [ ] **Step 1: Failing tests.** In `test_logic.js`, extend the return list to `{ volumeIcon, vmRole, flagFor, privacyRoles, parseOpenWindow, obsElapsed }` and add before `console.log("ok")`:

```js
// OBS elapsed: mm:ss under an hour, h:mm:ss past it.
assert.strictEqual(L.obsElapsed(0), "00:00");
assert.strictEqual(L.obsElapsed(61000), "01:01");
assert.strictEqual(L.obsElapsed(3599999), "59:59");
assert.strictEqual(L.obsElapsed(3661000), "1:01:01");
assert.strictEqual(L.obsElapsed(undefined), "00:00");

```

- [ ] **Step 2:** `node desktop/island/test_logic.js` → FAIL, `obsElapsed is not defined`.

- [ ] **Step 3: Implement** at the end of `Logic.js`:

```js
// OBS's outputDuration (ms) as mm:ss, or h:mm:ss past an hour.
function obsElapsed(ms) {
    const s = Math.floor((ms > 0 ? ms : 0) / 1000);
    const two = n => String(n).padStart(2, "0");
    const h = Math.floor(s / 3600);
    const mmss = `${two(Math.floor(s / 60) % 60)}:${two(s % 60)}`;
    return h ? `${h}:${mmss}` : mmss;
}

```

- [ ] **Step 4:** `node desktop/island/test_logic.js` → `ok`.

- [ ] **Step 5: Commit** `island: elapsed-time helper for the OBS pill`.

### Task 2: Auth helper

**Files:** Create `desktop/island/obs-auth.sh` (mode 755)

- [ ] **Step 1: Write it** (GPL header as in `privacy.sh`, then):

```sh
# obs-websocket v5 authentication, which QML cannot compute: it has no
# SHA256. stdin is two lines, password+salt then challenge, so neither
# reaches a command line. stdout is
#   base64(sha256(base64(sha256(password + salt)) + challenge))

read -r ps || exit 1
read -r ch || exit 1
secret=$(printf %s "$ps" | openssl dgst -sha256 -binary | base64)
printf %s "$secret$ch" | openssl dgst -sha256 -binary | base64
```

- [ ] **Step 2: Check against Python** (one-off, not committed):

```sh
printf 'pwSALT\nCHAL\n' | sh desktop/island/obs-auth.sh
/usr/bin/python3 -c "import hashlib,base64;s=base64.b64encode(hashlib.sha256(b'pwSALT').digest());print(base64.b64encode(hashlib.sha256(s+b'CHAL').digest()).decode())"
```
Expected: identical lines.

- [ ] **Step 3: Commit** `island: obs-websocket auth helper`.

### Task 3: `Obs.qml` singleton

**Files:** Create `desktop/island/Obs.qml`

- [ ] **Step 1: Write it** (GPL header, then):

```qml
pragma Singleton

import Quickshell
import Quickshell.Io
import QtQuick
import QtWebSockets

// OBS Studio over obs-websocket v5. Connected means OBS is running with
// its server enabled, so nothing checks for the process. State follows
// OBS's events; actions only send requests and never set state
// optimistically.
Singleton {
    id: root

    property bool connected: false
    property bool recording: false
    property bool paused: false
    property real duration: 0
    property var scenes: []
    property string scene: ""
    // The webcam: the first v4l2_input item in the current scene, -1 for none.
    // ponytail: a webcam inside a group or nested scene is not found; walk
    // GetGroupSceneItemList if one ever is.
    property int camId: -1
    property bool camOn: false

    function toggleRecord() { request("ToggleRecord"); }
    function togglePause() { request("ToggleRecordPause"); }
    function setScene(name) { if (name) request("SetCurrentProgramScene", { sceneName: name }); }
    function toggleCam() {
        if (camId >= 0)
            request("SetSceneItemEnabled", { sceneName: scene, sceneItemId: camId, sceneItemEnabled: !camOn });
    }

    // --- config -----------------------------------------------------------

    // OBS's own file, so no copy of the password exists anywhere else.
    FileView {
        id: cfg
        path: `${Quickshell.env("XDG_CONFIG_HOME") || Quickshell.env("HOME") + "/.config"}/obs-studio/plugin_config/obs-websocket/config.json`
        watchChanges: true
        onFileChanged: reload()
    }

    function config() {
        try { return JSON.parse(cfg.text()); } catch (e) { return null; }
    }

    // --- socket -----------------------------------------------------------

    property bool warned: false
    property bool wasOpen: false

    WebSocket {
        id: sock
        onStatusChanged: {
            if (status === WebSocket.Open) { root.wasOpen = true; return; }
            if (status === WebSocket.Connecting) return;
            // QML's WebSocket hides the close code, so a wrong password
            // (4009) and OBS quitting look the same. Say it once per run.
            if (root.wasOpen && !root.connected && !root.warned) {
                console.warn("obs: closed before Identified, wrong password?");
                root.warned = true;
            }
            root.reset();
        }
        onTextMessageReceived: message => {
            try { root.receive(JSON.parse(message)); }
            catch (e) { console.warn(`obs: bad message: ${e}`); }
        }
    }

    function reset() {
        connected = false; wasOpen = false;
        recording = false; paused = false; duration = 0;
        scenes = []; scene = ""; camId = -1; camOn = false;
    }

    // Retry while not connected; a closed or failed socket is reopened by
    // toggling active.
    Timer {
        interval: 3000
        repeat: true
        running: !root.connected
        triggeredOnStart: true
        onTriggered: {
            if (sock.status === WebSocket.Open || sock.status === WebSocket.Connecting) return;
            const c = root.config();
            if (!c || !c.server_enabled) return;
            sock.active = false;
            sock.url = `ws://127.0.0.1:${c.server_port}`;
            sock.active = true;
        }
    }

    // --- protocol -----------------------------------------------------------

    property int seq: 0

    function send(op, d) { sock.sendTextMessage(JSON.stringify({ op: op, d: d })); }

    function request(type, data) {
        if (!connected) return;
        send(6, { requestType: type, requestId: String(++seq), requestData: data || {} });
    }

    function identify(token) {
        const d = { rpcVersion: 1, eventSubscriptions: 4 | 64 | 128 }; // Scenes | Outputs | SceneItems
        if (token) d.authentication = token;
        send(1, d);
    }

    Process {
        id: auth
        command: ["sh", `${Quickshell.shellDir}/island/obs-auth.sh`]
        stdinEnabled: true
        property string data: ""
        onStarted: { auth.write(auth.data); auth.stdinEnabled = false; }
        stdout: StdioCollector { onStreamFinished: root.identify(text.trim()) }
    }

    function receive(m) {
        switch (m.op) {
        case 0: { // Hello
            const a = m.d.authentication;
            if (!a) { identify(""); break; }
            const c = config();
            auth.data = `${c ? c.server_password : ""}${a.salt}\n${a.challenge}\n`;
            auth.stdinEnabled = true;
            auth.running = false;
            auth.running = true;
            break;
        }
        case 2: // Identified
            connected = true;
            warned = false;
            request("GetRecordStatus");
            request("GetSceneList");
            break;
        case 5:
            event(m.d.eventType, m.d.eventData || {});
            break;
        case 7:
            response(m.d);
            break;
        }
    }

    function event(type, d) {
        switch (type) {
        case "RecordStateChanged":
            recording = d.outputActive;
            paused = d.outputState === "OBS_WEBSOCKET_OUTPUT_PAUSED";
            if (!recording) duration = 0;
            break;
        case "CurrentProgramSceneChanged":
            scene = d.sceneName;
            request("GetSceneItemList", { sceneName: scene });
            break;
        case "SceneListChanged":
        case "SceneItemCreated":
        case "SceneItemRemoved":
            request("GetSceneList");
            break;
        case "SceneItemEnableStateChanged":
            if (d.sceneName === scene && d.sceneItemId === camId) camOn = d.sceneItemEnabled;
            break;
        }
    }

    function response(d) {
        if (!d.requestStatus.result) {
            console.warn(`obs: ${d.requestType} failed: ${d.requestStatus.comment ?? d.requestStatus.code}`);
            return;
        }
        const r = d.responseData || {};
        switch (d.requestType) {
        case "GetRecordStatus":
            recording = r.outputActive;
            paused = r.outputPaused;
            duration = r.outputDuration;
            break;
        case "GetSceneList":
            // obs-websocket lists scenes bottom-up; reversed is OBS's own order.
            scenes = r.scenes.slice().reverse().map(s => s.sceneName);
            scene = r.currentProgramSceneName;
            request("GetSceneItemList", { sceneName: scene });
            break;
        case "GetSceneItemList": {
            const it = r.sceneItems.find(i => i.inputKind === "v4l2_input");
            camId = it ? it.sceneItemId : -1;
            camOn = !!it && it.sceneItemEnabled;
            break;
        }
        }
    }

    // OBS owns the clock, so pausing freezes it with no local bookkeeping.
    // ponytail: one local request a second, only while recording.
    Timer {
        interval: 1000
        repeat: true
        running: root.recording && !root.paused
        onTriggered: root.request("GetRecordStatus")
    }
}
```

- [ ] **Step 2: Commit** `island: Obs singleton, obs-websocket v5 client`. Verified together with the pill in Task 5.

### Task 4: `ObsPill.qml`

**Files:** Create `desktop/island/ObsPill.qml`

- [ ] **Step 1: Write it** (GPL header, then):

```qml
import QtQuick
import ".."
import "Logic.js" as Logic

// At rest a record dot, with the elapsed time while recording. A click
// morphs the capsule into the controls panel, as the status pill does for
// sound: record, pause, webcam, and the scene list.
Capsule {
    id: pill

    property string panel: ""
    signal openPanel()

    expanded: panel === "obs"
    restWidth: rest.implicitWidth + 24
    panelWidth: 260
    panelHeight: controls.implicitHeight + 28

    Row {
        id: rest
        anchors.centerIn: parent
        spacing: 6
        opacity: pill.expanded ? 0 : 1
        visible: opacity > 0
        Behavior on opacity { NumberAnimation { duration: 120 } }

        Text {
            anchors.verticalCenter: parent.verticalCenter
            text: "\uf111"
            color: Obs.recording ? Theme.red : Theme.subtext
            opacity: Obs.paused ? 0.5 : 1
            font { family: Theme.iconFamily; pixelSize: 14 }
        }
        Text {
            anchors.verticalCenter: parent.verticalCenter
            visible: Obs.recording
            text: Logic.obsElapsed(Obs.duration)
            color: Theme.text
            font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 2 }
        }
    }

    MouseArea {
        anchors.fill: parent
        enabled: !pill.expanded
        cursorShape: Qt.PointingHandCursor
        onClicked: pill.openPanel()
    }

    Column {
        id: controls
        x: 14
        y: 14
        width: pill.panelWidth - 28
        spacing: 10
        opacity: pill.expanded ? 1 : 0
        visible: opacity > 0
        Behavior on opacity { NumberAnimation { duration: 160 } }

        Text {
            text: Obs.recording ? (Obs.paused ? "Paused  " : "Recording  ") + Logic.obsElapsed(Obs.duration)
                                : "Not recording"
            color: Obs.recording ? Theme.red : Theme.subtext
            font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 2 }
        }

        Row {
            spacing: 8
            Button {
                text: Obs.recording ? "Stop" : "Record"
                danger: Obs.recording
                onClicked: Obs.toggleRecord()
            }
            Button {
                visible: Obs.recording
                text: Obs.paused ? "Resume" : "Pause"
                onClicked: Obs.togglePause()
            }
            Button {
                visible: Obs.camId >= 0
                text: Obs.camOn ? "Hide webcam" : "Show webcam"
                onClicked: Obs.toggleCam()
            }
        }

        // ponytail: a plain Column, no scrolling; about ten scenes fit the
        // island's 480px window. A ListView if a scene collection outgrows it.
        Repeater {
            model: Obs.scenes
            delegate: Rectangle {
                required property string modelData
                readonly property bool current: modelData === Obs.scene
                width: controls.width
                height: 30
                radius: 7
                color: current ? Qt.alpha(Theme.accent, 0.25)
                     : area.containsMouse ? Qt.alpha(Theme.surface, 0.8) : "transparent"
                Text {
                    anchors { left: parent.left; leftMargin: 10; verticalCenter: parent.verticalCenter }
                    text: modelData
                    color: current ? Theme.text : Theme.subtext
                    font { family: Theme.fontFamily; pixelSize: Theme.fontSize - 2 }
                }
                MouseArea {
                    id: area
                    anchors.fill: parent
                    hoverEnabled: true
                    cursorShape: Qt.PointingHandCursor
                    onClicked: Obs.setScene(modelData)
                }
            }
        }
    }
}
```

`Button` is `desktop/Button.qml`, reached by `import ".."`.

- [ ] **Step 2: Commit** `island: OBS pill and its controls panel`.

### Task 5: Wire into the island

**Files:** Modify `desktop/island/Island.qml`

- [ ] **Step 1: Hover.** Line `readonly property bool hovered: ...` gains `|| obs.hovered`.

- [ ] **Step 2: Mask.** In `mask: Region { ... }` add
  `Region { item: obs.visible ? obs : null; intersection: Intersection.Combine }`.

- [ ] **Step 3: Pill**, after `MediaPill`, mirroring it on the right:

```qml
    // While OBS runs; right of the status pill, following it as the sound
    // panel widens it.
    ObsPill {
        id: obs
        visible: Obs.connected
        panel: win.panel
        onOpenPanel: win.panel = "obs"
        x: win.cx - width / 2 + (win.gap * 1.5 + status.width + width / 2) * win.reveal
        y: -height + (win.top + height) * win.reveal
        opacity: Math.min(1, win.reveal * 2)
    }
```

- [ ] **Step 3b: Panel bookkeeping.** The `panel` comment becomes `// "", "sound", "calendar" or "obs".` OBS quitting with its panel open must close it, else the island stays held open by an invisible pill. Add next to the dismissal section:

```qml
    Connections {
        target: Obs
        function onConnectedChanged() { if (!Obs.connected && win.panel === "obs") win.panel = ""; }
    }
```

Escape and outside clicks already close any panel (`keys`, `HyprlandFocusGrab`); nothing else to add.

- [ ] **Step 4: Sliver pulse**, right after the `sliver` Row:

```qml
    // Recording: a red pulse over the sliver, steady and dim while paused.
    // Red alone would not say it: OBS's screen source already lights the
    // privacy sliver's red segment whenever OBS is open.
    Rectangle {
        x: sliver.x
        y: 0
        width: sliver.width
        height: sliver.height
        radius: 2
        color: Theme.red
        visible: Obs.recording
        property real pulse: 1
        opacity: Obs.paused ? 0.4 : pulse
        SequentialAnimation on pulse {
            running: Obs.recording && !Obs.paused
            loops: Animation.Infinite
            NumberAnimation { to: 0.25; duration: 700; easing.type: Easing.InOutSine }
            NumberAnimation { to: 1; duration: 700; easing.type: Easing.InOutSine }
        }
    }
```

- [ ] **Step 5: Smoke.** Ask the user to run `./reload.sh desktop` (new files in `island/` need the reindex). Then `qs log -p desktop --log-times | tail -40`: expect no `ReferenceError`, no `QtWebSockets` import error.

- [ ] **Step 6: Live check with OBS** (user starts OBS; the server is enabled). Ask the user to confirm by eye:
  1. Pill appears within ~3s of OBS starting, disappears on quit.
  2. Click the pill: panel opens; Escape and an outside click close it.
  3. Record: rest dot turns red, timer counts in the panel and on the pill, sliver pulses.
  4. Pause: timer freezes, sliver steady dim. Resume continues.
  5. Picking a scene switches OBS; changing scene in OBS moves the highlight.
  6. Webcam button toggles the source in OBS; toggling the eye in OBS updates the button. Absent in a scene without a webcam.
  7. Stop: pill back to idle, pulse gone.
  8. Quit OBS with the panel open: panel and pill go, island hides.

  Agent side: `qs log -p desktop | grep obs:` shows no warnings during the above.

- [ ] **Step 7: Commit** `island: place the OBS pill and pulse the sliver while recording`.

### Task 6: Docs

**Files:** `desktop/island/README.md`, `AGENTS.md`

- [ ] **Step 1: README**, new section after "Media pill":

```markdown
## OBS pill

Right of the status pill, while OBS Studio runs with its WebSocket server
enabled (Tools > WebSocket Server Settings; auth stays on, the server
listens on every interface). `Obs.qml` speaks obs-websocket v5 directly
and reads the password from OBS's own `obs-websocket/config.json`, so no
copy of it exists; `obs-auth.sh` computes the SHA256 handshake QML cannot.

At rest it shows a record dot, with the elapsed time while recording. A
click opens its panel in the capsule: Record or Stop, Pause or Resume
(while recording), Show or Hide webcam (the first `v4l2_input` item in the
current scene; absent without one), and the scene list, current one
highlighted, click to switch. While recording the sliver pulses red, and
holds dim while paused.

QML's `WebSocket` does not expose the close code, so a wrong password
reads the same as OBS quitting; it is logged once as "closed before
Identified".
```

- [ ] **Step 2: AGENTS.md** line 19: `island/ top-centre pills on DP-1: clock, volume, tray, layout, privacy, calendar` → append `, OBS`.

- [ ] **Step 3: Commit** `docs: the OBS pill`.