What You'll Build
A browser-based stream overlay that works with OBS, Streamlabs, or any software that supports browser sources. It displays:
- Live chat messages in real-time
- Animated gift alerts with diamond values
- Current viewer count
- A scrolling chat feed with user avatars
Prerequisites
- Node.js 18+ installed
- A free TikTool Live API key — get one here
- OBS Studio (or any streaming software with Browser Source)
Step 1: Set Up the Project
mkdir tiktok-overlay && cd tiktok-overlay
npm init -y
npm install @tiktool/live expressStep 2: Create the Server
Create server.mjs — this connects to TikTok and broadcasts events via Server-Sent Events (SSE) to the browser overlay:
import express from 'express'
import { TikTokLive } from '@tiktool/live'
const app = express()
const clients = new Set()
// Serve the overlay HTML
app.get('/', (req, res) => {
res.sendFile('overlay.html', { root: '.' })
})
// SSE endpoint for real-time events
app.get('/events', (req, res) => {
res.writeHead(200, {
'Content-Type': 'text/event-stream',
'Cache-Control': 'no-cache',
Connection: 'keep-alive',
})
clients.add(res)
req.on('close', () => clients.delete(res))
})
function broadcast(event, data) {
for (const client of clients) {
client.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)
}
}
// Connect to TikTok LIVE
const tiktok = new TikTokLive({
uniqueId: process.env.STREAMER || 'tv_asahi_news',
apiKey: process.env.TIKTOOL_API_KEY
})
tiktok.on('chat', (e) => broadcast('chat', {
user: e.nickname, comment: e.comment, avatar: e.profilePictureUrl
}))
tiktok.on('gift', (e) => broadcast('gift', {
user: e.nickname, gift: e.giftName, diamonds: e.diamondCount
}))
tiktok.on('viewer_count', (e) => broadcast('viewers', {
count: e.viewerCount
}))
await tiktok.connect()
app.listen(3333, () => console.log('Overlay: http://localhost:3333'))Step 3: Create the Overlay HTML
Create overlay.html — this is what OBS will render as a browser source:
<!DOCTYPE html>
<html>
<head>
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: 'Inter', sans-serif;
background: transparent;
overflow: hidden;
}
.chat-feed {
position: fixed; bottom: 20px; left: 20px;
width: 360px; max-height: 400px;
display: flex; flex-direction: column-reverse;
gap: 6px; overflow: hidden;
}
.chat-msg {
background: rgba(0, 0, 0, 0.6);
border-radius: 8px; padding: 8px 12px;
color: #fff; font-size: 14px;
animation: slideIn 0.3s ease;
}
.chat-msg .user { color: #a78bfa; font-weight: 600; }
.gift-alert {
position: fixed; top: 50%; left: 50%;
transform: translate(-50%, -50%);
background: rgba(0, 0, 0, 0.8);
border: 2px solid #f59e0b;
border-radius: 16px; padding: 24px 40px;
text-align: center; color: #fff;
animation: popIn 0.5s ease;
display: none;
}
.gift-alert.show { display: block; }
.gift-alert .gift-name { font-size: 28px; font-weight: 800; }
.gift-alert .gift-user { font-size: 16px; color: #94a3b8; }
.gift-alert .gift-diamonds { font-size: 18px; color: #f59e0b; }
.viewer-count {
position: fixed; top: 20px; right: 20px;
background: rgba(0, 0, 0, 0.6);
border-radius: 8px; padding: 8px 16px;
color: #fff; font-size: 14px; font-weight: 600;
}
@keyframes slideIn {
from { opacity: 0; transform: translateY(10px); }
to { opacity: 1; transform: translateY(0); }
}
@keyframes popIn {
0% { opacity: 0; transform: translate(-50%, -50%) scale(0.5); }
100% { opacity: 1; transform: translate(-50%, -50%) scale(1); }
}
</style>
</head>
<body>
<div class="chat-feed" id="chat"></div>
<div class="gift-alert" id="gift">
<div class="gift-name" id="gift-name"></div>
<div class="gift-user" id="gift-user"></div>
<div class="gift-diamonds" id="gift-diamonds"></div>
</div>
<div class="viewer-count" id="viewers">👁 0</div>
<script>
const chat = document.getElementById('chat')
const gift = document.getElementById('gift')
const src = new EventSource('/events')
src.addEventListener('chat', (e) => {
const d = JSON.parse(e.data)
const el = document.createElement('div')
el.className = 'chat-msg'
el.innerHTML = `<span class="user">${d.user}</span> ${d.comment}`
chat.prepend(el)
if (chat.children.length > 50) chat.lastChild.remove()
})
src.addEventListener('gift', (e) => {
const d = JSON.parse(e.data)
document.getElementById('gift-name').textContent = `🎁 ${d.gift}`
document.getElementById('gift-user').textContent = `from ${d.user}`
document.getElementById('gift-diamonds').textContent = `${d.diamonds} 💎`
gift.classList.add('show')
setTimeout(() => gift.classList.remove('show'), 4000)
})
src.addEventListener('viewers', (e) => {
const d = JSON.parse(e.data)
document.getElementById('viewers').textContent = `👁 ${d.count.toLocaleString()}`
})
</script>
</body>
</html>Step 4: Run & Add to OBS
TIKTOOL_API_KEY=your_key STREAMER=target_username node server.mjsThen in OBS:
- Add a new Browser Source
- Set URL to
http://localhost:3333 - Set width to 1920 and height to 1080
- Check "Shutdown source when not visible"
Customization Ideas
- Custom themes — change colors, fonts, and layout to match your stream brand
- Sound effects — play sounds when gifts arrive using the Web Audio API
- GIF animations — show animated GIFs for specific gifts
- Goal bars — add donation/gift goal progress bars
- Top gifter podium — show the top 3 gifters in real-time