tiktok-agent

KO | EN

gitlite — search

#python #php #nodejs #wordpress #javascript #mysql #react #android #python3 #bot #library #pandas

★ 26 Open GitHub ↗

🌟 TikTok Agent - An AI-powered tool that automatically extracts viral-worthy clips from videos and formats them for TikTok. Using engagement modeling, it identifies the most promising segments of content and transforms them into platform-ready vertical videos with options for watermarking, face detection, and custom formatting (crop, blur, or bars

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🌟 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

```bash
# 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:
# GEMINI_API_KEY=your_api_key_here
```

### 2. Frontend Setup

```bash
cd web
npm install
```

### 3. Run the App

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

**Terminal 1 (Backend):**
```bash
# From root directory
python -m app.main
```

**Terminal 2 (Frontend):**
```bash
# From web directory
npm run dev
```

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

---

## 🛠️ Usage Guide

1.  **Input**: Paste a YouTube URL or upload a video file.
2.  **Configure**: Set the number of clips, duration, and format style (Crop/Blur).
    *   *Optional*: Enable **"AI Metadata (SEO)"** to generate titles/tags (requires API key).
3.  **Analyze**: The AI scans the video (take a coffee break ☕).
4.  **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**.
5.  **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.

```bash
# 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

---

## 🏗️ 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!

tiktok-agent

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README