VGT StreamBridge

Lightweight, privacy-first, zero-dependency WordPress plugin bridging public TikTok LIVE streams with PRISM Live Studio and OBS overlays.

VGT StreamBridge discovers public TikTok LIVE sessions directly from public room metadata and renders a clean, transparent, real-time event overlay designed specifically for PRISM Live Studio (Mobile & Desktop) and OBS Studio.

Built under strict VisionGaiaTechnology engineering standards: no third-party SaaS relays, no external cloud dependencies, no browser automation, no TikTok login credentials, and no external signing services.

---

Table of Contents

1. Key Highlights
2. Technical Architecture
3. Trust Boundaries & Security
4. Supported Realtime Events
5. Prerequisites
6. Installation & Setup
7. Guided Onboarding Wizard
8. PRISM Live Studio Integration Guide
9. OBS Studio Integration
10. TikTok Protocol & Signing Diagnostics
11. REST API Reference
12. Verification & Test Suite
13. Project Structure
14. License

---

Key Highlights

• 100% On-Premise & Same-Origin: Runs entirely on your own WordPress instance. Your stream data is never proxied through external servers or third-party cloud infrastructure.
• Zero Credentials Required: Never asks for TikTok passwords, session cookies, or TikTok Developer API keys. All discovery relies strictly on public web data.
• Direct Webcast Compatibility Probe: Tests direct public /webcast/im/fetch/ connectivity and clearly surfaces provider states (signing_required, rate_limited, offline) instead of silently failing.
• Dependency-Free Modern Protobuf Engine: Features a pure, bounded PHP wire-format protobuf decoder and event normalizer without external Composer packages.
• PRISM-Ready Transparent Overlay: Beautiful, responsive streaming overlay tailored for PRISM Live Studio Mobile (Web Widget), PRISM Desktop, and OBS browser sources.
• HMAC-SHA256 Token Protection: Overlay routes and REST endpoints are safeguarded by timing-safe HMAC bearer tokens bound to your installation identity and WordPress auth salts.
• Stream Stability: Bounded FIFO event buffers, 512-event sliding duplicate suppression, jittered exponential reconnect backoff, and heartbeat liveness tracking.
• 5-Step First-Run Onboarding: Automatic setup wizard on first activation that guides you through configuration, connectivity testing, and widget embedding.

---

Technical Architecture

VGT StreamBridge is built with strict domain boundaries and separation of concerns:

┌────────────────────────────────────────────────────────────────────────┐
│                        PRISM Live Studio / OBS                         │
│             (Web Page Widget / Transparent Browser Source)             │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Same-Origin HTTP / REST
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        WordPress Presentation                          │
│   ┌─────────────────────┐   ┌─────────────────┐   ┌────────────────┐   │
│   │ SetupWizard / Admin │   │ OverlayPage (UI)│   │ REST API (v1)  │   │
│   └──────────┬──────────┘   └────────┬────────┘   └────────┬───────┘   │
└──────────────┼───────────────────────┼─────────────────────┼───────────┘
               │                       ▼                     │
┌──────────────┼─────────────────────────────────────────────┼───────────┐
│              ▼             Application Layer               ▼           │
│   ┌────────────────────────────────────────────────────────────────┐   │
│   │ LiveDiscoveryService   •   RealtimeService                     │   │
│   └───────────────────────────────┬────────────────────────────────┘   │
└───────────────────────────────────┼────────────────────────────────────┘
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                              Domain Core                               │
│   ┌────────────────────────────────────────────────────────────────┐   │
│   │ TikTokUsername (VO)    •   ProtobufReader (Zero-dependency)    │   │
│   │ TikTokHtmlParser       •   WebcastEnvelopeDecoder              │   │
│   │ BoundedEventBuffer     •   TikTokEventNormalizer               │   │
│   └───────────────────────────────┬────────────────────────────────┘   │
└───────────────────────────────────┼────────────────────────────────────┘
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                         WordPress Infrastructure                       │
│   ┌────────────────────────────────────────────────────────────────┐   │
│   │ InstallationIdentity (HMAC)  •  TransientLiveStatusCache       │   │
│   │ SettingsRepository           •  OnboardingStateRepository      │   │
│   │ TikTokPublicPageClient       •  TikTokWebcastPollClient        │   │
│   └────────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────┘

Discovery Pipeline

