Welcome to PupCid's Little TikTool Helper

This documentation helps you get the most out of the tool and learn all its features.

What is ltth.app?

PupCid's Little TikTool Helper is a professional Open Source tool for TikTok LIVE streaming with extensive features for content creators. The tool provides complete integration of TikTok LIVE events into OBS Studio with overlays, alerts, Text-to-Speech, soundboard and event automation.

Main Features

• Real-time TikTok LIVE Integration: Receive Gifts, Comments, Follows, Shares and Likes in real-time
• Text-to-Speech: 75+ TikTok voices & 30+ Google Cloud voices
• Alert System: Customizable alerts for all event types
• Soundboard: 100,000+ sounds via MyInstants integration
• Event Automation (Flows): If-Then automations without code
• OBS Integration: Transparent Full-HD overlay for streams
• Plugin System: 7+ pre-installed plugins, extensible
• 100% Local & Open Source: No cloud, no login credentials required

Who is this tool for?

• TikTok LIVE Streamers - Professional overlays and alerts
• Content Creators - Event automation and interactivity
• VRChat Streamers - OSC integration for avatar control
• Multi-Guest Streamers - VDO.Ninja integration for interviews
• Developers - Modular plugin system for extending

Installation & Setup

Installing PupCid's Little TikTool Helper is simple and fast.

System Requirements

• Operating System: Windows 10/11 (64-bit)
• Node.js: 18.0.0 - 23.x (installed automatically)
• RAM: At least 4 GB recommended
• Disk Space: 500 MB free space

Installation

1. Download: Download setup.exe from ltth.app/download
2. Run Installation: Double-click setup.exe and follow the installation wizard
3. Node.js: Is automatically installed if not present
4. Start Server: The tool starts automatically after installation
5. Open Dashboard: Browser opens automatically at http://localhost:3000

Manual Installation (for Developers)

# Clone repository
git clone https://github.com/Loggableim/ltth.app.git
cd ltth.app

# Install dependencies
npm install

# Start server
node launch.js

# Or with launcher script:
# Windows: start.bat
# Linux/macOS: ./start.sh

Quick Start

Get a professional TikTok LIVE stream in 3 steps!

Step 1: Connect to TikTok LIVE

1. Open the Dashboard at http://localhost:3000
2. Enter your TikTok username (without @)
3. Click "Connect to TikTok LIVE"
4. Wait for green status "Connected"

Important: You must already be LIVE on TikTok for the connection to work.

Step 2: Set up OBS

1. Open OBS Studio
2. Add a new Browser Source
3. URL: http://localhost:3000/overlay
4. Width: 1920, Height: 1080
5. Enable "Shutdown source when not visible" for performance

Step 3: Configure Features

• TTS: Dashboard → TTS → Select voice → Enable "Auto-TTS for Chat"
• Alerts: Dashboard → Alerts → Select event type → Configure sound and text
• Goals: Dashboard → Goals → Set goal → Customize style
• Flows: Dashboard → Flows → "New Flow" → Define trigger and actions

Done! 🎉 Your stream is now professionally set up.

Configuration

Customize ltth.app to your needs with extensive configuration options.

Dashboard Access

After starting, the dashboard opens automatically at:

http://localhost:3000

Basic Settings

• TikTok Username: Your TikTok username (without @)
• Language: German or English
• Theme: Light, Dark or System
• Server Port: Default 3000 (changeable)

Profiles

Create multiple profiles for different streaming setups:

• Different TikTok accounts
• Different alert configurations
• Separate soundboards
• Individual flow automations

Backup & Restore

Regularly backup your configuration:

1. Dashboard → Settings → Backup
2. Click "Create Backup"
3. ZIP file will be downloaded
4. To restore: "Restore from Backup"

TikTok LIVE Connection

Real-time connection to your TikTok LIVE stream without login credentials.

Establishing Connection

1. Open Dashboard at http://localhost:3000
2. Enter your TikTok username (without @)
3. Click "Connect to TikTok LIVE"
4. You must already be LIVE on TikTok
5. Wait for green status "Connected"

Received Events

• Gifts: Gifts with coins, combo tracking, gift catalog
• Chat: Messages with profile pictures and badges
• Follows: New followers with follow role tracking
• Shares: Stream shares with user information
• Likes: Like events with like counts
• Subscriptions: Subscribers with tier levels

