OBS overlays for a TikTok live stream, driven by the Tikfinity desktop app's local Events API WebSocket. Ships with a gallery + configurator so you can browse overlays, tweak every option with a live preview, and copy a ready‑to‑paste OBS Browser Source URL.
Included overlay:
- Coin Jar Pro — a clear glass jar that fills up with viewers' gifts as they're sent. Each gift drops in as its real TikTok gift icon and uses the icon's visible silhouette for collisions, so transparent image padding does not leave artificial gaps in the pile. When the jar fills, gifts overflow and a box around it catches them. Turn on “Combine like gifts” and two of the same gift that touch combine into one bigger gift — any sizes count up (1🍊 + 2🍊 = 3🍊). And when a big gift lands or the jar overflows, it cracks and shatters — gifts burst off‑screen, a fresh jar drops in, and a broken‑jar kill tally counts each one.
No coding needed to use it. Everything runs locally as plain HTML/JS.
Hosted gallery: https://darinh.github.io/tiktok-overlays/ is useful for browsing, configuring, and demo previews. For a reliable live OBS source, use the downloaded local copy. Current Chromium security can require Local Network Access permission—or block a public HTTPS page entirely—when it tries to reach Tikfinity at
ws://127.0.0.1:21213. The hosted configurator shows this warning and can copy a loopback URL fornpm run serve.
- Make sure Tikfinity Desktop is installed and running on this PC, and that it's connected to your TikTok account / live.
- Open
index.html(this folder) in your web browser by double‑clicking it. This is the gallery.- The top‑right dot shows whether Tikfinity is detected. Green = good.
- Click Configure on Coin Jar Pro.
- Tweak the settings (you'll see a live preview). Tick “Animate preview with demo gifts” to watch fake gifts drop while you design.
- Click Copy URL.
- In OBS: Sources → ➕ → Browser, paste the URL, set the size (≈ 360 × 600), click OK. Done.
Tip: there's also a Node helper —
npm run serve— which serves everything athttp://127.0.0.1:8777/. This loopback URL is the most reliable option for both browser testing and OBS.
Want a different jar look? The overlay composites your own layered jar PNGs from
overlays/coin-jar-pro/assets/(front glass, back rim, inner base) with the gifts piling up in between. Swap those PNGs for your own art to restyle the jar — see §7.
TikTok LIVE ─▶ Tikfinity Desktop ─▶ ws://127.0.0.1:21213/ ─▶ overlay (OBS Browser Source)
- Tikfinity does the hard part (connecting to TikTok, decoding gifts) and re‑broadcasts
every event on a local WebSocket:
ws://127.0.0.1:21213/. - Each message looks like
{"event":"gift","data":{ ... }}. On connect Tikfinity also sends a{"event":"config", ...}handshake. - The overlay connects to that WebSocket, listens for
giftevents, counts the coins, and animates the jar. The overlay must run on the same PC as Tikfinity.
Because it's just a Browser Source pointed at a local file, there is nothing to “side‑load” into Tikfinity — Tikfinity only needs to be running so the WebSocket is available.
- Install & open Tikfinity Desktop, sign in, and connect to your TikTok username.
- Keep the app running while you stream. The local Events API
(
ws://127.0.0.1:21213/) is served by the desktop app. - Go live on TikTok (or use Demo mode below to test the look without being live).
If the overlay's debug panel shows connected but nothing happens, it usually just means no gifts have arrived yet, or you're not currently live. See Troubleshooting.
- Sources → ➕ → Browser.
- URL: paste the URL from the local configurator (it points at
…/overlays/coin-jar-pro/index.html?…your settings…).- If you prefer, you can use the local file path directly, e.g.
file:///C:/Users/you/repos/tiktok-overlays/overlays/coin-jar-pro/index.html?combine=1&width=380
- If you prefer, you can use the local file path directly, e.g.
- Width / Height: about 360 × 600 (or match your chosen
width/scale). - Leave “Shutdown source when not visible” unchecked so the count keeps running.
- Click OK, position it on your scene.
Keep the whole project folder together — the overlay loads its own lib.js,
overlay.js, overlay.css, and vendor/matter.min.js from the same folder.
All options are set from the configurator (or by editing the URL's ?key=value
parts). Defaults are shown.
The configurator mirrors Tikfinity's real Coin Jar Pro “Overlay Settings” dialog (Font · Position · Alert · Leaderboard · Gift), with this project's extras merged in (Jar art · Combine · Stream & motion · Effects · Sounds).
| Option | Default | What it does |
|---|---|---|
fontType |
Exo 2 |
Font family for the on‑screen text (loaded from Google Fonts; falls back to system fonts offline). |
fontSize |
50 |
Relative size of the HUD text (50 = baseline). |
fontLineSpacing |
50 |
Line spacing for the leaderboard. |
fontLetterSpacing |
50 |
Letter spacing (50 = normal). |
| Option | Default | What it does |
|---|---|---|
xOffset |
0 |
Nudge the whole overlay left/right (px). |
yOffset |
0 |
Nudge the whole overlay up/down (px). |
scale |
1 |
Overall scale (0.1–2). |
giftScale |
1 |
Size of the gift icons only (0.1–2). |
| Option | Default | What it does |
|---|---|---|
displayAlert |
on |
Banner announcing who just gifted (e.g. “Dan sent Rose”). |
alertDuration |
5 |
Seconds the alert stays on screen (2–10). |
| Option | Default | What it does |
|---|---|---|
displayLeaderboard |
on |
Show the top‑gifters leaderboard (top left). |
numberOfRanks |
top5 |
How many gifters to list — top3 / top5 / top10. |
leaderboardDisplayFormat |
avatarNameCoins |
What each row shows — avatarNameCoins / nameCoins / avatarCoins / coins. |
leaderboardDuration |
5 |
Seconds the leaderboard stays visible after the latest gift. |
displayRankBadges |
on |
Show the 1/2/3 rank badges. |
showTotalCoins |
on |
Show the running total coin count (top center). |
| Option | Default | What it does |
|---|---|---|
giftType |
allGifts |
allGifts, or selectedGifts to reveal the picker below. |
gift |
(empty) | (Selected Gifts) Only these gifts count — add them by name or ID. An empty selection allows none. |
minimumValue |
0 |
(Selected Gifts) Ignore gifts worth fewer than this many coins. |
excludeGifts |
(empty) | Blacklist — these gifts are always ignored. |
| Option | Default | What it does |
|---|---|---|
combine |
off |
When two of the SAME gift touch, they combine into one bigger gift — any sizes count (1🍊 + 2🍊 = 3🍊). |
combineGrowth |
0.5 |
How fast a combined gift grows with how many combined (0.5 = √count). |
combineMaxScale |
4.5 |
Cap on how big a combined gift can get (× base size). |
The jar cracks when a big gift lands or once gifts overflow the mouth, then shatters — gifts explode off‑screen, glass shards fly, a fresh jar drops in with a little sway, and a broken‑jar kill mark (WW2‑style) joins the tally (top‑right). There's no hard gift cap; the break cycle keeps the count bounded.
| Option | Default | What it does |
|---|---|---|
jarBreaks |
on |
Master switch for the crack → shatter → respawn cycle. |
crackBigGiftCoins |
100 |
A single gift at/above this coin value cracks the jar; ~5× shatters it outright. |
bigGiftCrack |
0.22 |
How much one big gift cracks the jar (1 = instant break). |
overflowCrack |
0.05 |
Extra crack damage from each gift that settles above the mouth. |
showJarTally |
on |
Show the broken‑jar kill marks (top‑right), one per jar shattered. |
breakSound |
(empty) | Optional URL played when the jar shatters. |
| Option | Default | What it does |
|---|---|---|
stream |
on |
Gifts arrive one‑by‑one from a single point above the jar (vs all at once). |
streamStagger |
0 |
Milliseconds between each streamed gift (0 = no spacing). |
spreadDeg |
30 |
Launch cone width (°): gifts fan across this angle instead of dropping straight down. |
launchSpeed |
8 |
Initial launch speed. |
gravity |
1 |
Fall speed. |
baseRadius |
14 |
Base size of a gift icon (px), multiplied by giftScale. |
maxBodies |
200 |
How many gifts the box holds; once full it stays full (settled gifts are frozen, so it stays smooth). |
spawnCap |
20 |
A big streak drops at most this many gift icons at once. |
| Option | Default | What it does |
|---|---|---|
sizeByValue |
off |
Optional. Gifts worth more diamonds drop in larger. |
sizeMaxScale |
2.6 |
Cap on the value‑based size multiplier (× base). |
bigGiftSplash |
off |
Optional. Burst confetti when a big gift lands. |
bigGiftCoins |
50 |
If bigGiftSplash is on, gifts at/above this diamond value burst confetti. |
coinSound, mergeSound (URLs) and volume (0–1). Leave blank for silence.
| Option | Default | What it does |
|---|---|---|
bg |
transparent |
Background — keep transparent for OBS, or set a color. |
width |
360 |
Overlay width in px. |
port |
21213 |
Tikfinity Events API WebSocket port. |
reconnect |
2000 |
Reconnect delay (ms) if the socket drops. |
demo |
off |
Demo mode — generates fake gifts and ignores the WebSocket. Great for testing. |
debug |
off |
Show a debug panel (connection status + recent events). |
When off, gifts just pile up in the jar as their TikTok icons and overflow when there are a lot of them.
When on, two of the same gift that touch combine into one bigger gift — and the sizes don't have to match: a single 🍊 can merge with a 3‑🍊 blob to make a 4‑🍊, just like 2‑🍊 + 3‑🍊 makes 5‑🍊. The more that have combined, the bigger that gift is (capped). No numbers, badges, or counters — it just gets bigger.
TikTok “streak” gifts (the kind that combo up while a viewer holds the button) are handled once, at the end of the streak, so a held streak drops the right number of icons.
Gift collisions automatically follow a compact convex outline derived from each icon's alpha channel instead of its full square image bounds. This excludes transparent padding while keeping large piles fast and stable. Deep inward notches and holes are intentionally treated as solid; if an image host does not permit alpha sampling, that icon safely falls back to a circular hitbox.
The jar is composited from three transparent PNG layers you provide, with the gifts on a canvas in between:
jar-top-bg-2.png back of the rim (behind the gifts)
jar-bottom.png inner base (behind the gifts)
---------------- gifts (canvas) ----------------
jar-top.png front glass (over the gifts)
- Put your three PNGs in
overlays/coin-jar-pro/assets/(default names above). - Make sure the front layer's glass interior is transparent so the gifts show through.
- Reload — gifts pile inside your jar and overflow out the mouth.
If the gifts don't line up, nudge these in the configurator (or URL):
| Option | Default | Meaning |
|---|---|---|
jarFrontImage |
assets/jar-top.png |
Front glass (over the gifts). |
jarBackImage |
assets/jar-top-bg-2.png |
Back of the rim (behind the gifts). |
jarBottomImage |
assets/jar-bottom.png |
Inner base (behind the gifts). |
jarInsetX |
0.24 |
Left/right of the interior where gifts pile. |
jarInsetTop |
0.13 |
Mouth line — gifts overflow above this. |
jarInsetBottom |
0.14 |
Floor — where gifts rest. |
The art is authored on a 500 × 500 front jar; the overlay scales everything to your
chosen width. Use your own art (or anything you have the rights to). The gift
icons come from TikTok live, so the overlay already shows the real ones when you're
streaming — the emoji only appear in offline demo mode.
Three ways to test without being live on TikTok:
A. Demo mode (zero setup). In the configurator tick “Animate preview with demo gifts”,
or add demo=1 to the URL. Fake gifts (including oranges 🍊 you can watch merge) drop in.
B. Events API simulator (most realistic). A bundled local server that speaks Tikfinity's WebSocket protocol and gives you a button panel to fire gifts — no internet, Tikfinity, or TikTok needed:
npm run sim # starts on port 21214
# or: node tools/sim.js --port 21214 --autoUse a different port than the real Tikfinity (21213) so they never clash. Then point the
overlay at that port — open overlays/coin-jar-pro/index.html?port=21214 (in OBS or a browser) —
and open the simulator's control panel at http://127.0.0.1:21214/ to send gifts: quick
presets, big gifts that crack/shatter the jar, random bursts, an auto stream, or a
custom gift. Whatever you send appears in the overlay live, exactly like a real Tikfinity gift.
C. Keyboard shortcuts (overlay focused in a browser): d debug · c toggle combine ·
g spawn a gift · b break the jar · r reset. The configurator's 🎁 Send test
gift / ↺ Reset buttons also drive the live preview.
| Symptom | Fix |
|---|---|
| Gallery dot is red / “not detected” | Start Tikfinity Desktop. It must be running on the same PC. Confirm the port is 21213 (Tikfinity setting). |
| Hosted gallery says local access is blocked | Download the project and use file:///…/index.html, or run npm run serve and use the generated http://127.0.0.1:8777/… URL. Modern Chromium restricts public pages that connect to loopback services. |
| Overlay says connected but nothing happens | You're connected to Tikfinity, but no gift events are arriving — make sure you're live on TikTok and that Tikfinity is connected to your room. Try Demo mode to confirm the overlay itself works. |
| Numbers don't move on real gifts | Turn on debug=1 and watch the event log. If you see events with different field names than expected, send me a sample line — the parser is defensive but I can add a mapping. |
| Count resets unexpectedly | Set a unique persistKey, and keep “Shutdown source when not visible” unchecked in OBS. |
| Too many / too few gifts on screen | Tune maxBodies, spawnCap, and baseRadius; use gifts / excludeGifts to filter which gifts appear. |
| Animation pauses when the page isn't focused | Normal browser background‑tab throttling — it does not happen in OBS, which keeps a Browser Source rendering continuously even when OBS isn't focused. For local browser testing, keep the overlay tab visible (or pop it into its own window). |
| Browser blocks local files | Use the helper server: node serve.js, then point OBS at http://localhost:8777/overlays/coin-jar-pro/index.html?…. |
tiktok-overlays/
├─ index.html # the gallery (open this)
├─ gallery.css / gallery.js
├─ serve.js # optional local test server
├─ overlays/
│ ├─ registry.js # list of overlays shown in the gallery
│ └─ coin-jar-pro/
│ ├─ index.html # the overlay (point OBS here)
│ ├─ config.js # defaults shared by the runtime + configurator
│ ├─ overlay.css
│ ├─ overlay.js # WebSocket + physics + rendering
│ ├─ lib.js # pure logic (unit‑tested)
│ └─ vendor/matter.min.js # physics engine (MIT)
├─ tools/ # simulator + control panel + smoke/perf tests
└─ test/ # unit and local integration tests
To add another overlay: create overlays/<your-id>/ with its own index.html, then
append an entry to overlays/registry.js (id, name, description, path, and the
list of configurable fields). It will appear in the gallery automatically.
npm test # unit tests for the pure logic (no browser needed)
npm run serve # serve everything at http://localhost:8777/
npm run sim # offline Events API simulator (control panel at http://127.0.0.1:21214/)
npm install --no-save puppeteer ; npm run smoke # headless end-to-end checks- Physics by Matter.js (MIT) — vendored at
overlays/coin-jar-pro/vendor/with its license. - Gift data comes from Tikfinity's local Events API; this project is an independent overlay and is not affiliated with Tikfinity or TikTok.
- The “merge when they touch” idea is a classic game mechanic (2048 / Suika‑style); this is an original implementation using your stream's own gift icons.