Overview
Bread Boi Live Pet is an engaging digital companion that enhances live TikTok streams with dynamic interactions. This project involved setting up a homelab with Docker containers to host the game and relay server, ensuring seamless real-time reactions based on stream events.
Background
The goal was to create an interactive pet that could react in real time to various events during a live stream, such as receiving gifts or gaining new followers. The pet is built using three.js for rendering and a Node.js relay server to handle TikTok LIVE events and interact with a local language model (LLM).
How It Works
Game Container
The game itself runs in an nginx:alpine container. This setup allows the game files to be bind-mounted directly from the Network Attached Storage (NAS), ensuring that any changes made on the NAS are immediately reflected in the live stream.
docker run -d \
--name breadboi-game \
-v /path/to/game/files:/usr/share/nginx/html \
-p 80:80 \
nginx:alpine
The custom nginx configuration serves only the game file, excluding any unnecessary files like .env:
server {
listen 80;
server_name breadtoasting.com;
location / {
root /usr/share/nginx/html;
try_files $uri $uri/ =404;
}
# Auto-reload when the game file changes
error_page 497 403 502 503 504 /reload.html;
location = /reload.html {
internal;
allow 127.0.0.1;
deny all;
default_type text/html;
return 497 "<meta http-equiv='refresh' content='0;url=/'>";
}
}
Relay Server Container
The relay server runs in a node:22-alpine container, handling TikTok LIVE events and communicating with the local LLM. It restarts unless stopped to ensure it remains up and running.
docker run -d \
--name breadboi-relay \
-v /path/to/relay/code:/app \
-p 3000:3000 \
node:22-alpine \
sh -c "npm install && npm start"
Reverse Proxy
Both containers sit behind a reverse proxy, with the relay server specifically handling WebSocket upgrades.
server {
listen 443 ssl;
server_name breadtoasting.com;
# Other configurations...
location /relay {
proxy_pass http://breadboi-relay:3000;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
Results
The setup works well, with the game and relay server communicating seamlessly to provide real-time interactions during live streams. The auto-reloading feature ensures that any changes made on the NAS are immediately visible in the stream.
Key Features
- Real-Time Reactions: Dances when receiving gifts, heart animations for new followers.
- AI-Generated Responses: Local LLM provides personalized responses to comments.
- Idle Loop: Includes an idle hunger/feed-and-pet loop to keep the pet engaged even between interactions.
Lessons Learned
- TikTok Signing Service Limitations: The free tier of the signing service used for TikTok LIVE connections requires disabling "extended gift info" to avoid premium-only paths that can cause issues with gift resolution.
- Auto-Reloading: Implementing a lightweight auto-reload mechanism ensures that changes are immediately visible without manual intervention.
TODO:
- Integrate more complex reactions based on specific comments (e.g., "dance", "spin").
- Map specific gift IDs to tailored reactions/lines, bypassing the free-tier's generic gift name limitation.
This project has been a valuable learning experience in setting up real-time interactions for live streams and managing Docker containers within a homelab environment.