Event Display

All events are displayed in real-time:

• Event Log: Chronological list of all events
• Statistics: Live statistics (Total Coins, Followers, etc.)
• Top Gifters: Leaderboard of top donors

Auto-Reconnect

Automatic reconnect on connection loss:

• Maximum reconnect attempts: 10
• Wait time between attempts: 5 seconds
• Configurable in Settings

Troubleshooting

Connection fails:

• Make sure you are already LIVE
• Username must be correct (without @)
• Check firewall/antivirus settings
• Try again after 30 seconds

Text-to-Speech (TTS)

Professional TTS system with over 100 voices for chat messages and alerts.

Available Voices

TikTok Voices (Free)

75+ TikTok voices without API key:

• English: US Female, US Male, UK Female, Australian, etc.
• German: Male and Female
• Character Voices: Ghostface, C-3PO, Stitch, Chewbacca
• Singing Voices: Singing Female, Singing Male

Google Cloud Voices (Premium)

30+ Google Cloud voices with highest quality (API key required)

Auto-TTS for Chat

Automatic reading of chat messages:

1. Dashboard → TTS → Enable "Auto-TTS for Chat"
2. Select default voice
3. Optional: Set up blacklist for words/users
4. Adjust volume and speed

User Voice Mapping

Assign specific voices to certain users:

UserA → Ghostface (Horror voice)
UserB → German Female
UserC → Singing Voice

Settings

• Volume: 0% - 200% (Default: 100%)
• Speed: 0.5x - 2.0x (Default: 1.0x)
• Max. Length: Skip messages over X characters
• Delay: Pause between TTS messages

Blacklist

Block words or users:

• Word Blacklist: Skip messages with certain words
• User Blacklist: Completely ignore certain users

TTS in Flows

Use TTS in event automations:

Trigger: Gift (Rose)
Action: TTS "Thanks {username} for the Rose!"

Alert System

Visual and audio notifications for TikTok LIVE events in your OBS overlay.

Alert Types

• Gift Alerts: Gift notifications
• Follow Alerts: New followers
• Share Alerts: Stream shares
• Subscription Alerts: New subscribers
• Like Alerts: Like milestones (e.g., every 100 likes)

Alert Configuration

Each alert can be customized individually:

• Text: Message with variables like {username}, {giftName}, {coins}
• Sound: MP3/WAV file or MyInstants sound
• Duration: Display duration in seconds
• Animation: Slide, Fade, Bounce, etc.
• Image/GIF: Optional custom graphics

Template Variables

Use placeholders in alert texts:

{username} - Username
{giftName} - Name of the gift
{coins} - Coin value
{count} - Combo count
{total} - Total coins from user
{likeCount} - Current like count

Example Configurations

Gift Alert:

Text: "Thanks {username} for {giftName}!"
Sound: celebration.mp3
Duration: 5 seconds
Animation: Slide from bottom

Follow Alert:

Text: "Welcome {username}! 🎉"
Sound: welcome.mp3
Duration: 4 seconds
Animation: Fade in

Alert Queue

Multiple alerts are displayed one after another:

• Queue size: 50 alerts (default)
• Priority: Subs > Gifts > Follows > Shares > Likes
• Older alerts are discarded on overflow

Test Function

Test alerts before the stream:

1. Dashboard → Alerts
2. Select event type
3. Click "Test Alert"
4. Alert appears in OBS overlay

Soundboard

100,000+ sounds via MyInstants integration plus custom upload option.

MyInstants Integration

Access to huge sound library:

1. Dashboard → Soundboard → MyInstants
2. Enter search term (e.g., "applause", "laugh")
3. Sound preview with play button
4. "Add to Soundboard" to import

Custom Upload

Upload your own sounds:

• Formats: MP3, WAV, OGG
• Max. Size: 10 MB per file
• Recommended: 1-30 seconds duration
• Quality: 128-320 kbps (MP3)

Gift-to-Sound Mapping

Play sounds automatically on gifts:

Rose → romantic-music.mp3
Lion → lion-roar.mp3
Galaxy → space-sound.mp3

Event Sounds

Sounds for various events:

• Follow Sound: On new follower
• Subscribe Sound: On subscriber
• Share Sound: On stream share
• Like Milestone: On like threshold (e.g., every 100)