1. Public Request: wp_safe_remote_get() fetches https://www.tiktok.com/@<username>/live with zero redirects, TLS verification, and strict response size caps.
2. Dual-Strategy Parser: TikTokHtmlParser parses JSON bootstrap structures (SIGI_STATE first, with __UNIVERSAL_DATA_FOR_REHYDRATION__ fallback) to discover room ID, room status, and owner details.
3. Transient Cache: Caches active room state to avoid aggressive upstream queries and protect your site from rate limiting.

Realtime Transport Pipeline

1. Direct Probe: Queries https://webcast.tiktok.com/webcast/im/fetch/ using public audience parameters.
2. Wire Protobuf Decoder: ProtobufReader decodes the binary response envelope with explicit length and depth bounds.
3. Event Normalization: TikTokEventNormalizer maps raw wire messages into structured domain events.
4. Client Event Bus: JavaScript runtime (realtime-core.js) manages polling intervals, backoff, and deduplication before passing events to the UI (overlay.js).

---

Trust Boundaries & Security

Trust Boundary	Protection Mechanism
Admin Input	TikTokUsername enforces strict username syntax ([a-zA-Z0-9_.-]), hostile inputs and control characters fail closed.
TikTok Network Data	Treated as untrusted hostile input. Size ceiling enforced before decoding. Recursive JSON & Protobuf depth is strictly bounded.
Overlay Access	Requires an HMAC-SHA256 bearer token (?token=...). Derived from WordPress AUTH_SALT and a cryptographically generated installation UUID; validated using hash_equals().
REST Endpoints	Read-only, GET-only, rate-limited via transients, and strictly token-authorized.
DOM Rendering	Dynamic content (chat text, user names) is strictly inserted via text nodes or validated sanitization. No innerHTML interpolation of remote data.
Content Security Policy	Sends strict CSP headers, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, and allows iframe embedding exclusively for broadcast tools while blocking untrusted external origins.

---

Supported Realtime Events

VGT StreamBridge decodes and normalizes the following TikTok Webcast events:

Event	Wire Message	Normalized Properties
Chat Message	WebcastChatMessage	User ID, display name, username, comment text, message ID, timestamp.
Gift	WebcastGiftMessage	Gifter details, gift ID, gift name, diamond/coin cost, repeat count, combo status.
Like	WebcastLikeMessage	Sender details, like count, cumulative total likes.
Follow	WebcastSocialMessage	Follower details, social action type (follow).
Share	WebcastSocialMessage	Sharer details, target platform, social action type (share).
Member Join	WebcastMemberMessage	Member details, join type (viewer, subscriber).
Stream End	WebcastControlMessage	Action codes 3 & 4 (stream terminated/suspended). Triggers overlay end-state transition.

---

Prerequisites

• WordPress: 6.4 or higher
• PHP: 8.1, 8.2, 8.3, or 8.4
• PHP Extensions: curl, json, hash, openssl, pcre
• Broadcast Software:
  • PRISM Live Studio (Mobile on iOS/Android or Desktop on Windows/macOS)
  • OR OBS Studio (29.0+)

---

Installation & Setup

Method 1: Upload via WordPress Admin (Recommended)

1. Download the latest vgt-streambridge-0.3.0.zip release from Releases.
2. Log in to your WordPress Admin dashboard.
3. Navigate to Plugins → Add New Plugin → Upload Plugin.
4. Choose the downloaded ZIP file and click Install Now.
5. Click Activate Plugin.
6. The Guided Setup Wizard will launch automatically.

Method 2: Manual / Composer-Free Installation

1. Clone or copy the vgt-streambridge folder into your WordPress plugins directory:

   cd wp-content/plugins/
   git clone https://github.com/visiongaiatechnology/streambridgetiktokprism.git vgt-streambridge

2. Navigate to wp-admin → Plugins and click Activate under VGT StreamBridge.

---

Guided Onboarding Wizard

Upon initial activation, StreamBridge automatically opens the 5-step guided setup wizard (also accessible anytime via VGT StreamBridge → Einrichtung):

1. Step 1 — Welcome & Privacy Principles
   Explains the trust boundary: StreamBridge never asks for passwords, credentials, or third-party signing keys.
2. Step 2 — TikTok Username
   Enter your TikTok handle (with or without @). The input is sanitized and stored.
3. Step 3 — Public LIVE Discovery Check
   Probes https://www.tiktok.com/@username/live to verify accessibility.
   • Note: An active LIVE stream is not required to complete setup. If you are currently offline, the wizard records your configuration and lets you proceed.
4. Step 4 — PRISM Live Studio Web Widget Setup
   Presents your unique, token-authenticated overlay URL with one-click copy and an in-browser diagnostic test link.
