TikTok Live Audience Logger

Connects to active TikTok Live streams and logs all viewer activity (chat messages, member joins, and gifts) in real-time. Includes a built-in web dashboard for starting, stopping, and monitoring recording sessions.

How it works: The actor starts an Express web server with a control dashboard. When you start a recording, it spawns a child process (live.js) that connects to the TikTok Live stream via the tiktok-live-connector library and logs every event to a JSON file plus the Apify Key-Value Store. A generated HTML page provides a live-updating view of all captured events.

Note: This actor does NOT use a browser or TikTok session cookies. It connects to TikTok's WebSocket-based live stream API directly using the tiktok-live-connector library.

Input Parameters

Parameter	Type	Required	Default	Description
username	String	No	—	If provided, the actor will immediately begin logging this user's livestream on startup (auto-start mode).
durationSeconds	Integer	No	—	Auto-stop timer in seconds. The logger will automatically stop after this duration. Only applies when username is provided.
port	Integer	No	4321	Custom port for the web dashboard server. On the Apify platform, this is overridden by the ACTOR_WEB_SERVER_PORT environment variable.

Web Dashboard

The actor serves three pages:

• / — Main landing page (TikTok Live Engine). Enter a username and start recording from here.
• /admin — Command Center. View all active and past recording sessions, start/stop loggers, and export session data.
• /<username>_live_<date>.html — Live session viewer. Auto-refreshing page showing real-time chat, joins, and gifts for an active recording.

Dashboard API Endpoints

Endpoint	Method	Description
/start	POST	Start logging a livestream. Body: { "username": "..." }
/stop	POST	Stop a specific logger. Body: { "username": "..." }
/stop-all	POST	Stop all active loggers.
/status	GET	Returns status of all active loggers (username, PID, HTML file).
/loggers	GET	Lists all generated session files (HTML + JSON).
/export/:filename	GET	Download a session file (JSON or HTML).

Output

• Local files: For each recording session, a JSON log file (<username>_live_<date>.json) and an HTML viewer file (<username>_live_<date>.html) are generated in the project root.
• Key-Value Store: Both the JSON log and HTML viewer are synced to a named Key-Value Store called tiktok-live-logs, which persists across runs on the Apify platform.
• Dataset: Each viewer interaction (chat, join, gift) is pushed as a dataset entry with liveHost, viewer, event, comment, and timestamp.

Running Locally

cd tiktok-live-recorder
apify run

Then open http://localhost:4321 in your browser to access the dashboard. From there you can enter any TikTok username that is currently live and start recording.

On Apify Platform

The dashboard is accessible via the actor's Live View URL (shown in the Apify console after the run starts). You can also use the username input to auto-start recording without opening the dashboard.