Sound Categories

Organize sounds in categories:

• Alerts - Notifications
• Reactions - Reactions
• Memes - Funny sounds
• Music - Music clips
• Effects - Sound effects
• Custom - Custom uploads

Favorites

Mark frequently used sounds as favorites for quick access.

Volume Control

• Master Volume: 0% - 200% for all sounds
• Per-Sound Volume: Individual volume
• Volume Ducking: Reduce sound during TTS

Event Automation (Flows)

Create "If-Then" automations without code.

Flow Components

• Trigger: Event that starts the flow (Gift, Chat, Follow, etc.)
• Conditions: Optional conditions (e.g., coins >= 100)
• Actions: What gets executed (TTS, Alert, OBS, OSC, etc.)

Available Triggers

• Gift: Gift received
• Chat: Chat message
• Follow: New follower
• Share: Stream shared
• Subscribe: New subscriber
• Like: Likes received

Conditions

Operators for conditions:

== (equal)
!= (not equal)
> (greater than)
< (less than)
>= (greater or equal)
<= (less or equal)
contains (contains)
startsWith (starts with)
endsWith (ends with)

Available Actions

• TTS: Play Text-to-Speech
• Alert: Show alert
• Sound: Play sound
• OBS Scene: Switch OBS scene
• OBS Source: Show/hide source
• VRChat OSC: Avatar control
• HTTP Request: Call external API
• Delay: Wait (for action chains)
• Goal Increment: Increase goal progress

Example Flows

Rose Gift → TTS + Scene Change

Trigger: Gift
Condition: giftName == "Rose"
Actions:
  1. TTS: "Thanks {username} for the Rose!"
  2. OBS Scene: "Cam2"
  3. Delay: 5 seconds
  4. OBS Scene: "Main"

High Value Gift → Special Alert

Trigger: Gift
Condition: coins >= 1000
Actions:
  1. Alert: "🎉 WOW! {username} → {giftName}!"
  2. Sound: celebration.mp3
  3. VRChat OSC: Celebrate animation

Chat Command → Action

Trigger: Chat
Condition: message == "!dance"
Actions:
  1. VRChat OSC: Dance animation
  2. TTS: "Let's dance!"

New Follower → Welcome

Trigger: Follow
Actions:
  1. TTS: "Welcome {username}!"
  2. Alert: "New follower: {username}"
  3. Goal: Followers +1

Flow Management

• Enable/Disable: Turn flows on/off
• Test Flow: Test flow without being live
• Export/Import: Backup/share flows as JSON
• Priority: Set flow order

Best Practices

• Test flows before the stream
• Use descriptive names
• Keep conditions simple
• Use delays for OBS scene changes
• Use variables for dynamic texts

Goals & Overlays

Progress bars for Likes, Followers, Subscriptions and Coins with OBS integration.

Goal Types

• Likes Goal: Target likes with real-time tracking
• Followers Goal: Follower target
• Subscriptions Goal: Subscriber target
• Coins Goal: Coin donation target
• Custom Goal: User-defined goals (manual)

Configuration

Configurable per goal:

• Target Value: Number of points to reach
• Current Value: Auto-update or manual
• Mode: Add, Set, Increment
• Display Text: Template with {current}, {target}, {percentage}

Styling

Customize progress bars:

• Colors: Background, Progress, Text
• Gradients: Linear gradient support
• Size: Width, Height, Border-Radius
• Animations: Fill, Pulse, Shimmer

OBS Browser Source

Show Goals in OBS:

URL: http://localhost:3000/overlay/goals
Width: 1920
Height: 200
FPS: 30

Milestone Notifications

Alerts at certain progress percentages:

25% → "Quarter done!"
50% → "Halfway there!"
75% → "Almost there!"
100% → "🎉 Goal reached!"

Goal Modes

• Add: Add value to current progress
• Set: Set progress to specific value
• Increment: Increase by 1

Auto-Update

Automatically update goals via Flows:

Trigger: Follow
Action: Goal Increment: Followers +1

Reset Options

• Manual Reset: Reset anytime
• Daily Reset: Daily at midnight
• Stream Start: At stream start
• Stream End: At stream end

OBS Studio Integration

Full OBS control with WebSocket v5 for scenes, sources and overlays.

Requirements

