viral-video-blueprint
This server provides an asynchronous interface to analyze viral social media videos from Douyin, Xiaohongshu, or Bilibili and extract reusable production blueprints. You can:
Submit an analysis job by providing a video share link, optionally choosing a processing profile (
fast,balanced,deep) and an AI provider (auto,none,openai,gemini,ollama). You receive a persistent job ID.Check job status using the job ID to get the current state and any structured errors.
Retrieve results once the job is complete, getting the output directory and paths to four standard deliverables:
analysis.md(video breakdown),template.json(editing blueprint),contact-sheet.jpg(labeled frames), andtranscript.srt(timestamped speech).Manage jobs with persistent storage under
~/.viral-video-blueprint/or a customVVB_DATA_DIR.
Enables analyzing videos from Bilibili share links, extracting shot, caption, speech, rhythm, BGM, and visual evidence into a reusable blueprint.
Provides local multimodal reasoning for semantic hook, story-arc, and asset-slot analysis using a loopback-only Ollama instance.
Provides multimodal reasoning support for semantic hook, story-arc, and asset-slot analysis based on extracted video evidence, with validation and repair.
Identifies non-authoritative BGM candidates via ShazamIO, suggesting potential music tracks for the video blueprint.
Enables analyzing videos from Xiaohongshu share links, extracting shot, caption, speech, rhythm, BGM, and visual evidence into a reusable blueprint.
中文文档 | English
Viral Video Blueprint
Turn one Douyin, Xiaohongshu, or Bilibili share link into a reusable video blueprint. The tool downloads a single authorized public video, extracts evidence about shots, captions, speech, rhythm, BGM candidates, and visual elements, then produces:
analysis.md— a human-readable breakdown;template.json— a versioned reusable editing blueprint;contact-sheet.jpg— labeled representative frames;transcript.srt— timestamped speech transcription.
The source video, extracted audio, and temporary frames are deleted after success or failure. Local MP4 input, profile crawling, watermark removal, voice cloning, and media redistribution are intentionally unsupported.
Quick start
Requirements: Python 3.11/3.12, uv, and FFmpeg.
git clone https://github.com/loveld322/viral-video-blueprint.git
cd viral-video-blueprint
uv sync --all-extras --dev
uv run viral-video doctor
uv run viral-video analyze "https://b23.tv/your-authorized-video"Results are written to ./viral-video-results/.
uv run viral-video analyze "share-link" \
--output . \
--profile balanced \
--provider autoProfiles are fast, balanced, and deep. Provider choices are auto,
none, openai, gemini, and ollama.
Related MCP server: Wanyi Watermark Remover
Use as a Codex Skill
Install the repository and link the bundled Skill into Codex. The example uses
$HOME so it works on any machine; choose another checkout location if you
prefer.
git clone https://github.com/loveld322/viral-video-blueprint.git \
"$HOME/Documents/viral-video-blueprint"
cd "$HOME/Documents/viral-video-blueprint"
mkdir -p "$HOME/.codex/skills"
(
skill_source="$HOME/Documents/viral-video-blueprint/skills/replicate-viral-video"
skill_target="$HOME/.codex/skills/replicate-viral-video"
if [ -e "$skill_target" ] || [ -L "$skill_target" ]; then
printf 'Refusing to overwrite existing Skill: %s\n' "$skill_target" >&2
exit 1
fi
ln -s "$skill_source" "$skill_target"
)The command stops without changing anything if
~/.codex/skills/replicate-viral-video already exists, including as a broken
symbolic link. Inspect that path before continuing. Restart Codex after
creating the link so it discovers the Skill.
A symbolic-link installation automatically discovers the checkout from the
Skill's resolved path, including checkouts outside ~/Documents. If you copy
the Skill directory instead of linking it, set
VVB_PROJECT_DIR=/absolute/path/to/viral-video-blueprint in the Codex
environment; a detached copy cannot infer its source checkout.
Then use this prompt (replace every placeholder):
Use $replicate-viral-video to analyze this video link: <link>.
My new topic: <topic>
My product/business: <description or material path>
Target customers: <audience>
Desired action: <DM, lead form, consultation, or purchase>
Please produce a business-specific script, shot-by-shot replication table,
asset checklist, editing settings, and CTA. Keep the method and pacing, while
replacing the original people, copy, logos, watermarks, and copyrighted assets.The Skill accepts one authorized HTTPS share link from Douyin, Xiaohongshu, or
Bilibili, runs the project from skills/replicate-viral-video, and verifies
these four outputs before adapting them:
analysis.mdtemplate.jsoncontact-sheet.jpgtranscript.srt
Version 1 produces an analysis and production blueprint; it does not render a finished video.
Multimodal reasoning
Without a model, the pipeline still produces deterministic shot, text, audio,
and timing analysis with a conservative template. To get semantic hook,
story-arc, and asset-slot analysis, copy .env.example and configure OpenAI,
Gemini, or local Ollama.
Only compressed representative frames and structured evidence are sent to a
configured model, never the complete source video. Provider output is validated
against VideoBlueprint, checked for evidence references, and repaired at most
once. Model failure falls back to the deterministic deliverables.
MCP for Codex, Marvis, and AionUi
The MCP server exposes:
analyze_video(url, profile, provider);get_analysis_status(job_id);get_analysis_result(job_id).
Example client configuration:
{
"mcpServers": {
"viral-video-blueprint": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/viral-video-blueprint",
"run",
"viral-video-mcp"
]
}
}
}MCP uses local stdio by default. Jobs persist under
~/.viral-video-blueprint/, or under VVB_DATA_DIR when configured.
Supported extraction
yt-dlp primary downloader with platform-specific external fallbacks;
ffprobe, FFmpeg, and PySceneDetect for duration, shots, frames, and audio;
faster-whisper for word-timestamp transcription;
PaddleOCR for on-screen text;
librosa for BPM, beats, and energy;
ShazamIO for non-authoritative BGM candidates;
OpenAI-compatible, Gemini, or loopback-only Ollama reasoning.
Optional media dependencies are installed by uv sync --all-extras. The
offline CI suite uses generated media and performs no live platform download.
Development
uv sync --dev
uv lock --check
uv run ruff check src/ tests/
uv run mypy src/
uv run pytest -q
uv buildLegal and safety boundary
Reuse structure, pacing, shot language, public editing presets, and properly licensed music. Replace the original people, script, logos, watermarks, screenshots, brand identity, and copyrighted assets. Do not clone a real voice, extract the original narration, remove watermarks, or redistribute source music. A detected song may be reused only when your platform library or license permits it.
Licensed under Apache-2.0. See LICENSE.
Available Tools
3 toolsanalyze_videoC
提交一条视频分享链接并立即返回持久化任务 ID。
Inputs: url (required), profile, provider. Returns: object
get_analysis_resultA
获取已完成任务的结果目录和四个标准文件路径。
Inputs: job_id (required). Returns: object
get_analysis_statusC
查询视频分析任务的当前状态和结构化错误。
Inputs: job_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a distinct role: analyze_video initiates a task, get_analysis_status polls its progress, and get_analysis_result retrieves the output. There is no overlap in their purposes, making selection unambiguous.
All tools follow a consistent verb_noun pattern: analyze_video, get_analysis_status, get_analysis_result. The verbs are descriptive and the nouns align with the resource or operation, making the naming predictable and easy to follow.
With exactly 3 tools, the set is tightly scoped to the asynchronous video analysis workflow. Each tool serves a necessary step in the lifecycle (submit, check status, fetch result), and none are redundant or missing.
The tool set covers the complete flow for a single analysis job: submission, status polling, and result retrieval. There are no obvious gaps such as missing cancellation or listing capabilities, as the domain is narrowly defined and fully served.
Maintenance
Related MCP Connectors
Douyin, Xiaohongshu, TikTok, YouTube, X links to text: transcript, screen text, viral breakdown
Viral video analyzer for content creators. Share a link to a public Instagram Reel, YouTube Short or TikTok and get the opening hook and its score, why the video went viral, and a ready-to-shoot script for your own video built on the same structure. Browse trending short videos by niche for content ideas. Signs in to your ViralDecoder account; the free plan includes 3 analyses a month.
TikTok transcripts, comment sentiment by moment, AI breakdowns and director-level shot analysis.
Extract time-coded spoken transcripts, 0-3s viral hooks, visual OCR captions & UGC clone briefs.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables AI assistants to create and edit professional videos through natural language by automating JianYing (CapCut) video production workflows. Supports adding media segments, effects, transitions, animations, and exporting editable project files.20330-
- AlicenseAqualityDmaintenanceExtracts watermark-free videos and images from Douyin (TikTok) and Xiaohongshu (RedNote) share links, with optional AI-powered video transcription support.442 PyPI27Apache 2.0
- AlicenseBqualityBmaintenanceAnalyze YouTube, TikTok, and Instagram videos from URL. Extracts transcripts, generates AI insights, and pulls tutorial steps from any video link.18160 PyPI5MIT
- AlicenseNot gradedqualityDmaintenanceExtracts content from Douyin, Bilibili, Xiaohongshu, and Zhihu, and generates intelligent knowledge graphs.4MIT