ViralLab

Engineer your influence. Turn noise into viral.

Try it live →

ViralLab scores content using Jonah Berger's STEPPS framework — behavioral science, not guesswork. Design content that spreads.

ViralLab now includes professional, project-level skill workflows for:

• strict Berger STEPPS contagious evaluation
• strict Minto Pyramid structuring (conclusion-first, grouped logic, evidence mapping)
• multi-source crawling + SEO discovery for bilingual tag coverage

English and Chinese channels use different sources. The English channel pulls from DuckDuckGo, YouTube, Hacker News, Reddit. The Chinese channel uses Weibo, Zhihu, Douyin, Baidu, Bilibili, 少数派, IT之家, 36氪, 今日头条, 掘金, and PTT (Taiwan). Bilingual users can switch between channels to digest content from each ecosystem based on their preference.

英文与中文频道使用不同来源。 英文频道来自 DuckDuckGo、YouTube、Hacker News、Reddit；中文频道来自微博、知乎、抖音、百度、B站、少数派、IT之家、36氪、今日头条、掘金、PTT（台湾）。双语用户可按偏好切换频道，获取不同生态的内容。

---

Who is this for?

Content creators — YouTubers, course builders, newsletter writers, social media managers. Anyone who wants to:

• Catch what's trending in their niche
• Know why content goes viral (science, not guesswork)
• Turn video into text for scripts, blogs, or repurposing
• Build their channel around topics that actually spread

If you create content and want to be ahead of the curve, ViralLab is for you.

---

What does it do?

1. Gather trends — Search news and videos by topic. No API keys. DuckDuckGo (global) + Bilibili (China).
2. Score with Berger — Every piece gets a 0–100 score based on Jonah Berger's STEPPS (Social Currency, Triggers, Emotion, Public, Practical, Stories) and magic words. Science-backed.
3. Video/audio to text — Paste YouTube/Bilibili/Douyin/Xiaohongshu/Shipinhao/Xiaoyuzhou/podcast links (or local media path). Export transcript markdown and score the script.
4. One dashboard — News, videos, transcripts. All in one place. Simple.

---

Professional Skill Sets Built In

Reusable Cursor Agent skills (Minto Pyramid, Berger STEPPS, crawling/SEO, platform virality, etc.) live in a single machine-wide source: ~/cursor-skills-source. Run ~/cursor-skills-source/link-to-cursor.sh once per Mac so Cursor loads them from ~/.cursor/skills/ in every project. See .cursor/skills/README.md for setup; do not duplicate those skills inside this repo.

1. Minto Pyramid Structuring (minto-pyramid-structuring)

• Enforces single governing thought, grouped key points, and mapped evidence.
• Supports strict structure for transcript-to-article workflows.

2. Contagious Berger STEPPS (contagious-berger-stepps)

• Applies auditable STEPPS scoring and diagnosis for article/video/news cards.
• Helps answer: "Which content attracts attention?" and "What should we borrow?"

3. Multi-Source Crawling + SEO (multi-source-crawling-seo, technical-seo-discovery)

• Expands discovery workflows for news, podcasts, and videos.
• Keeps EN/ZH ecosystems separated and generates hot-tag references for both.

These skills are designed for repeated, professional use across teams—not one-off prompting.

---

How to use it

Quick start (3 steps)

git clone https://github.com/Funghi88/ViralLab.git
cd ViralLab
./scripts/install.sh
./scripts/dev-server.sh

Open http://127.0.0.1:5001 in your browser.

Commands

What you want	Command
Daily news (top 3 today)	.venv/bin/python main.py --daily-news
News on a topic	.venv/bin/python main.py --search-only "AI agents"
Viral videos (ranked by spread rate)	.venv/bin/python main.py --videos "trending viral"
Videos + full transcript (markdown)	.venv/bin/python main.py --videos "AI explainer" --transcript
Single media link/file → text	.venv/bin/python main.py --video-to-text <url_or_media_path>
Web dashboard	.venv/bin/python server.py
Web dashboard (safe restart)	./scripts/dev-server.sh

In the app

• Daily News — Top stories for creators (EN/ZH). With server.py running, the digest refreshes about every 30 minutes; if output/daily_news_updated.txt is older than ~8 hours, opening /daily also kicks off a debounced background refresh. Use 立即刷新 anytime, or GET /api/refresh-daily from cron on sleeping hosts. See .env.example (DAILY_REFRESH_INTERVAL_MINUTES, etc.).
• Your field — Choose your field (fashion, tech, food, beauty, content) for curated trends, color forecasting, and reliable resources.
• Viral Videos — Search by topic (YouTube or Bilibili). Berger score, content angles, trend lifecycle.
• Long-form & Podcasts — Dedicated page for deep articles + podcast signals, with EN/ZH hot-tag references.
• STEPPS & Magic Words — Learn how we score. Jonah Berger's framework, explained.
• Video to Text — Paste platform URL/audio link (or local media path) → markdown transcript + Berger score + Minto structure tab.
• Article Lab + Publish Queue — Rewrite markdown with Minto + STEPPS, then queue/approve publish to X or blog.
• WeChat 公众号 / 小红书 — ViralLab 不内置 mp/小红书后台自动化。定稿 markdown 后，在 Cursor 里让 Agent 按全局技能 wechat-mp-auto、xiaohongshu-auto 操作浏览器发布（真源 ~/cursor-skills-source，先跑 link-to-cursor.sh）。发布页 /publish 有简要说明。详见 .cursor/rules/virallab-cursor-publish-handoff.mdc。
• Workflow hardening — Publish queue includes duplicate prevention, quality warnings, and audit events for safer agentic automation.

