Build a TikTok LIVE Stream Overlay for OBS with Node.js

#javascript #tiktok #obs #tutorial

Custom stream overlays that react to real-time TikTok events — gifts, chat, viewer counts. Here's how to build one with Node.js and a transparent HTML page as an OBS Browser Source.

Architecture

TikTok LIVE → tiktok-live-api (WebSocket) → Node.js Server → Local WebSocket → OBS Browser Source

Step 1: Set Up

mkdir tiktok-overlay && cd tiktok-overlay
npm init -y
npm install tiktok-live-api ws express
mkdir public

Step 2: Server

Create server.mjs:

// server.mjs
import { TikTokLive } from 'tiktok-live-api';
import { WebSocketServer } from 'ws';
import express from 'express';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

const __dirname = dirname(fileURLToPath(import.meta.url));
const app = express();
app.use(express.static(join(__dirname, 'public')));
app.listen(3000, () => console.log('Overlay at http://localhost:3000'));

const wss = new WebSocketServer({ port: 8080 });
const client = new TikTokLive('USERNAME_HERE', {
  apiKey: 'YOUR_API_KEY'
});

// Forward all TikTok events to overlay via local WebSocket
client.on('event', (event) => {
  const data = JSON.stringify(event);
  for (const ws of wss.clients) {
    ws.send(data);
  }
});

client.on('connected', () => console.log('✅ Connected to TikTok'));

client.on('chat', (e) => {
  console.log(`💬 ${e.user.uniqueId}: ${e.comment}`);
});

client.on('gift', (e) => {
  console.log(`🎁 ${e.user.uniqueId} sent ${e.giftName} (${e.diamondCount} 💎)`);
});

client.connect();

Step 3: Overlay HTML

Create public/index.html:

<!DOCTYPE html>
<html>
<head>
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body {
      background: transparent;
      font-family: 'Segoe UI', sans-serif;
      color: white;
      overflow: hidden;
    }
    #alerts {
      position: fixed; top: 20px; right: 20px;
      width: 350px;
    }
    .alert {
      background: rgba(0,0,0,0.8);
      border-left: 4px solid #ff0050;
      padding: 12px 16px;
      margin-bottom: 8px;
      border-radius: 8px;
      animation: slideIn 0.3s ease-out, fadeOut 0.5s ease-in 4.5s;
      animation-fill-mode: forwards;
    }
    .alert.gift { border-color: #ffd700; }
    .alert .user { color: #ff0050; font-weight: bold; }
    .alert .diamonds { color: #ffd700; }
    #viewers {
      position: fixed; bottom: 20px; right: 20px;
      background: rgba(0,0,0,0.8);
      padding: 8px 16px;
      border-radius: 20px;
      font-size: 18px;
    }
    @keyframes slideIn {
      from { transform: translateX(100%); opacity: 0; }
      to { transform: translateX(0); opacity: 1; }
    }
    @keyframes fadeOut {
      to { opacity: 0; transform: translateY(-20px); }
    }
  </style>
</head>
<body>
  <div id="alerts"></div>
  <div id="viewers">👀 0</div>
  <script>
    const ws = new WebSocket('ws://localhost:8080');
    const alerts = document.getElementById('alerts');

    ws.onmessage = (e) => {
      const msg = JSON.parse(e.data);
      const d = msg.data || {};
      const user = d.user?.uniqueId || '';

      switch (msg.event) {
        case 'chat':
          addAlert(
            `<span class="user">@${user}</span>: ${d.comment}`
          );
          break;
        case 'gift':
          addAlert(
            `<span class="user">@${user}</span> sent ${d.giftName} ` +
            `<span class="diamonds">(${d.diamondCount} 💎)</span>`,
            'gift'
          );
          break;
        case 'follow':
          addAlert(
            `<span class="user">@${user}</span> followed! ➕`
          );
          break;
        case 'roomUserSeq':
          document.getElementById('viewers').textContent =
            `👀 ${d.viewerCount}`;
          break;
      }
    };

    function addAlert(html, type = '') {
      const div = document.createElement('div');
      div.className = `alert ${type}`;
      div.innerHTML = html;
      alerts.prepend(div);
      setTimeout(() => div.remove(), 5000);
      while (alerts.children.length > 5)
        alerts.lastChild.remove();
    }
  </script>
</body>
</html>

Step 4: Run It

node server.mjs

Open http://localhost:3000 in your browser — you'll see the overlay with alerts sliding in from the right.

Step 5: Add to OBS

In OBS, add a Browser Source
Set URL to http://localhost:3000
Set size to 1920×1080 (or match your canvas)
Check "Shutdown source when not visible"
The background is transparent — alerts overlay on top of your stream

Chat shows as red-bordered alerts
Gifts show as gold-bordered alerts with diamond values
Viewer count stays in the bottom-right corner

How It Works

The tiktok-live-api package connects to TikTok via a managed WebSocket API. Your server receives typed JSON events and forwards them to the browser overlay via a local WebSocket. The overlay renders alerts with CSS animations.

This was tested live on gbnews — chat messages, gifts, and viewer counts all flow through in real-time.

Links

Free tier: 50 requests/day, 1 WebSocket connection — enough to build and test your overlay.

DEV Community