Viewer Database
VMSC automatically builds a local database of every viewer who interacts with your stream. When someone sends a chat message, follows, shares, gifts, or likes, their profile is created (or updated) with cumulative statistics. No manual setup is required — the database populates itself as you stream.
The viewer database is stored locally on your machine in an SQLite file. Data persists across streams and application restarts. You own all of your data and it never leaves your computer.
Viewer tracking begins the moment you connect to TikTok. There is no "enable" switch — every event that includes a username is recorded in the database automatically.
Viewer Stats
Each viewer entry in the database tracks a rich set of engagement metrics. These stats are updated in real time as events arrive from TikTok.
| Stat | Description |
|---|---|
| Messages | Total number of chat messages sent by this viewer across all tracked streams. |
| Gifts | Total number of individual gift events. Combo gifts count each increment separately. |
| Diamonds | Cumulative diamond value of all gifts sent. This reflects the monetary value of a viewer's contributions. |
| Likes | Total like count from this viewer. TikTok sends like events in batches, so this may increment by more than one at a time. |
| Visits | Number of times the viewer has joined your stream (triggered by the "member joined" event). |
| Shares | Number of times the viewer shared your stream. |
| Follows | Whether the viewer has followed (tracked as a boolean, with the timestamp of the follow event). |
| First Seen | Timestamp of the first event ever recorded from this viewer. |
| Last Seen | Timestamp of the most recent event from this viewer. |
Click on any viewer row in the Viewers page to open their full profile card, which displays all stats along with their chat history and applied tags.
Per-Platform Stats
VMSC tracks viewer engagement per platform. When a viewer interacts across multiple connected platforms (TikTok, Twitch, YouTube, Kick, Streamlabs, StreamElements), their stats are recorded separately for each source. Per-platform metrics include:
- Messages — chat messages sent on each platform
- Gifts — gift events per platform
- Diamonds — diamond/currency value per platform
- Likes — like count per platform
- Follows — follow status per platform
- Subscriptions — sub status per platform
- Bits / Donations — monetary contributions per platform
Platform Breakdown Table
The viewer detail panel includes a Platform Breakdown table that shows a row for each platform the viewer has been seen on. Each row displays the platform name with a colored platform badge and counters for that platform's stats. This gives you an at-a-glance view of where a viewer is most active.
Viewer records created before multi-platform support was added continue to work. Legacy records are treated as TikTok-only entries. New platform data is appended as it arrives without overwriting existing stats.
For full technical details, see the Per-Platform Viewer Stats dedicated page.
Region-Aware Gift Matching
TikTok gift names vary by region and language. A gift called "Rose" in English may have a completely different display name in other regions. VMSC solves this with region-aware gift matching.
How It Works
- Each gift in the database includes a
numericIdfield — a platform-assigned numeric identifier that is consistent across all regions. - VMSC auto-fetches gift metadata from the TikTok webcast API, including numeric IDs and localized names.
- When matching gifts in rule filters, VMSC looks up by numeric ID first, then falls back to a name-based match if the numeric ID is unavailable.
This ensures your gift-based rules work correctly regardless of the viewer's TikTok region or the language of the gift name displayed on their client.
For full technical details, see the Region-Aware Gift Matching dedicated page.
Tags
Tags let you label viewers with custom categories that you define. Tags are useful for organizing your community, creating targeted rule conditions, and quickly identifying important viewers.
Adding Tags
- Single viewer — Open a viewer's profile and click Add Tag. Type a tag name and press Enter. Tags are created on the fly; you do not need to define them in advance.
- Bulk tagging — Select multiple viewers using the checkboxes in the viewer list, then click Tag Selected in the toolbar to apply a tag to all selected viewers at once.
Using Tags in Rules
Tags can be referenced in rule conditions. For example:
- Only trigger a rule for viewers tagged as VIP
- Block an action for viewers tagged as Banned
- Send a special chatbox greeting for viewers tagged as Friend
In the rule condition editor, select Viewer Tag as the condition type, then choose has tag or does not have tag and enter the tag name.
Combine tags with rules for powerful automation. For example, automatically tag any viewer who gifts more than 1,000 diamonds as "Top Supporter" using a rule action, then use that tag to unlock special interactions in other rules.
Search and Filter
The Viewers page includes a search bar and filter controls to help you find specific viewers quickly, even in databases with thousands of entries.
- Search by name — Type a username (or partial username) in the search bar to instantly filter the viewer list. The search is case-insensitive and matches anywhere in the username.
- Filter by tag — Use the tag filter dropdown to show only viewers with a specific tag. You can combine this with the search bar for more precise results.
- Sort options — Click column headers to sort viewers by messages, diamonds, gifts, likes, visits, first seen, or last seen. Click again to toggle ascending/descending order.
The viewer list is paginated for performance. Use the page controls at the bottom to navigate through large datasets.
Chat History
VMSC logs every chat message received during your streams. Chat history is stored per viewer, letting you review what any individual has said across all of their sessions.
Viewing Chat History
To view a viewer's chat history, click on their row in the Viewers page, then click the Chat History button in their profile card. This opens the Chat Log Popup.
Chat Log Popup
The Chat Log Popup is a dedicated overlay window that displays a viewer's full message history with the following features:
- Chronological view — Messages are displayed oldest-first with timestamps in your local timezone.
- Session dividers — Horizontal dividers with date headers separate messages from different stream sessions, making it easy to see when a conversation happened.
- Search — A search bar at the top filters messages in real time. Type any keyword to find specific messages across all sessions.
- Scrollable — The popup supports smooth scrolling through thousands of messages without performance issues.
Chat messages are stored in the same SQLite database as viewer stats. Over time, this file can grow significantly if you stream frequently. You can manage database size from Settings > Data.
Session Tracking
VMSC uses a rolling-window session system to track recent viewer activity. By default, the system tracks the last 5 stream sessions. This allows you to distinguish between long-time regulars and first-time visitors based on recent attendance.
How Sessions Work
- A new session begins each time you connect to TikTok LIVE and start receiving events.
- The session ends when you disconnect or close VMSC.
- Viewer stats include a session count field that tracks how many of the last 5 sessions this viewer appeared in.
- When the 6th session starts, the oldest session data is rolled off the window.
Session-Based Conditions
You can use session data in rule conditions to create behavior like:
- First-time viewer greeting — Trigger a special welcome message when a viewer's session count is 1 (this is their first appearance in the rolling window).
- Regular viewer reward — Offer exclusive interactions for viewers who have appeared in 3 or more of the last 5 sessions.
- Returning viewer detection — Fire an event when a known viewer joins for the first time in the current session.
Session tracking uses a 5-stream rolling window, not lifetime data. A viewer who was active months ago but has not appeared in your last 5 streams will show a session count of 0. Lifetime stats (total messages, total diamonds, etc.) are always preserved regardless of the session window.
Bulk Operations
When managing large viewer databases, individual edits become impractical. VMSC provides bulk operations to act on multiple viewers at once.
Selecting Viewers
Each row in the viewer list has a checkbox. You can:
- Click individual checkboxes to select specific viewers.
- Click the Select All checkbox in the header to select every viewer on the current page.
- Use Shift+Click to select a range of viewers between two clicked checkboxes.
Available Bulk Actions
Once you have selected one or more viewers, the toolbar at the top reveals these bulk action buttons:
| Action | Description |
|---|---|
| Tag Selected | Apply a tag to all selected viewers. A dialog prompts you to enter or choose a tag name. |
| Remove Tag | Remove a specific tag from all selected viewers. |
| Delete Selected | Permanently remove selected viewers and all their associated data (stats, chat history, tags) from the database. This cannot be undone. |
Deleting viewers removes all of their data from the database, including their complete chat history and cumulative stats. There is no undo or recycle bin. A confirmation dialog will ask you to verify before proceeding.
Live Feed Widget
The dashboard includes a Live Feed widget that shows a real-time scrolling view of all incoming stream events. This is separate from the viewer database — it shows the raw event stream as it happens.
The Live Feed displays:
- Chat messages with usernames and timestamps
- Gift events with gift name, count, and diamond value
- Follow, share, and like events
- Member join events
- Rule trigger notifications (when a rule fires)
Use the Live Feed to monitor your stream activity at a glance and verify that events are being received correctly from TikTok.