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

Legal 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.