🎬 TikTok Live Studio

An advanced, all-in-one solution for recording TikTok Live streams, capturing real-time chat, and managing the entire process via a CLI or a Web Interface.

This project is a hybrid fork and significant enhancement of:

TikTok-Live-Recorder by Michele0303 (Core recording logic).
TTLive-Manager by zfadhli (Manager architecture).

⚠️ Disclaimer: This project is for educational purposes only. The authors are not responsible for how you use this tool. Please respect copyright laws and TikTok's Terms of Service.

⚠️ Note on Support: This project was entirely designed and written by Artificial Intelligence (Claude.ai & Google AI Studio). The maintainer is not a programmer. While the software is tested, errors may occur, and the ability to provide deep technical support or code modifications is limited. Use at your own risk.

🌟 Key Features

🎥 Recording & Monitoring

Live Recording: Automatically record streams from a list of users (users.txt) or single targets.
Smart Monitoring and Infinite Retry System (Manager): "Set and Forget". The system monitors users in your list. If they are offline, it waits. As soon as they go live, recording starts automatically.
- Infinite Loop: The system now guarantees that it will keep trying to record a target user indefinitely until you manually stop it.
- Adaptive Cooldowns:
  - Normal Retry (60s): Used when a stream ends normally or the user is offline.
  - Blocked Retry (5m / 300s): Triggered automatically if DEVICE_BLOCKED, WebSocket rejected, or Connection error is detected in the logs. This prevents permanent IP bans by allowing the connection to "cool down."
Resource Isolation: Recordings happen in a hidden .recording folder to prevent file locking issues during conversion.
Dual Interface: Control everything via an interactive Command Line Interface (CLI) or a modern Web UI.

💬 Chat Capture & Overlay

Formats: Save chat as JSON, TXT, SRT, or ASS.
Professional Overlay: Automatically generates a "Side-Bar" style chat overlay (.ass) and burns it onto the video.
Smart Matching: Uses intelligent date/time matching to find the correct chat file for a video, even if filenames differ slightly.
Battle Tracking: (Experimental) Logs PK Battle scores and events directly into the chat file.
Emoji Support: Maps TikTok internal emoji codes (e.g., [laugh]) to standard Unicode emojis (😆).

🎨 Enhanced Visuals & Logging

Smart Console Coloring: The CLI and Server console now use intelligent color coding for better readability:
- 🔴 RED: System alerts, errors, connection status, recording events (Start/Stop), and critical info.
- 🟡 YELLOW: Automatically highlights all @usernames in the logs.
- 🟢 GREEN: Success messages, conversion progress, and file operations.
System Logs: A dedicated system_logs.txt file is now generated in the root directory. It records connection errors, retry attempts, and file movements, keeping your console clean of repetitive system info while preserving a history of events (excluding chat messages).

🛠️ Utilities

Auto-Fixing: Automatically repairs broken timestamps in recorded streams.
Safe Fix: Convert and overlay finished videos while other recordings are still running in the background.
Format Choice: Convert to MKV, MP4 (x264/x265), MOV, AVI, WMV, or WEBM.

The "Fix & Overlay" tool has been completely rewritten in TypeScript to match the advanced Python logic:

Auto-Crop: Automatically detects and removes black bars from the source video.
Smart Scaling: Fits any video resolution into a standard 1920x1080 canvas with proper padding (prevents "squashed" videos during PKs/Battles).
Emoji Support: Automatically patches subtitle files to use Segoe UI Emoji, ensuring emojis appear correctly in the overlay.
Auto-Match: Intelligently finds the correct chat log for the video based on timestamps, even if filenames vary slightly.

🚀 Quick Start

🛠️ Prerequisites

Before you begin, ensure you have the following installed:

Git (Recommended for Windows). Download Here
FFmpeg (Essential for video conversion and overlay). Download Here - Make sure it is added to your System PATH.
Python 3.11+. Download Here
Bun (JavaScript Runtime).
- Windows Install (PowerShell):
```
powershell -c "irm bun.sh/install.ps1|iex"
```

📥 Installation

Clone the repository:

git clone https://github.com/norby777/TikTok-Live-Studio.git
cd TikTok-Live-Studio

Install Python Dependencies: Run the included batch file to set up the virtual environment (.venv) and install all required libraries (including the critical httpx fix).
```
cd src
./setup_venv.bat
```
- In CMD/Explorer: Double click setup_venv.bat
- In Git Bash: ./setup_venv.bat
This script installs critical fixed versions of httpx, betterproto, and TikTokLive to ensure stability.
Install Bun Dependencies:
```
bun install
```

🚀 Usage

You can launch the program in two modes.

Web Interface (Recommended) Provides a visual dashboard to manage downloads, settings, and converting.
- Command:
```
bun run web
```
- Shortcut: Double-click Start_web.bat
- URL: Open in your browser.
```
http://localhost:3000
```
Command Line Interface (CLI) A terminal-based menu system.
- Command:
```
 bun run dev
```
- Shortcut: Double-click start_cli.bat

📚 Documentation

For detailed instructions on configuration, usage, and advanced features, please read the Full User Guide.

🤝 Credits & Attribution

This project was developed and refined by a non-programmer with the extensive assistance of Artificial Intelligence tools.

Original Core: Michele0303
Original Manager: zfadhli
AI Development:
- Google AI Studio (Gemini 3 Pro Preview)
- Claude.ai (Sonnet 4.5)

⚖️ Legal

This code is in no way affiliated with, authorized, maintained, sponsored or endorsed by TikTok or any of its affiliates or subsidiaries. Use at your own risk.

Downloads last month: -; Downloads are not tracked for this model. How to track

Inference Providers NEW

This model isn't deployed by any Inference Provider. 🙋 Ask for provider support