{"_id":"@blorkfield/obs-overlay","_rev":"2-cd57199c122facf1266ccf679b107460","name":"@blorkfield/obs-overlay","dist-tags":{"latest":"0.5.1"},"versions":{"0.4.0":{"name":"@blorkfield/obs-overlay","version":"0.4.0","license":"GPL-3.0-only","_id":"@blorkfield/obs-overlay@0.4.0","maintainers":[{"name":"blorkfield_user","email":"meier_steven@yahoo.com"}],"dist":{"shasum":"4ca4c30b70482ea7498d66ca8f6bb14f5afe283a","tarball":"https://registry.npmjs.org/@blorkfield/obs-overlay/-/obs-overlay-0.4.0.tgz","fileCount":168,"integrity":"sha512-8taED5IRphOEeOzgRXcaMhw/p3LM8/biZupPpBNpaiE/slYCKB5pHftUbBXNq9s90DhH+s4nLYxWEXE+LgqX5w==","signatures":[{"sig":"MEUCIQC7sxtHEYBOnRdMiPfZgldb/mm5cEbXZsNgckhPGcWi5AIgCB2pmItv+FVlWfObWjCoeQSoHe/T66YY+IrT8MgwAY8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":12019471},"type":"module","gitHead":"8a038346160c158c91554ef926688e1f95c06f04","scripts":{"dev":"pnpm build && vite","build":"tsc && vite build","start":"node server/index.js","preview":"vite preview","typecheck":"tsc --noEmit"},"_npmUser":{"name":"blorkfield_user","email":"meier_steven@yahoo.com"},"_npmVersion":"11.10.0","description":"Physics-based streaming overlay with OBS Studio integration. Built on [@blorkfield/overlay-core](https://github.com/Blorkfield/overlay-core).","directories":{},"_nodeVersion":"25.6.0","dependencies":{"ws":"^8.19.0","express":"^4.22.1","obs-websocket-js":"^5.0.7","@blorkfield/blork-tabs":"^0.4.0","@blorkfield/overlay-core":"^0.8.10","@blorkfield/twitch-integration":"^0.6.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.28.2","devDependencies":{"vite":"^6.4.1","@types/ws":"^8.18.1","typescript":"^5.9.3","@types/express":"^4.17.25","@changesets/cli":"^2.29.8"},"_npmOperationalInternal":{"tmp":"tmp/obs-overlay_0.4.0_1773452263630_0.40126000743208357","host":"s3://npm-registry-packages-npm-production"}},"0.5.1":{"name":"@blorkfield/obs-overlay","version":"0.5.1","license":"GPL-3.0","repository":{"type":"git","url":"git+https://github.com/Blorkfield/obs-overlay.git"},"packageManager":"pnpm@10.28.2","type":"module","publishConfig":{"access":"public"},"scripts":{"dev":"pnpm build && vite","build":"tsc && vite build","preview":"vite preview","start":"node server/index.js","typecheck":"tsc --noEmit"},"dependencies":{"@blorkfield/blork-tabs":"^0.4.0","@blorkfield/overlay-core":"^0.11.0","@blorkfield/twitch-integration":"^0.6.1","express":"^4.22.1","obs-websocket-js":"^5.0.7","ws":"^8.19.0"},"devDependencies":{"@changesets/cli":"^2.29.8","@types/express":"^4.17.25","@types/ws":"^8.18.1","typescript":"^5.9.3","vite":"^6.4.1"},"gitHead":"4dd86837b3e6ab9ecbc850a7e98372a7f39ac49e","_id":"@blorkfield/obs-overlay@0.5.1","description":"Physics-based streaming overlay with OBS Studio integration. Built on [@blorkfield/overlay-core](https://github.com/Blorkfield/overlay-core).","bugs":{"url":"https://github.com/Blorkfield/obs-overlay/issues"},"homepage":"https://github.com/Blorkfield/obs-overlay#readme","_nodeVersion":"22.22.1","_npmVersion":"11.11.1","dist":{"integrity":"sha512-0fCO0qqudrafrcKFSSGmWhwc4nu9SC1HojdcLUDhRQDNhkYLKo+eoGka6AwoqgkADeEyAGMVwagT5sFhU0tPdw==","shasum":"afb5de56597af57eaef11a669aa20da691e08cb5","tarball":"https://registry.npmjs.org/@blorkfield/obs-overlay/-/obs-overlay-0.5.1.tgz","fileCount":168,"unpackedSize":12015182,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@blorkfield%2fobs-overlay@0.5.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDBc8VCR0kjptaDo2ipe7BbJf0yL2ro9Q3gyI+hDMXrzwIhAMD6QhjkLuN4+wKOuspiystLYENyVcQn+5i/U98p/wFN"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:18cf4e57-99a5-48ec-9f6c-d5688fac6831"}},"directories":{},"maintainers":[{"name":"blorkfield_user","email":"meier_steven@yahoo.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/obs-overlay_0.5.1_1773453883691_0.8319821150574194"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-14T01:37:43.571Z","modified":"2026-03-14T02:04:44.340Z","0.4.0":"2026-03-14T01:37:43.967Z","0.5.1":"2026-03-14T02:04:44.050Z"},"license":"GPL-3.0","description":"Physics-based streaming overlay with OBS Studio integration. Built on [@blorkfield/overlay-core](https://github.com/Blorkfield/overlay-core).","maintainers":[{"name":"blorkfield_user","email":"meier_steven@yahoo.com"}],"readme":"# @blorkfield/obs-overlay\n\nPhysics-based streaming overlay with OBS Studio integration. Built on [@blorkfield/overlay-core](https://github.com/Blorkfield/overlay-core).\n\n## Features\n\n- **Physics simulation** - Matter.js powered gravity, collisions, and pressure collapse\n- **OBS integration** - WebSocket connection for scene changes, stream/recording status\n- **Mouse tracking** - System-wide mouse capture via OBS script (position and button states)\n- **Entity system** - Spawn physics objects with customizable images, tags, TTL, and weight\n- **Text obstacles** - Add text as physical obstacles with TTF font support\n- **Effects** - Configurable burst, rain, and stream particle effects\n- **Grabbing** - Click and drag entities around the scene\n- **Panel UI** - Draggable, collapsible, auto-hiding panels via [@blorkfield/blork-tabs](https://github.com/Blorkfield/blork-tabs)\n- **Event debugging** - Embedded event log with hover-to-enlarge for easy debugging in OBS\n\n## Quick Start\n\n### Development\n\n```bash\npnpm install\npnpm dev\n```\n\nOverlay runs at http://localhost:5173\n\n### Docker\n\n```bash\ndocker compose up\n```\n\nOverlay runs at http://localhost:5173 (dev) or http://localhost:80 (production)\n\n## OBS Setup\n\n### 1. Browser Source\n\n1. Add a new **Browser Source** in OBS\n2. Set URL to `http://localhost:5173?panels=hidden` (dev) or your production URL with the same parameter\n3. Set dimensions to match your canvas (e.g., 1920x1080)\n4. Enable transparency if desired\n\n> **Tip:** Use `?panels=hidden` in the OBS browser source URL to hide the control panels in your stream. To configure the overlay, open `http://localhost:5173?panels=visible` in a regular browser window to keep panels always visible while adjusting settings.\n\n### 2. WebSocket Connection\n\n1. In OBS: **Tools > WebSocket Server Settings**\n2. Enable the WebSocket server (default port: 4455)\n3. Set a password if desired\n4. In the overlay's Connection panel, enter the WebSocket address and connect\n\n### 3. Mouse Capture Script\n\nThe overlay tracks your system mouse position via an OBS script. This captures mouse coordinates relative to your screen display - not browser interaction.\n\n#### Install Python Dependencies\n\n**Arch Linux (AUR):**\n```bash\nyay -S python-pynput python-websocket-client\n```\n\n**Debian/Ubuntu:**\n```bash\nsudo apt install python3-pynput python3-websocket\n```\n\n**Fedora:**\n```bash\nsudo dnf install python3-pynput python3-websocket-client\n```\n\n**macOS/Windows/Other (pip):**\n```bash\npip install pynput websocket-client\n```\n\n#### Configure OBS Python Path\n\n1. In OBS: **Tools > Scripts > Python Settings**\n2. Set the Python install path:\n   - **Arch Linux:** `/usr` (not the full python3 path)\n   - **Debian/Ubuntu:** `/usr`\n   - **Fedora:** `/usr`\n   - **macOS (Homebrew):** `/opt/homebrew/Frameworks/Python.framework/Versions/3.x` or `/usr/local/Cellar/python@3.x/...`\n   - **Windows:** `C:\\Python311` or your Python install directory\n\n   > **Note:** On Linux, OBS expects the prefix directory (e.g., `/usr`), not the python binary path. OBS will look for `lib/python3.x/` under this path.\n\n#### Add the Script\n\n1. In OBS: **Tools > Scripts**\n2. Click **+** and select `obs-scripts/mouse_capture.py` from this repository\n3. Configure the script settings:\n   - **Overlay WebSocket URL**: `ws://localhost:5173/mouse?source=obs`\n   - **Enable mouse capture**: checked\n   - **Send interval**: 16ms (~60fps, adjust if needed)\n\nThe script connects automatically when OBS starts. Check **Script Log** for connection status.\n\n## Architecture\n\n```\nYour Mouse (system-wide)\n    │\n    ▼\nOBS Script (mouse_capture.py)\n    │ pynput captures position\n    ▼\nWebSocket ───────────────────► Overlay (browser source)\n    ws://localhost:PORT/mouse     │ receives & displays\n                                  ▼\n                             OBS Scene\n```\n\nMouse data flows from the OBS script (running inside OBS) through WebSocket to the overlay. No separate background process required - the script runs within OBS itself.\n\n## Panels\n\nAll panels auto-hide after 5 seconds of inactivity and reappear on mouse/keyboard activity. This keeps the overlay clean during streams while remaining accessible for configuration.\n\n| Panel | Description |\n|-------|-------------|\n| **OBS Connection** | Connect to OBS WebSocket server |\n| **Settings** | Debug mode, log level, background color, mouse capture offset/scale |\n| **Entity Management** | Spawn entities and text obstacles, manage tags |\n| **Effects** | Configure burst, rain, and stream effects |\n| **Event Detection** | Live mouse position, button states, OBS events, and event log |\n\n### Event Log\n\nThe Event Detection panel includes an embedded event log for debugging click/grab events. Hover over the log for 3 seconds to enlarge it to 75% of the screen for easier reading—useful when debugging in OBS browser sources without console access.\n\n## Configuration\n\nSettings persist to browser localStorage. When used as an OBS Browser Source, config survives OBS restarts.\n\n### URL Parameters\n\n| Parameter | Value | Description |\n|-----------|-------|-------------|\n| `panels` | `hidden` | Completely hides all panels and stats (use for OBS browser source) |\n| `panels` | `visible` | Disables auto-hide, keeps panels always visible |\n\n**Examples:**\n- `http://localhost:5173?panels=hidden` — Production/streaming (no UI)\n- `http://localhost:5173?panels=visible` — Configuration (panels always visible)\n- `http://localhost:5173` — Default (panels auto-hide after 5 seconds)\n\n### Mouse Capture Calibration\n\nIf mouse coordinates from the OBS script don't align with your overlay (e.g., multi-monitor setups, scaled displays), use the **Mouse Capture Offset** settings:\n\n| Setting | Description |\n|---------|-------------|\n| **Offset X/Y** | Pixel offset to subtract from raw coordinates |\n| **Scale X/Y** | Multiplier for coordinate scaling (default: 1.0) |\n\nThe transformation applied is: `canvas_pos = (raw_pos - offset) * scale`\n\n## Development\n\n```bash\npnpm install      # Install dependencies\npnpm dev          # Start dev server with hot reload\npnpm build        # Build for production\npnpm start        # Run production server (after build)\npnpm typecheck    # Run TypeScript checks\n```\n\n## CI/CD\n\nThis project uses shared workflows from [blork-infra](https://github.com/Blorkfield/blork-infra).\n\n### Automated Pipeline\n\n1. **Push to feature branch** (e.g., `feat/add-new-effect`)\n   - Auto-PR workflow creates a PR and changeset based on branch prefix\n   - Branch naming: `feat/`, `fix/`, `chore/`, `docs/`, `refactor/`, `perf/`, `test/`, `breaking/`\n\n2. **PR to main**\n   - CI runs build and typecheck\n   - Auto-merges on success (squash + delete branch)\n\n3. **Merge to main with changesets**\n   - Creates a release PR to version the package\n\n4. **Release PR merges**\n   - Builds and pushes Docker image to `ghcr.io/blorkfield/obs-overlay`\n\n### Manual Publish\n\nTrigger a manual publish via GitHub Actions > Publish > Run workflow.\n\n## Requirements\n\n- Node.js 22+\n- pnpm\n- OBS Studio 28+ (includes WebSocket server)\n- Python 3.x with `pynput` and `websocket-client`\n\n## License\n\nGPL-3.0\n","readmeFilename":"README.md","homepage":"https://github.com/Blorkfield/obs-overlay#readme","repository":{"type":"git","url":"git+https://github.com/Blorkfield/obs-overlay.git"},"bugs":{"url":"https://github.com/Blorkfield/obs-overlay/issues"}}