5. Step 5 — Readiness Verification
   Validates your installation identity, token health, and settings, marking onboarding complete.

---

PRISM Live Studio Integration Guide

PRISM Live Studio Mobile (iOS / Android)

VGT StreamBridge is tailored specifically for mobile live streaming via PRISM:

1. Open the PRISM Live Studio app on your phone.
2. Set your broadcast destination (e.g., TikTok, YouTube, or Custom RTMP).
3. Swipe or tap to enter Live Mode.
4. Tap the My Studio icon in the bottom toolbar.
5. Select Widget → Web Page (Web Browser Widget).
6. In the URL field, paste your VGT StreamBridge Overlay URL:

   https://your-domain.com/vgt-streambridge-overlay/?token=YOUR_HMAC_TOKEN

7. Set the preferred display area and tap Save.
8. Position and resize the chat widget anywhere on your vertical canvas (9:16).
9. The overlay automatically renders chat messages, likes, and gifts with a transparent background.

[!TIP] Refer to the official PRISM documentation for detailed visual steps:
PRISM Guide: Using the Web Browser Widget

Diagnostic Mode in PRISM

To test whether PRISM can communicate with your WordPress site before you go live, append &diagnostic=1 to the overlay URL:

https://your-domain.com/vgt-streambridge-overlay/?token=YOUR_HMAC_TOKEN&diagnostic=1

This renders an on-screen status HUD displaying room status, polling frequency, connection latency, and received event counters.

---

OBS Studio Integration

