Telemersive Gateway is a desktop app for joining a telemersive-bus room — a shared MQTT-based session for routing video, audio, OSC, and motion-capture data between remote participants. It bridges local UltraGrid, OSC, and Motive devices into the room. It is a drop-in replacement for the Max MSP implementation of the Telemersive Gateway and is wire-compatible, so rooms mixing the two work.
On the repository name. The app was prototyped as Portbay; the product is Telemersive Gateway. The repository, its release URLs and the documentation site still use
telemersive-portbayso that existing links, downloads and the auto-updater keep working.
See docs/spec.md for the protocol and design specification, and CLAUDE.md for an architecture overview. User-facing documentation lives under docs/ and is published with MkDocs Material — see scripts/docs-screenshots/README.md for how its screenshots are generated.
- UltraGrid — video and audio relay (uses the UltraGrid CLI; located on first run)
- OSC — bidirectional OSC message relay
- StageControl — OSC variant for stage automation cues
- Mocap — Optitrack NatNet to OSC relay
- Motive Bridge — Optitrack NatNet protocol relay
- [Node.js] 18+ and [npm]
link to download and install Node.js and npm
Once Node.js and npm are installed, you can verify the installation by running the following commands in your terminal:
node -v
npm -vlink to download and install nvm -> nvm-setup.exe
- restart Powershell
nvm install lts # install latest LTS version
nvm use lts # activate it
node --version # verify
then set the execution policiy:
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
and confirm with [A]
npm -v # verify
then follow the instructions below to install and run the app.
Inside the terminal, cd to a directory where you want to have your local folder for the project, then run the following commands:
git clone https://github.com/telemersion/telemersive-portbay.git
cd telemersive-portbay
npm install
npm run devThis starts the electron-vite dev server with HMR for the renderer and live-reload for the main and preload processes. The app window opens automatically.
Use the in-app session UI to pick a room and join.
On first launch, open the Settings view and find the Tools & Compatibility section. The app checks whether UltraGrid and NatNetFour2OSC (currently Windows only) are installed at compatible versions and shows the status of each. For any tool marked missing or version-mismatched, use Download required build from official website ↗ to get the right version, then Locate… to point the app at the installed binary. The app validates the version and persists the path.
UltraGrid is needed for video/audio channels. NatNetFour2OSC v1.2.0 is needed for NatNet and Motive channels. OSC and StageControl channels need no external tools.
- src/main/ — Electron main process: MQTT client, device router, child-process handlers
- src/renderer/ — Vue 3 UI; reconstructs room state from the MQTT stream forwarded over IPC
- src/preload/ — thin IPC bridge between main and renderer
- src/shared/ — topic helpers and shared types
- tests/ — vitest suite with golden UG fixtures
- vendor/ultragrid/ — per-version UG installs (gitignored except for the README)
npm run typecheck— type-check main + renderer (vue-tsc --noEmit)npm test— run the full vitest suitenpx vitest run tests/main/devices/OscDevice.test.ts— run a single test filenpx vitest run tests/main/enumeration/parsers— run only the UG parser testsnpm run build— production build intoout/npm run preview— launch the built app fromout/without HMRnpm run docs:screenshots— regenerate the documentation screenshots from the live appnpm run docs:serve— serve the documentation site locally (needs.venv-docs, see below)
UltraGrid CLI output changes between versions, so the parsers in src/main/enumeration/parsers/ are version-coupled. Upgrading the vendored UltraGrid is a deliberate multi-step procedure — see docs/upgrading-ultragrid.md for the full runbook, and vendor/ultragrid/README.md for vendor layout details.
The user manual is built with MkDocs Material and published to GitHub Pages by
.github/workflows/docs.yml on every push to master.
python3.12 -m venv .venv-docs
.venv-docs/bin/pip install -r requirements-docs.txt
npm run docs:serve # http://127.0.0.1:8000
npm run docs:build # strict build, fails on broken linksScreenshots under docs/assets/screenshots/ are generated from the running app
by npm run docs:screenshots — no broker or second machine required. Re-run it
and commit the result whenever the UI changes.
Use npm version to bump both atomically:
npm version patch # 0.1.4 → 0.1.5 (bug fixes)
npm version minor # 0.1.4 → 0.2.0 (new features)
npm version major # 0.1.4 → 1.0.0 (breaking changes)This updates package.json, commits the change, and creates a matching git tag (e.g. v0.1.5). Then push both:
git push && git push --tagsTo build the installer locally:
npm run package # runs build + electron-builder → dist/Bugs and feature requests: GitHub Issues.
MIT. Copyright © 2024–2026 Martin Froehlich (maybites) for Immersive Art Space and Zürich University of the Arts (ZHdK). See LICENSE.
