🛰️ Trend Rover

Know how your brand is trending on YouTube & X — in one command.
Real-time social listening for marketers, founders, and growth teams.

🚀 Quick Start · 📊 Dashboard · 🇨🇳 中文文档 · 🤝 Contributing

---

Trend Rover scrapes YouTube and X (Twitter) in real time, collects engagement metrics (views, likes, comments, shares, bookmarks), detects your brand logo in video thumbnails, and exports clean summary reports — all from a single CLI command or a polished web dashboard.

💡 Built to answer the question every marketing team asks on Monday morning: "How is our brand performing on social media this week?"

Why Trend Rover?

• 🎯 Keyword-first — track any brand, product, or campaign across platforms at once
• 👀 See the trend, not just the data — built-in tables and line charts surface momentum at a glance
• 🔍 Logo-aware — finds your brand even when it's only in the thumbnail, not the title
• ⚡ Zero infra — local SQLite, no cloud account, no API keys required to start
• 🤖 AI-native — query your data in plain English via the Claude Code skill

⭐ If Trend Rover saves you time, star the repo — it genuinely helps others find it.

Features

• Multi-platform search — YouTube and X, unified keyword search with date ranges
• Engagement tracking — Views, likes, comments, shares, bookmarks per post
• Logo detection — Finds your brand logo in YouTube thumbnails via OpenCV or LLM (Claude / OpenAI)
• YouTube filters — Filter by video type (video / shorts / live), duration, sort order
• Gradio dashboard — 4-tab web UI: Search, Stats, Detail, Export
• CSV export — One-command summary reports, ready for spreadsheets
• Claude Code skill — Use /trend-rover in Claude Code for natural language queries
• SQLite storage — Local database with automatic deduplication

Quick Start

Install

# Requires Python 3.11+
git clone https://github.com/user/trend-rover.git
cd trend-rover
python -m venv .venv
source .venv/bin/activate
pip install trend-rover
playwright install chromium

Search

# Search YouTube and X for "Pokekara" in April 2026
trend-rover search "Pokekara" \
  --platform youtube x \
  --since 2026-04-01 \
  --until 2026-04-30

# YouTube only, shorts, sorted by views
trend-rover search "Pokekara" \
  --platform youtube \
  --since 2026-04-01 \
  --until 2026-04-30 \
  --type shorts \
  --sort-by views

Logo detection

# Find videos containing your brand logo in thumbnails
trend-rover search "Pokekara" \
  --platform youtube \
  --since 2026-04-01 \
  --until 2026-04-30 \
  --logo ./brand-logo.png \
  --vision-engine opencv

Stats & Export

# View aggregated stats
trend-rover stats "Pokekara" \
  --platform youtube x \
  --since 2026-04-01 \
  --until 2026-04-30

# Export summary CSV
trend-rover export "Pokekara" \
  --platform youtube x \
  --date 20260426 \
  --output ./report.csv

Dashboard

trend-rover dashboard --port 7860

Opens a Gradio web UI at http://localhost:7860 with four tabs:

Tab	What it does
Search	Search by keyword, platform, date range, filters, and logo
Stats	View aggregated engagement metrics
Detail	Browse individual posts with metadata
Export	Download summary CSV

See your brand's momentum at a glance — daily post counts and view totals in a clean table, plus a trend line that makes spikes obvious:

Daily breakdown of posts and views for a tracked brand keyword

Trend line chart — spot the spikes and track brand heat over time

Claude Code

If you have Claude Code installed:

/trend-rover
> Search YouTube for Pokekara videos from last month

Architecture

trend_rover/
├── cli.py              # argparse entry point
├── orchestrator.py     # Search pipeline: scrape → detect → store
├── models.py           # Feed dataclass
├── config.py           # TOML config loader
├── scrapers/
│   ├── youtube.py      # Playwright + XHR intercept
│   ├── x.py            # Playwright + scroll + cookie auth
│   └── _utils.py       # UA rotation, retry, delay
├── vision/
│   ├── opencv.py       # Multi-scale template matching
│   └── llm.py          # Claude / OpenAI vision API
├── storage/
│   ├── db.py           # SQLite with upsert
│   └── export.py       # Transposed CSV export
├── dashboard/
│   └── app.py          # Gradio 4-tab UI
└── skill/
    └── trend-rover.md  # Claude Code skill

Configuration

Create trend_rover.toml in your project root:

[scraper]
min_delay = 2.0
max_delay = 5.0
max_retries = 3

[vision]
engine = "opencv"        # "opencv" or "llm"
threshold = 0.8

[llm]
provider = "claude"      # "claude" or "openai"
api_key = "sk-..."
model = "claude-sonnet-4-6"

[x]
cookies_file = "./x_cookies.json"

Development

git clone https://github.com/user/trend-rover.git
cd trend-rover
python -m venv .venv
source .venv/bin/activate
pip install -e .
playwright install chromium

# Run tests (62 tests)
pytest tests/ -v

Contributing

We welcome contributions! Here are some ways to get involved:

• Add a new platform — Instagram, TikTok, Reddit, LinkedIn
• Improve scrapers — Better anti-detection, proxy support, rate limiting
• Enhance logo detection — YOLO/CLIP models, batch processing
• Dashboard features — Charts, trend visualization, comparison views
• Internationalization — More languages for UI and reports
• Documentation — Tutorials, examples, deployment guides

How to contribute

1. Fork the repo
2. Create a feature branch (git checkout -b feat/add-instagram)
3. Write tests first (we use TDD)
4. Make your changes
5. Run pytest tests/ -v to ensure all tests pass
6. Submit a PR

License

MIT

Star History

If Trend Rover helps your team track what matters, give it a ⭐ — it's the single best way to help others discover the project and keeps us motivated to ship more.