🌟 TikTok Agent

TikTok Agent is an advanced AI-powered tool that automatically extracts viral-worthy clips from long-form videos and formats them for TikTok, YouTube Shorts, and Instagram Reels.

It features a stunning Neon Glass / Cyberpunk Lab UI where you can review AI-selected candidates, manually trim clips with frame precision, and batch render your final videos.

---

✨ Features

• 🤖 AI Viral Detection: Automatically identifies the most engaging segments using motion scoring and scene analysis.
• 💎 Neon Glass UI: A premium, "Dark Mode Glassmorphism" interface with animated ambient backgrounds and bento-grid layout.
• ✂️ Precision Trimmer: Watch AI-selected clips and fine-tune start/end times with a frame-perfect scrubber before rendering.
• 📱 9:16 Auto-Formatting: Smart cropping and background blur modes to convert landscape video to vertical format.
• 🎯 Smart Hook Optimization: Automatically detects and preserves the most engaging "hook" moments.
• 📝 AI Metadata Generator: Generates viral titles, descriptions, and hashtags using Google Gemini LLM.
• 💾 Job Persistence: Automatically saves your progress and job history, so you never lose your work.
• 📜 History Dashboard: View past jobs, check their status, and easy access to results.
• 🌊 Watermarking: Add custom text or image watermarks.
• 📥 Multi-Source: Support for YouTube URLs and local file uploads.

---

🚀 Quick Start (Web App)

Prerequisites

• Python 3.8+
• Node.js & npm
• FFmpeg (must be in your system PATH)
• Google Gemini API Key (optional, for AI metadata)

1. Backend Setup

# Clone the repository
git clone https://github.com/yourusername/tiktok_agent.git
cd tiktok_agent
Create virtual environment (optional but recommended)
python -m venv venv
Windows
venv\Scripts\activate
Mac/Linux
source venv/bin/activate
Install Python dependencies
pip install -r requirements.txt
Setup Environment Variables
Create a .env file and add your API key:
GEMINIAPIKEY=yourapikey_here

2. Frontend Setup

cd web
npm install

3. Run the App

You need to run the backend and frontend in separate terminals.

Terminal 1 (Backend):

# From root directory python -m app.main

Terminal 2 (Frontend):

# From web directory npm run dev

Open your browser at http://localhost:5173 to start creating!

---

🛠️ Usage Guide

• Input: Paste a YouTube URL or upload a video file.
• Configure: Set the number of clips, duration, and format style (Crop/Blur).

Optional*: Enable "AI Metadata (SEO)" to generate titles/tags (requires API key).

• Analyze: The AI scans the video (take a coffee break ☕).
• Review:

* You'll see a list of "Viral Candidates" found by the AI. * Click Adjust on any clip to open the Trimmer. * Use the sliders to fix the timing. * Click Confirm.

• Render: Click "Render All Clips" to generate the final MP4s.

---

💻 CLI Usage (Advanced)

You can also use the tool purely from the command line for automation.

# Process a YouTube video
python main.py --youtube https://youtu.be/VIDEO_ID --num-clips 3
Process a local file
python main.py --file video.mp4
Advanced options
python main.py --file video.mp4 --format blur --watermark --watermark-text "@MyChannel"

Key Arguments

| Argument | Description | Default | | :--- | :--- | :--- | | --youtube | YouTube URL to download | | | --file | Local file path | | | --num-clips | Number of clips to extract | 1 | | --duration | Target duration in seconds | 15.0 | | --format | crop (center), blur (blurred bg), bars | crop | | --use-gpu | Enable GPU acceleration | False |

---

🏗️ Architecture

• Backend: Python, FastAPI (Modular app/ structure), OpenCV, PyTorch, MoviePy
• Persistence: JSON-based job history storage (jobs.json)
• Frontend: React, Vite, TailwindCSS (Neon/Glass Theme), Lucide Icons
• AI Models:

* Face Detection: MediaPipe / OpenCV DNN * Visual Interest: Motion energy & scene complexity analysis

---

📄 License

MIT License. Free to use and modify!