1. In OBS Studio, locate the Sources dock for your Scene.
2. Click + (Add Source) and select Browser.
3. Name the source (e.g., TikTok StreamBridge).
4. Configure the source:
   • URL: Your StreamBridge Overlay URL (https://your-domain.com/vgt-streambridge-overlay/?token=...)
   • Width: 450 (for a compact chat column) or 1080 (for full vertical canvas).
   • Height: 800 (or 1920).
   • Custom Frame Rate: 60 FPS (recommended for smooth animations).
   • Check Shutdown source when not visible (saves background CPU).
5. Click OK. The transparent overlay will now display on your OBS canvas.

---

TikTok Protocol & Signing Diagnostics

The Direct Webcast Boundary

TikTok's live webcast endpoint (https://webcast.tiktok.com/webcast/im/fetch/) periodically introduces or enforces anti-scraping parameters (such as _signature, X-Bogus, X-Gnarly, or JS challenges).

VGT StreamBridge maintains a firm architectural policy:

• No Reverse-Engineered Signature Bypass: The plugin will never execute unsafe JS sandbox hacks or ship obfuscated binary signing tools.
• No Third-Party Signer Proxies: It will never forward your visitors or stream data to shady external subscription signing services.

Compatibility States

When you run Echtzeit-Gate testen (Realtime Gate Diagnostic) in the WordPress admin:

• Eventkanal PASS: TikTok accepted the direct public audience poll and returned valid protobuf event envelopes.
• signing_required: TikTok requested browser-level verification or cryptographic signatures for that room. StreamBridge captures this as a typed compatibility result, protecting your server from crashes or IP bans.
• rate_limited: Upstream rate limit active. The plugin automatically waits for the cooldown period before retrying.

---

REST API Reference

All endpoints are registered under /wp-json/vgt-streambridge/v1.

1. Check Stream Status

GET /wp-json/vgt-streambridge/v1/status?token=<HMAC_TOKEN>&force=0

Response (200 OK)

{
  "is_live": true,
  "room_id": "7412345678901234567",
  "state": "LIVE",
  "source": "SIGI_STATE",
  "checked_at": 1727372800,
  "username": "example_creator"
}

2. Poll Realtime Events

GET /wp-json/vgt-streambridge/v1/events?token=<HMAC_TOKEN>&cursor=<CURSOR_VALUE>&limit=50

Response (200 OK)

{
  "events": [
    {
      "id": "741234567890_chat_1",
      "type": "chat",
      "timestamp": 1727372805,
      "user": {
        "id": "12345678",
        "username": "fan123",
        "nickname": "Super Fan"
      },
      "text": "Hello from PRISM Live!"
    }
  ],
  "cursor": "4096_continuation_token",
  "status": "connected"
}

---

Verification & Test Suite

VGT StreamBridge includes a comprehensive, dependency-free test suite covering domain rules, protobuf decoding, contract enforcement, and WordPress hooks.

Running Tests Locally

Run the complete test suite with PHP and Node.js:

# 1. Domain, Parser, Protobuf & Realtime Service Tests
php tests/run.php

# 2. WordPress Bootstrap & Hook Smoke Verification
php tests/wp-bootstrap-smoke.php

# 3. First-Run Onboarding Lifecycle Tests
php tests/onboarding-activation.php
php tests/onboarding-redirect.php
php tests/onboarding-state.php
php tests/setup-wizard-render.php

# 4. REST & Transport Contract Tests
php tests/rest-contract.php
php tests/wp-transport-contract.php

# 5. JavaScript Core & Overlay DOM Runtime Tests
node tests/realtime-core.test.js
node tests/overlay-runtime.test.js

One-Liner Test Execution

php tests/run.php && php tests/wp-bootstrap-smoke.php && node tests/realtime-core.test.js && node tests/overlay-runtime.test.js

All tests execute in sub-second time without requiring an active database or network connection.

---

Project Structure

vgt-streambridge/
├── ARCHITECTURE.md                 # Detailed architectural boundaries & design notes
├── LICENSE                         # GNU Affero General Public License v3.0 (AGPLv3)
├── MANIFEST.sha256                 # Cryptographic SHA-256 manifest of all project files
├── Next.md                         # VGT quality gate status & handoff documentation
├── README.md                       # Comprehensive English project guide & reference
├── readme.txt                      # WordPress.org standard metadata file
├── index.php                       # Silent directory protection
├── uninstall.php                   # Complete WordPress uninstallation cleanup
├── vgt-streambridge.php            # Primary plugin entry point & autoloader
├── assets/
│   ├── css/
│   │   ├── admin.css               # Admin dashboard styles
│   │   ├── overlay.css             # Transparent broadcast overlay styles
│   │   └── setup.css               # 5-step onboarding wizard layout
│   └── js/
│       ├── admin.js                # Admin page interactions (copy to clipboard, diagnostics)
│       ├── overlay.js              # Broadcast overlay DOM renderer & animations
│       └── realtime-core.js        # Bounded event polling, dedupe & reconnect loop
├── docs/
│   ├── PROTOCOL-NOTES.md           # TikTok Webcast wire protocol specifications
│   ├── RUNTIME-GATE.md             # Manual & production verification checklist
│   ├── SETUP-GUIDE.md              # German guided setup documentation
│   ├── VERIFICATION-MATRIX.md      # Gate-by-gate testing matrix
│   └── WORDPRESS-RUNTIME-EVIDENCE.md # Verified runtime test proof on official WP develop
├── src/
│   ├── Plugin.php                  # Main plugin orchestrator & lifecycle hooks
│   ├── Application/                # Application services & service interfaces
│   │   ├── LiveDiscoveryService.php
│   │   ├── LiveStatusCacheInterface.php
│   │   ├── PublicPageClientInterface.php
│   │   ├── RealtimeService.php
│   │   └── WebcastPollClientInterface.php
│   ├── Domain/                     # Zero-dependency domain models & protobuf decoder
│   │   ├── Exception/              # Typed domain exception hierarchy
│   │   ├── Live/                   # Discovery models & HTML parser
│   │   └── Realtime/               # Protobuf reader, envelope decoder, event normalizer
│   ├── Infrastructure/WordPress/   # Concrete WordPress adapters (transients, HTTP API, auth)
│   │   ├── InstallationIdentity.php
│   │   ├── OnboardingStateRepository.php
│   │   ├── SettingsRepository.php
│   │   ├── TikTokPublicPageClient.php
│   │   ├── TransientLiveStatusCache.php
│   │   └── WebcastPollClient.php
│   └── Presentation/               # Admin pages, setup wizard, overlay page & REST controllers
│       ├── Admin/                  # Admin page & SetupWizard UI
│       ├── Overlay/                # Transparent overlay template
│       └── Rest/                   # Status & Realtime event endpoints
└── tests/                          # Executable test harnesses & fixtures
    ├── fixtures/                   # Representative HTML & wire payload fixtures
    ├── onboarding-activation.php
    ├── onboarding-redirect.php
    ├── onboarding-state.php
    ├── overlay-runtime.test.js
    ├── realtime-core.test.js
    ├── rest-contract.php
    ├── run.php
    ├── setup-wizard-render.php
    ├── wp-bootstrap-smoke.php
    └── wp-transport-contract.php

---

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

See the LICENSE file for the full license text.

Copyright (C) 2026 VisionGaiaTechnology. All rights reserved.