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

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.