Metadata-Version: 2.3
Name: douyin-insight
Version: 0.1.0
Summary: AI-powered short video analyzer — Douyin, TikTok, and more. Extract, analyze, and summarize video content using free multimodal LLMs.
Project-URL: Homepage, https://github.com/qq1455519358-sys/douyin-insight
Project-URL: Repository, https://github.com/qq1455519358-sys/douyin-insight
Project-URL: Issues, https://github.com/qq1455519358-sys/douyin-insight/issues
Author-email: Z S <qq1455519358@gmail.com>
License: MIT
Keywords: ai,content-analysis,douyin,llm,multimodal,tiktok,video-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: rich>=13.0
Provides-Extra: all
Requires-Dist: yt-dlp>=2024.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: yt-dlp
Requires-Dist: yt-dlp>=2024.0; extra == 'yt-dlp'
Description-Content-Type: text/markdown

# 🔍 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.

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

```bash
pip install douyin-insight

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

**Requires**: Python 3.9+ and [ffmpeg](https://ffmpeg.org/) installed.

### Get a Free API Key

| Provider | Free Tier | Get Key |
|----------|-----------|---------|
| **Groq** (recommended) | 1000 req/min | [console.groq.com](https://console.groq.com) |
| Google Gemini | 15 req/min | [aistudio.google.com](https://aistudio.google.com) |
| Zhipu/GLM | Unlimited | [open.bigmodel.cn](https://open.bigmodel.cn) |
| NVIDIA NIM | Free tier | [build.nvidia.com](https://build.nvidia.com) |

### Usage

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

```python
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

```python
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

| Variable | Provider |
|----------|----------|
| `GROQ_API_KEY` | Groq (Llama 4 Scout) |
| `GOOGLE_API_KEY` | Google Gemini |
| `ZHIPU_API_KEY` | Zhipu GLM-4V |
| `NVIDIA_API_KEY` | NVIDIA NIM |
| `DYI_API_KEY` | Generic (use with `--provider`) |

### Proxy Support

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

```python
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

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

## 📄 License

MIT

## 🙏 Credits

- [yt-dlp](https://github.com/yt-dlp/yt-dlp) for universal video downloading
- [Groq](https://groq.com), [Google](https://aistudio.google.com), [Zhipu](https://open.bigmodel.cn), [NVIDIA](https://build.nvidia.com) for free API access
- [ffmpeg](https://ffmpeg.org/) for video processing
- [Rich](https://github.com/Textualize/rich) for beautiful terminal output