---

Why Berger?

We use Jonah Berger's research from Contagious and Magic Words. Not random. Not algorithmic engagement hacks. Behavioral science — what actually makes people share.

High score = content that taps into social currency, emotion, practical value, stories. The stuff that spreads.

---

Install

./scripts/install.sh

Python 3.12+. No API keys for news/videos.

Publish queue webhooks (optional):

X_PUBLISH_WEBHOOK=https://your-endpoint/x
BLOG_PUBLISH_WEBHOOK=https://your-endpoint/blog

If webhook is unset, publish actions are still tracked locally in output/publish_queue.json.

Transcript coverage (recommended):

pip install videocaptioner

ViralLab uses YouTube captions first when available. For Bilibili, Douyin, Xiaohongshu, Shipinhao, Xiaoyuzhou, and broader podcast/audio links, VideoCaptioner enables ASR fallback transcript generation.

Douyin → transcript: Prefer pasting a local video/audio path on the Video to Text page after saving the clip (most reliable). Optional URL flow uses VideoCaptioner and/or yt-dlp; Douyin URLs often fail without douyin.com cookies Netscape config/ytdlp_cookies.txt (see config/README-ytdlp-cookies.md / YTDLP_COOKIES_FILE — app-only login is not enough). Set VIRALLAB_VIDEOCAPTIONER_BIN if Videocaptioner lives outside this repo.

Higher-quality ASR (optional): Install WhisperX for multilingual speech-to-text with word-level timestamps and alignment (better for subtitles and noisy short video). Requires ffmpeg on your PATH. With no VIRALLAB_WHISPER_MODEL set, GPU/MPS use large-v3; on CPU, VIRALLAB_WHISPER_MAX_ACCURACY=1 (default) also uses large-v3 (slower), or set it to 0 for medium only on CPU.

pip install -r requirements-asr.txt

Environment variables: see .env.example (VIRALLAB_ASR_ENGINE, VIRALLAB_WHISPER_MODEL, VIRALLAB_WHISPER_MAX_ACCURACY, VIRALLAB_WHISPER_DEVICE, VIRALLAB_WHISPER_BATCH_SIZE, VIRALLAB_WHISPER_LOG, VIRALLAB_FFMPEG_AF_PRESET). Default VIRALLAB_ASR_ENGINE=auto uses WhisperX when installed, otherwise VideoCaptioner. Render and other small hosts often omit this extra stack; keep requirements.txt only for minimal deploys. VIRALLAB_WHISPER_LOG (default on) toggles stderr lines prefixed with [whisperx]: the pre-run settings line and a short [whisperx] error: … line if ASR fails (no traceback); set to 0 to silence both.

China users: DuckDuckGo and YouTube require VPN. Use our China sources (Bilibili, Douyin, Xiaohongshu, Shipinhao) for content without VPN. See CHINA_ACCESS.md.

Platform note: Some sources (e.g. TikTok/Douyin/Xiaohongshu/Shipinhao) are constrained by platform policies. ViralLab supports a hybrid approach: official search links + optional crawler outputs where feasible.

China crawler (optional): To add content from Xiaohongshu, Douyin, Zhihu, and Shipinhao to the China viral feed: use the Fetch card on the Viral page (source = China), or run the CLI:

pip install playwright
playwright install chromium
.venv/bin/python -m tools.china_crawler run --platform xhs --keywords "关键词"
# Or: bilibili, douyin, shipinhao, zhihu

Results are written to output/china_crawler_<platform>.json. The app merges them into the China list and shows content type (video, post, article, note). Many platforms may require login for full results. See docs/CHINA_SOURCES_ROADMAP.md.

---

Deploy

Deploy to Render

1. Click the button above (or go to render.com → New → Web Service).
2. Connect your GitHub and select the ViralLab repo. Render detects render.yaml.
3. Add env vars if needed: OPENAI_API_KEY or GEMINI_API_KEY for AI features.
4. Deploy. Live at virallab.onrender.com.

Keep content fresh: cron-job.org → Create job → URL: https://virallab.onrender.com/api/refresh-daily?key=YOUR_CRON_SECRET → Daily at 8:00.

See DEPLOY.md for full instructions.

---

For developers

• China Access — VPN requirements, China sources (Bilibili, Douyin, Xiaohongshu, Shipinhao). See CHINA_ACCESS.md.
• API — GET /api/digests (list), GET /api/digests/<filename>, GET /api/export/<filename>?format=markdown|notion|obsidian, GET /api/viral-videos?q=<query>&source=global|china, POST /api/video-to-text.
• China crawler — tools/china_crawler: optional Playwright-based XHS search; output merges into China viral when present. docs/CHINA_SOURCES_ROADMAP.md.
• Project skills — Professional reusable workflows live in .cursor/skills/:
  • minto-pyramid-structuring
  • contagious-berger-stepps
  • multi-source-crawling-seo
  • technical-seo-discovery