Build a TikTok LIVE Stream Overlay for OBS with Node.js
Published: (March 15, 2026 at 08:03 PM EDT)
4 min read
Source: Dev.to
Source: Dev.to
Overview
Create a custom OBS overlay that reacts in real‑time to TikTok LIVE events such as chat messages, gifts, follows, and viewer count. The architecture is:
TikTok LIVE → tiktok-live-api (WebSocket) → Node.js server → Local WebSocket → OBS Browser SourceSetup
mkdir tiktok-overlay && cd tiktok-overlay
npm init -y
npm install tiktok-live-api ws express
mkdir publicServer (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 the overlay via the 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();Run the server:
node server.mjsFront‑end Overlay (public/index.html)
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>TikTok Live Overlay</title>
<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(`@${user}: ${d.comment}`);
break;
case 'gift':
addAlert(`@${user} sent ${d.giftName} (${d.diamondCount} 💎)`, 'gift');
break;
case 'follow':
addAlert(`@${user} 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>Open http://localhost:3000 in a browser to verify that alerts appear and the viewer count updates.
Adding the Overlay to OBS
Add a Browser Source
- URL:
http://localhost:3000 - Size:
1920×1080(or match your canvas) - Check Shutdown source when not visible
- URL:
The background is transparent, so alerts overlay directly on your stream.
- Chat messages appear as red‑bordered alerts.
- Gifts appear as gold‑bordered alerts with diamond values.
- Viewer count stays in the bottom‑right corner.
How It Works
tiktok-live-apimaintains a WebSocket connection to TikTok and emits typed JSON events.- The Node.js server forwards every event to any connected local WebSocket client (the overlay page).
- The browser source receives the events, updates the DOM, and uses CSS animations for smooth visual feedback.
Resources
- 📦 tiktok-live-api on npm
- 🐍 Python version on PyPI
- 📖 Full documentation
- 💬 Discord community
Free tier: 50 requests/day, 1 WebSocket connection — sufficient for development and testing.