[中文文档](./README_CN.md) | 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](https://docs.astral.sh/uv/), and
[FFmpeg](https://ffmpeg.org/).

```bash
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/`.

```bash
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`.

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

```bash
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):

```text
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:

```json
{
  "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

```bash
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](./LICENSE).