Skip to main content
Glama
viral-video-blueprint
by loveld322

中文文档 | 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 auto

Profiles 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.md

  • template.json

  • contact-sheet.jpg

  • transcript.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 build

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 tools
analyze_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

    A3.5/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers