🔍 douyin-insight

AI-powered short video analyzer for Douyin (抖音), TikTok, and more.

One command to download, extract frames, and analyze video content using free multimodal LLMs.

pip install douyin-insight
export GROQ_API_KEY=gsk_...  # Free at groq.com
dyi analyze https://v.douyin.com/xxxxx/

✨ Features

• 📥 Smart Download — Douyin, TikTok, and 1000+ sites (via yt-dlp)
• 🎞️ Intelligent Frame Extraction — Uniform sampling or scene-change detection
• 🧠 Multi-Provider AI Analysis — 4 free LLM providers out of the box
• 📊 Structured Output — Markdown, JSON, or custom prompts
• 🔌 Extensible — Bring your own OpenAI-compatible endpoint
• 🐍 Python API — Use as a library in your own projects

🚀 Quick Start

Installation

pip install douyin-insight

# Optional: better video download support
pip install "douyin-insight[yt-dlp]"

Requires: Python 3.9+ and ffmpeg installed.

Get a Free API Key

Usage

# Set your API key (one-time)
export GROQ_API_KEY=gsk_...

# Analyze a Douyin video
dyi analyze https://v.douyin.com/xxxxx/

# Analyze a TikTok video
dyi analyze https://www.tiktok.com/@user/video/123456

# Analyze a local video file
dyi analyze ./my_video.mp4

# More frames for longer videos
dyi analyze https://v.douyin.com/xxxxx/ --frames 16

# Scene-based frame extraction (better for varied content)
dyi analyze video.mp4 --strategy scene

# Output as JSON
dyi analyze video.mp4 --json

# Save to file
dyi analyze video.mp4 -o analysis.md

# Use a specific provider
dyi analyze video.mp4 --provider zhipu --api-key "your-key"

# Custom analysis prompt
dyi analyze video.mp4 --prompt "Count the number of people in each frame"

🐍 Python API

from douyin_insight import VideoAnalyzer

# Initialize with any supported provider
analyzer = VideoAnalyzer(
    api_key="gsk_...",
    provider="groq",  # or "gemini", "zhipu", "nvidia"
    frame_count=8,
)

# Analyze from URL
result = analyzer.analyze("https://v.douyin.com/xxxxx/")
print(result.analysis)
print(result.to_markdown())
print(result.to_json())

# Analyze local file
result = analyzer.analyze_local("video.mp4")

# Custom prompt
result = analyzer.analyze(
    "https://v.douyin.com/xxxxx/",
    prompt="What products are shown in this video? List brand names and prices if visible.",
)

# Access metadata
print(result.video_info)  # duration, resolution, codec
print(result.frames)       # list of extracted frame paths
print(result.provider)     # which LLM was used

Lower-Level API

from douyin_insight import download_video, extract_frames

# Download only
video_path = download_video("https://v.douyin.com/xxxxx/")

# Extract frames only
frames = extract_frames(video_path, count=12, strategy="scene")
# Returns: [Path('frame_000_1.2s.jpg'), Path('frame_001_5.4s.jpg'), ...]

🔧 Configuration

Environment Variables

Proxy Support

dyi analyze https://v.douyin.com/xxxxx/ --proxy http://127.0.0.1:7890

analyzer = VideoAnalyzer(api_key="...", proxy="http://127.0.0.1:7890")

🏗️ Architecture

URL → Download → Extract Frames → Vision LLM → Structured Analysis
         │              │                │
    Douyin/TikTok   ffmpeg          Groq/Gemini/
    yt-dlp/direct   uniform/scene   Zhipu/NVIDIA

📋 Requirements

• Python 3.9+
• ffmpeg (for frame extraction)
• One free API key from any supported provider

🤝 Contributing

git clone https://github.com/qq1455519358-sys/douyin-insight
cd douyin-insight
pip install -e ".[dev]"
pytest

📄 License

MIT

🙏 Credits

• yt-dlp for universal video downloading
• Groq, Google, Zhipu, NVIDIA for free API access
• ffmpeg for video processing
• Rich for beautiful terminal output