• OBS Studio 28.0+ (WebSocket v5 integrated)
• WebSocket enabled: Tools → WebSocket Server Settings
• Port: 4455 (default)

Setting Up Connection

1. Open OBS: Tools → WebSocket Server Settings
2. Enable WebSocket Server
3. Server Port: 4455
4. Set password (optional but recommended)
5. ltth.app: Dashboard → Settings → OBS Integration
6. WebSocket URL: ws://localhost:4455
7. Enter password (if set)
8. Click Connect

Browser Source Overlays

Main Overlay (All Features):

URL: http://localhost:3000/overlay
Width: 1920
Height: 1080
FPS: 30
☑ Shutdown source when not visible

Individual Overlays:

• Alerts: /overlay/alerts (1920x300)
• Goals: /overlay/goals (1920x200)
• Leaderboard: /overlay/leaderboard (400x600)
• Chat: /overlay/chat (400x800)

Scene Control

Switch OBS scenes automatically:

Trigger: Gift (coins >= 1000)
Actions:
  1. OBS Scene: "Celebration"
  2. Delay: 5 seconds
  3. OBS Scene: "Main"

Source Control

Show/Hide Sources:

Trigger: Gift (Rose)
Actions:
  1. OBS Source: Show "Heart Overlay"
  2. Delay: 3 seconds
  3. OBS Source: Hide "Heart Overlay"

Performance Tips

• FPS: 30 instead of 60 for browser sources
• Enable "Shutdown when not visible"
• Enable "Refresh when scene active"
• Enable hardware acceleration in OBS

VRChat OSC Integration

Control your VRChat avatar with TikTok LIVE events via OSC protocol.

Enable VRChat OSC

1. Start VRChat
2. Open Action Menu (R key)
3. Options → OSC
4. Enable OSC
5. Note the port (default: 9000)

ltth.app Configuration

1. Dashboard → Settings → VRChat OSC
2. OSC IP: 127.0.0.1 (localhost)
3. OSC Port: 9000
4. Enable VRChat OSC Integration
5. Click Connect

Avatar Parameters

Common avatar parameters:

• Wave: Wave gesture (bool/int)
• Dance: Dance animation (bool/int)
• Celebrate: Celebrate animation (bool)
• Hearts: Spawn heart particles (bool/trigger)
• Confetti: Confetti effect (bool/trigger)

Gift-to-Gesture Mapping

Gifts trigger avatar actions:

Rose → Heart particles
Lion → Dance animation
Galaxy → Celebrate + Fireworks

Example Flows

Rose Gift → Hearts

Trigger: Gift
Condition: giftName == "Rose"
Actions:
  1. VRChat OSC: /avatar/parameters/Hearts = true
  2. Delay: 2 seconds
  3. VRChat OSC: /avatar/parameters/Hearts = false

Follower → Wave

Trigger: Follow
Actions:
  1. VRChat OSC: /avatar/parameters/Wave = true
  2. TTS: "Welcome {username}!"
  3. Delay: 2 seconds
  4. VRChat OSC: /avatar/parameters/Wave = false

Plugin API

Create your own plugins for ltth.app with the Plugin API.

Plugin Structure

plugins/my-plugin/
├── plugin.json       # Metadata
└── main.js           # Plugin class

Example Plugin

class MyPlugin {
    constructor(api) {
        this.api = api;
    }

    async init() {
        // Register Express route
        this.api.registerRoute('GET', '/status', (req, res) => {
            res.json({ status: 'ok' });
        });

        // Subscribe to TikTok event
        this.api.registerTikTokEvent('gift', async (data) => {
            this.api.log(`Gift: ${data.giftName} from ${data.username}`);
        });
    }

    async destroy() {
        this.api.log('Plugin stopped');
    }
}

module.exports = MyPlugin;

Full plugin documentation: Plugin System

Troubleshooting

TikTok Connection Fails

• Make sure you are already LIVE on TikTok
• Username must be correct (without @)
• Firewall/Antivirus might be blocking the connection
• Port 3000 must be available

Overlay Not Showing

• Check browser source URL: http://localhost:3000/overlay
• Width: 1920, Height: 1080
• OBS must be running on the same PC
• Server must be running (localhost:3000 reachable)

More Help

Visit the FAQ & Troubleshooting Wiki or open a GitHub Issue.