mirabox-stream-dock-sdk 0.1.0__tar.gz

mirabox_stream_dock_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The project
+uses [Semantic Versioning](https://semver.org/); releases before `1.0.0` may
+change public APIs between minor versions.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-19
+
+- Added typed models for Stream Dock registration, events, and commands.
+- Added strict JSON parsing with diagnostic field paths.
+- Added typed codecs for settings and Property Inspector messages.
+- Added the reusable action registry and plugin runtime.
+- Added the WebSocket transport and common CLI lifecycle runner.
+- Added the shared Property Inspector JavaScript client.
+
+[Unreleased]: https://github.com/Nekit678/MiraboxStreamDockSDK/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Nekit678/MiraboxStreamDockSDK/releases/tag/v0.1.0

mirabox_stream_dock_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nekit678
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mirabox_stream_dock_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include CHANGELOG.md
+recursive-include examples *.html *.js *.json *.md *.py *.spec *.svg
+recursive-include scripts *.py
+recursive-include tests *.py

mirabox_stream_dock_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: mirabox-stream-dock-sdk
+Version: 0.1.0
+Summary: Typed Python SDK for building MiraBox Stream Dock plugins
+Author: Nekit678
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Nekit678/MiraboxStreamDockSDK
+Project-URL: Documentation, https://github.com/Nekit678/MiraboxStreamDockSDK#readme
+Project-URL: Repository, https://github.com/Nekit678/MiraboxStreamDockSDK.git
+Project-URL: Issues, https://github.com/Nekit678/MiraboxStreamDockSDK/issues
+Project-URL: Changelog, https://github.com/Nekit678/MiraboxStreamDockSDK/blob/main/CHANGELOG.md
+Keywords: mirabox,stream-dock,plugin,sdk,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websocket-client<2,>=1.8
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: ruff==0.15.21; extra == "dev"
+Dynamic: license-file
+
+# MiraBox Stream Dock SDK for Python
+
+Typed, unofficial Python SDK for building plugins for MiraBox Stream Dock. It
+implements the WebSocket protocol, registration, typed event parsing, outbound
+commands, per-plugin action registration, action lifecycle, plugin services,
+and a shared Property Inspector client.
+
+This project is not affiliated with or endorsed by MiraBox, HotSpot, or Elgato.
+The `connectElgatoStreamDeckSocket` callback name is kept because Stream Dock
+uses it for Property Inspector compatibility.
+
+## Requirements
+
+- Python 3.11 or newer;
+- MiraBox Stream Dock 2.10.179.426 or newer;
+- Windows for packaging a Python plugin with PyInstaller.
+
+## Installation
+
+```bash
+python -m pip install mirabox-stream-dock-sdk
+```
+
+For SDK development:
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+```
+
+On Windows, use `.venv\Scripts\python.exe` instead.
+
+## Minimal plugin
+
+```python
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mirabox_sdk import (
+    Action,
+    ActionRegistry,
+    JsonObject,
+    KeyDownEvent,
+    PluginLaunchArguments,
+    StreamDockPlugin,
+    StreamDockSender,
+    WebSocketStreamDockConnection,
+    WillAppearEvent,
+    run_plugin_cli,
+)
+
+ACTION_UUID = "com.example.counter.increment"
+
+
+@dataclass(frozen=True, slots=True)
+class Dependencies:
+    stream_dock: StreamDockSender
+
+
+registry: ActionRegistry[Dependencies] = ActionRegistry()
+
+
+@registry.register(ACTION_UUID)
+class CounterAction(Action[JsonObject, Dependencies]):
+    def _render(self) -> None:
+        count = self.settings.get("count", 0)
+        self.set_title(str(count if type(count) is int else 0))
+
+    def on_will_appear(self, _event: WillAppearEvent) -> None:
+        self._render()
+
+    def on_key_down(self, _event: KeyDownEvent) -> None:
+        count = self.settings.get("count", 0)
+        self.set_settings({"count": (count if type(count) is int else 0) + 1})
+        self._render()
+
+
+def build_application(arguments: PluginLaunchArguments) -> StreamDockPlugin[Dependencies]:
+    connection = WebSocketStreamDockConnection(arguments.port)
+    return StreamDockPlugin(
+        arguments,
+        stream_dock=connection,
+        action_registry=registry,
+        action_dependencies=Dependencies(connection),
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_plugin_cli(build_application))
+```
+
+The action UUID must also be declared in the plugin's `manifest.json`.
+
+## Property Inspector client
+
+Copy the versioned JavaScript client into the plugin bundle:
+
+```bash
+mirabox-sdk copy-property-inspector \
+  com.example.counter.sdPlugin/property-inspector
+```
+
+Use `--force` to replace a different existing copy. Include the client before
+the action-specific script:
+
+```html
+<script src="mirabox-sdk.js"></script>
+<script src="counter.js"></script>
+```
+
+The action script can use `window.MiraBoxPropertyInspector`:
+
+```javascript
+const client = window.MiraBoxPropertyInspector;
+client.on("connected", ({ settings }) => console.log(settings));
+client.sendToPlugin({ event: "refresh" });
+client.updateSettings({ mode: "toggle" });
+```
+
+## Public API
+
+- `events.py` contains typed inbound event models.
+- `commands.py` contains outbound command models.
+- `parser.py` validates wire JSON and reports exact invalid field paths.
+- `codecs.py` converts plugin-owned settings and messages to typed objects.
+- `Action` and `ActionRegistry` model action instances and registrations.
+- `StreamDockPlugin` dispatches events and manages service lifecycle.
+- `WebSocketStreamDockConnection` implements the Stream Dock transport.
+- `run_plugin_cli` handles the standard executable arguments and shutdown.
+
+The supported public surface is exported from `mirabox_sdk`. Other module-level
+objects are implementation details unless documented otherwise.
+
+## Checks
+
+```bash
+python -m unittest discover -s tests -v
+python -m compileall -q src tests scripts examples
+ruff check src tests scripts examples
+ruff format --check src tests scripts examples
+python -m build
+python scripts/verify_distribution.py dist
+```
+
+## Releasing
+
+1. Update the version in `pyproject.toml`, `src/mirabox_sdk/__init__.py`, and
+   `CHANGELOG.md`.
+2. Run all checks and build the distributions.
+3. Create and push the matching tag, for example `v0.1.0`.
+4. The release workflow publishes the wheel and source archive to PyPI through
+   Trusted Publishing and attaches them to a GitHub Release.
+
+## License
+
+[MIT](https://github.com/Nekit678/MiraboxStreamDockSDK/blob/main/LICENSE)

mirabox_stream_dock_sdk-0.1.0/README.md

@@ -0,0 +1,157 @@
+# MiraBox Stream Dock SDK for Python
+
+Typed, unofficial Python SDK for building plugins for MiraBox Stream Dock. It
+implements the WebSocket protocol, registration, typed event parsing, outbound
+commands, per-plugin action registration, action lifecycle, plugin services,
+and a shared Property Inspector client.
+
+This project is not affiliated with or endorsed by MiraBox, HotSpot, or Elgato.
+The `connectElgatoStreamDeckSocket` callback name is kept because Stream Dock
+uses it for Property Inspector compatibility.
+
+## Requirements
+
+- Python 3.11 or newer;
+- MiraBox Stream Dock 2.10.179.426 or newer;
+- Windows for packaging a Python plugin with PyInstaller.
+
+## Installation
+
+```bash
+python -m pip install mirabox-stream-dock-sdk
+```
+
+For SDK development:
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+```
+
+On Windows, use `.venv\Scripts\python.exe` instead.
+
+## Minimal plugin
+
+```python
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mirabox_sdk import (
+    Action,
+    ActionRegistry,
+    JsonObject,
+    KeyDownEvent,
+    PluginLaunchArguments,
+    StreamDockPlugin,
+    StreamDockSender,
+    WebSocketStreamDockConnection,
+    WillAppearEvent,
+    run_plugin_cli,
+)
+
+ACTION_UUID = "com.example.counter.increment"
+
+
+@dataclass(frozen=True, slots=True)
+class Dependencies:
+    stream_dock: StreamDockSender
+
+
+registry: ActionRegistry[Dependencies] = ActionRegistry()
+
+
+@registry.register(ACTION_UUID)
+class CounterAction(Action[JsonObject, Dependencies]):
+    def _render(self) -> None:
+        count = self.settings.get("count", 0)
+        self.set_title(str(count if type(count) is int else 0))
+
+    def on_will_appear(self, _event: WillAppearEvent) -> None:
+        self._render()
+
+    def on_key_down(self, _event: KeyDownEvent) -> None:
+        count = self.settings.get("count", 0)
+        self.set_settings({"count": (count if type(count) is int else 0) + 1})
+        self._render()
+
+
+def build_application(arguments: PluginLaunchArguments) -> StreamDockPlugin[Dependencies]:
+    connection = WebSocketStreamDockConnection(arguments.port)
+    return StreamDockPlugin(
+        arguments,
+        stream_dock=connection,
+        action_registry=registry,
+        action_dependencies=Dependencies(connection),
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_plugin_cli(build_application))
+```
+
+The action UUID must also be declared in the plugin's `manifest.json`.
+
+## Property Inspector client
+
+Copy the versioned JavaScript client into the plugin bundle:
+
+```bash
+mirabox-sdk copy-property-inspector \
+  com.example.counter.sdPlugin/property-inspector
+```
+
+Use `--force` to replace a different existing copy. Include the client before
+the action-specific script:
+
+```html
+<script src="mirabox-sdk.js"></script>
+<script src="counter.js"></script>
+```
+
+The action script can use `window.MiraBoxPropertyInspector`:
+
+```javascript
+const client = window.MiraBoxPropertyInspector;
+client.on("connected", ({ settings }) => console.log(settings));
+client.sendToPlugin({ event: "refresh" });
+client.updateSettings({ mode: "toggle" });
+```
+
+## Public API
+
+- `events.py` contains typed inbound event models.
+- `commands.py` contains outbound command models.
+- `parser.py` validates wire JSON and reports exact invalid field paths.
+- `codecs.py` converts plugin-owned settings and messages to typed objects.
+- `Action` and `ActionRegistry` model action instances and registrations.
+- `StreamDockPlugin` dispatches events and manages service lifecycle.
+- `WebSocketStreamDockConnection` implements the Stream Dock transport.
+- `run_plugin_cli` handles the standard executable arguments and shutdown.
+
+The supported public surface is exported from `mirabox_sdk`. Other module-level
+objects are implementation details unless documented otherwise.
+
+## Checks
+
+```bash
+python -m unittest discover -s tests -v
+python -m compileall -q src tests scripts examples
+ruff check src tests scripts examples
+ruff format --check src tests scripts examples
+python -m build
+python scripts/verify_distribution.py dist
+```
+
+## Releasing
+
+1. Update the version in `pyproject.toml`, `src/mirabox_sdk/__init__.py`, and
+   `CHANGELOG.md`.
+2. Run all checks and build the distributions.
+3. Create and push the matching tag, for example `v0.1.0`.
+4. The release workflow publishes the wheel and source archive to PyPI through
+   Trusted Publishing and attaches them to a GitHub Release.
+
+## License
+
+[MIT](https://github.com/Nekit678/MiraboxStreamDockSDK/blob/main/LICENSE)

mirabox_stream_dock_sdk-0.1.0/examples/counter_plugin/README.md

@@ -0,0 +1,29 @@
+# Counter example plugin
+
+This is a minimal binary Stream Dock plugin built with `mirabox-stream-dock-sdk`.
+Each press increments a persisted counter; the Property Inspector can reset it.
+
+From the SDK repository:
+
+```bash
+python -m pip install -e ".[dev]"
+mirabox-sdk copy-property-inspector \
+  examples/counter_plugin/com.example.counter.sdPlugin/property-inspector
+PYTHONPATH=examples/counter_plugin/src python -m counter_plugin \
+  -port 12345 \
+  -pluginUUID com.example.counter \
+  -registerEvent registerPlugin \
+  -info '{"application":{"language":"en","platform":"windows","platformVersion":"11","version":"2.10"},"colors":{},"devicePixelRatio":1,"devices":[],"plugin":{"uuid":"com.example.counter","version":"0.1.0"}}'
+```
+
+Build the Windows executable from the SDK virtual environment:
+
+```powershell
+python -m pip install pyinstaller
+python -m PyInstaller --clean --noconfirm examples/counter_plugin/build.spec
+Copy-Item dist\CounterPlugin.exe `
+  examples\counter_plugin\com.example.counter.sdPlugin\
+```
+
+Copy the `.sdPlugin` directory to
+`%APPDATA%\HotSpot\StreamDock\plugins\` and restart Stream Dock.

mirabox_stream_dock_sdk-0.1.0/examples/counter_plugin/build.spec

@@ -0,0 +1,35 @@
+# -*- mode: python ; coding: utf-8 -*-
+
+a = Analysis(
+    ["src/counter_plugin/__main__.py"],
+    pathex=["src"],
+    binaries=[],
+    datas=[],
+    hiddenimports=[],
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[],
+    noarchive=False,
+    optimize=0,
+)
+pyz = PYZ(a.pure)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    a.binaries,
+    a.datas,
+    [],
+    name="CounterPlugin",
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=False,
+    console=False,
+    disable_windowed_traceback=False,
+    argv_emulation=False,
+    target_arch=None,
+    codesign_identity=None,
+    entitlements_file=None,
+)

mirabox_stream_dock_sdk-0.1.0/examples/counter_plugin/com.example.counter.sdPlugin/assets/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128">
+  <rect width="128" height="128" rx="24" fill="#087DEA"/>
+  <path d="M64 30V98M30 64H98" stroke="#FFFFFF" stroke-width="14" stroke-linecap="round"/>
+</svg>

mirabox_stream_dock_sdk-0.1.0/examples/counter_plugin/com.example.counter.sdPlugin/manifest.json

@@ -0,0 +1,42 @@
+{
+  "Actions": [
+    {
+      "UUID": "com.example.counter.increment",
+      "Name": "Counter",
+      "Tooltip": "Increment a persisted counter",
+      "Icon": "assets/icon.svg",
+      "PropertyInspectorPath": "property-inspector/counter.html",
+      "SupportedInMultiActions": true,
+      "UserTitleEnabled": false,
+      "Controllers": [
+        "Keypad"
+      ],
+      "States": [
+        {
+          "Image": "assets/icon.svg",
+          "ShowTitle": true,
+          "TitleAlignment": "bottom",
+          "FontSize": "18"
+        }
+      ]
+    }
+  ],
+  "Version": "0.1.0",
+  "Name": "Counter",
+  "Icon": "assets/icon.svg",
+  "CategoryIcon": "assets/icon.svg",
+  "Category": "Examples",
+  "Description": "Minimal counter plugin built with mirabox-stream-dock-sdk",
+  "CodePath": "CounterPlugin.exe",
+  "SDKVersion": 1,
+  "Author": "Example Author",
+  "OS": [
+    {
+      "Platform": "windows",
+      "MinimumVersion": "11"
+    }
+  ],
+  "Software": {
+    "MinimumVersion": "2.10.179.426"
+  }
+}

mirabox_stream_dock_sdk-0.1.0/examples/counter_plugin/com.example.counter.sdPlugin/property-inspector/counter.html

@@ -0,0 +1,35 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Counter</title>
+    <style>
+      :root {
+        color-scheme: dark;
+        font-family: system-ui, sans-serif;
+      }
+
+      body {
+        margin: 16px;
+        color: #e8e8e8;
+        background: #2d2d2d;
+      }
+
+      button {
+        width: 100%;
+        padding: 8px;
+        color: inherit;
+        border: 1px solid #555;
+        border-radius: 4px;
+        background: #3a3a3a;
+        cursor: pointer;
+      }
+    </style>
+  </head>
+  <body>
+    <button id="reset" type="button" disabled>Reset counter</button>
+    <script src="mirabox-sdk.js"></script>
+    <script src="counter.js"></script>
+  </body>
+</html>

mirabox_stream_dock_sdk-0.1.0/examples/counter_plugin/com.example.counter.sdPlugin/property-inspector/counter.js

@@ -0,0 +1,14 @@
+(() => {
+  "use strict";
+
+  const client = window.MiraBoxPropertyInspector;
+  const reset = document.getElementById("reset");
+
+  client.on("connected", () => {
+    reset.disabled = false;
+  });
+
+  reset.addEventListener("click", () => {
+    client.sendToPlugin({ event: "reset" });
+  });
+})();