YvanDeng/viral-video-distiller-pro

Viral Video Distiller Pro

Transforms a video into an auditable evidence package, a readable distillation report, and a directly executable original structure migration plan. The core principles: investigate first, then analyze; separate facts from inferences; and explicitly downgrade any claim without supporting evidence.

Triggering & Intent Routing

Priority is given to "one-sentence use." Do not require the user to restate evidence levels, cut detection algorithms, timeline coverage, or validation rules.

Automatic Triggering

Enter this Skill if any of the following is true:

• The text contains video semantics such as "analyze"/"dissect"/"break down"/"remake"/"duplicate"/"study"/"research" along with "video"/"short video"/"Douyin"/"TikTok"/"Reels"/"Xiaohongshu"/"Bilibili"/"YouTube"/"vocal".
• The input contains a recognizable video platform URL, e.g., douyin.com, v.douyin.com, tiktok.com, xiaohongshu.com, xhslink.com, bilibili.com, b23.tv, youtube.com, youtu.be, instagram.com/reel.
• The input contains a local video path or attachment with extension .mp4, .mov, .mkv, .webm, .m4v, .avi, .flv, .ts.
• The user provides only a video link/video file without a verb: default to "analyze this video"; pre-check first, do not require a long prompt.

Do Not Trigger or Escalate

• Only PDF, Word, web article, image, or audio analysis without video analysis intent.
• Only requests to play, upload, compress, transcode, download, or delete a video, without content deconstruction.
• Only a quick video summary explicitly excluding hooks, shots, interactions, or production scripts; use standard video summarization capability.

Default Behavior for "Analyze" vs. "Remake"

• "Analyze"/"Dissect"/"Break down": directly generate a complete distillation production package.
• "Remake"/"Duplicate": first automatically complete the original video analysis; if the user has already provided a new topic/audience, continue to generate an original migration script.
• User says "remake" but has no new topic: do not interrupt the analysis, first deliver the original distillation and replaceable slots; only ask one brief question when generating the specific new script truly requires a topic.
• It is forbidden to ask the user to confirm shots, evidence levels, algorithm thresholds, score weights, or report fields; these are the Skill's internal responsibility.

Recommended user prompt: Help me analyze and remake this Douyin video: <link>.

Applicable Input

• Local .mp4, .mov, .mkv, .webm.
• Public Douyin links; only analyze content the user has the right to access and study.
• Optional supplement: platform data screenshots/JSON, target audience, new topic, account positioning.

If only text, audio, or keyframes are available, partial analysis can be done, but a full video distillation must not be claimed. Mark modules that cannot be verified as N/A.

Mandatory Deliverables

The final directory is both a report package and a production asset package that can be further edited and audited:

• Nine core files: distillation-report.md, evidence.json, transcript.json, word-for-word-script.md, per-second-timeline.csv, remake-production-script.md, capcut-execution-checklist.md, asset-checklist.md, quality-self-inspection-report.md.
• Production assets: source_video.mp4, keyframes/, audio-and-transcription/, storyboard-files/, remake-sop.md.

Place reconstructable runtime garbage (.venv, model cache, __pycache__, download temp files, etc.) in work/ outside the delivery directory. Video, frames, audio, transcriptions, storyboards, and SOP are verifiable process assets and must be delivered.

Execution Workflow

1. Preflight & Authorization Boundaries

Run:

python3 scripts/preflight.py "<local path or link>"

• If the local file does not exist, confirm the path first.
• For Douyin links, run download_douyin.py: first try yt-dlp; if it requires fresh cookies, login/captcha fails, or the environment lacks yt-dlp, the script automatically requests the share page HTML, extracts restricted Douyin/ByteDance video CDN candidates, downloads, and verifies with ffprobe. If both paths fail, only then ask the user for a local video.
• The share page fallback must not print, save, or write fully signed CDN URLs, cookies, or auth parameters into reports; must not bypass login, captcha, paywall, or private content access controls. Only process public share links the user has the right to analyze.
• Do not generate a per-second report solely based on the title, thumbnail, or web page summary.

2. Establish Working and Delivery Directories

python3 scripts/scaffold_delivery.py <output directory> --source "<source>"

Use assets/templates/distillation-report.md as the report body template.

The output directory holds production assets; set up the runtime environment and cache in a sibling work/ directory or system temp directory; do not create .venv in the output directory.

3. Extract Deterministic Evidence

For local videos, run:

python3 scripts/extract_evidence.py <video> <working directory/evidence>

This tool extracts media metadata, a 16kHz mono analysis audio track, silence intervals, scene candidate cut points, and 1fps keyframes. It normalizes and copies the original video as source_video.mp4, saves keyframes to keyframes/, and analysis audio with raw ASR results to audio-and-transcription/. Fully read references/automated-visual-analysis.md: automatically confirm shot cuts through multi-signal analysis; automatically downgrade low-confidence results to suspected shot cuts or internal visual events. The analysis process does not require human involvement, nor should a single scene threshold result be presented as an actual shot.

3a. Obtain Timestamped Vocal Transcription (ASR)

Prefer to run Whisper (small model, cross-platform, supports Chinese):

python3 scripts/run_asr_whisper.py <video or audio> <delivery directory> [--model small] [--language zh]

• On first use, the model (~460MB for small) is automatically downloaded and cached locally, and dependencies must be installed: pip install openai-whisper (or faster-whisper).
• The script outputs a transcription with start and end timestamps, merges it into evidence/raw_evidence.json (with analysis_mode.asr="A", speech_metrics, and ev-asr evidence items), and generates transcript.json, word-for-word-script.md, and audio-and-transcription/asr_raw.json.
• ASR original text is immutable: each segment retains raw_text; reliable corrections are written to normalized_text, with corrections registered in corrections[] (original word, corrected word, basis, confidence). Do not correct without reliable basis.
• If whisper is unavailable and cannot be installed: mark the corresponding module as N/A, do not fabricate speech rate; if other ASR tools are available, merge their output, register it as ev-asr with the actual grade.

If the environment has OCR capability, generate subtitle observations and merge them into the evidence register; if not, mark the corresponding module as N/A or use direct multimodal observation marked as B. Do not fabricate for completeness.

4. Build the Unified Evidence Package

Fully read references/evidence-schema.md and references/analysis-protocol.md. Merge raw_evidence.json into evidence.json in the delivery directory:

• Register each observation with a unique evidence ID.
• All conclusions must reference evidence_ids.
• For C-level inferences, write a rationale and explain alternative interpretations.
• Before delivery, write delivery_metrics.evidence_item_count = len(evidence_items); the Quality Self-Inspection Report must reference this value, not manually sum items.
• When using phrases like "external source/official project/cross-validation", register the source in external_sources[] (id/title/url/accessed_at/grade); related conclusions must reference it via external_source_ids; if not registered, delete the phrasing and do not imply verification.
• per-second-timeline.csv must have one row per second and continuously cover at least 95% of the video; fill in visual_evidence_ids, audio_evidence_ids, subtitle_evidence_ids, and each modality's confidence. Visual facts can only reference frames, OCR, or direct multimodal observation; ASR alone cannot support visual descriptions. Audio and subtitles follow the same rule. Each row must reference at least one temporally adjacent evidence item with a span of no more than 15 seconds that overlaps with that second. Blank frames, black frames, and silence must also occupy a row and specify the state.
• The hook is fixed to cover 0.000–3.000 seconds; information from after 3 seconds must not be borrowed.

5. Analyze Viral Mechanisms

Analyze in the following order, avoiding premature conclusions:

1. First frame, first sentence, subtitles, sound, promise, and information gap.
2. ASR pauses + semantic transitions + segment boundaries from candidate shot cuts.
3. Only calculate Chinese characters per minute, semantic pauses, and stress if full ASR is available; without ASR, precise vocal metrics are N/A. Analyze acoustic pauses, BGM, sound effects, and loudness independently.
4. Report candidate cut points, auto-confirmed shot cuts, suspected shot cuts, subtitle refreshes, and internal visual events separately. Explain the deduplication approach for overall visual refresh rate.
5. Subtitle position, screen ratio, number of lines, color, keyword emphasis, appearance/exit animations. If OCR/keyframe coverage is less than 95%, only write "observed consistent/basically consistent at sample points," never "strictly synchronized throughout the video."
6. Engagement prompts: original sentences, timestamps, target actions, and leave-a-message mechanisms.
7. Five-part ending: like, follow, bookmark, next episode preview, open-ended question.
8. Automatically calculate scores, coverage, and missing dimensions using fixed eight-dimensional weights; never manually fill in the total score. Scoring is evidence-based; do not assume a high score just because the user calls it a hit.
9. For each core segment, generate expert insights in the format "Fact → Mechanism → Audience Reaction → Migration Formula"; never just describe the visuals.

6. Generate the Structure Migration Production Package

Fully read references/report-contract.md, fill in the distillation-report.md template. Then output:

"One-sentence conclusion": first fill in the eight slots in evidence.json.executive_summary, then combine into a compact paragraph. The toolchain can only be a C-level inference, and the rationale and alternative explanations must be listed simultaneously; without platform data, use "propagation mechanism," never directly assert "reason for virality."

If the toolchain is only a C-level inference, remake-production-script.md can only contain tool-agnostic workflows or explicitly marked candidate implementations; never upgrade an inferred software name to a definitive dependency, version, installation command, or CLI. Only after actual execution verification with toolchain_inference.execution_verified=true and documented verification evidence can definitive commands be given.

• remake-production-script.md: timing, functional slots, original vocal script, visuals, subtitles, sound effects, interaction purpose.
• storyboard-files/storyboard-table.csv: fixed fields time_range,shot_function,normalized_visual_text,normalized_spoken_text,asset_ids,evidence_ids,confidence. Use transcript.json.normalized_text for vocal; keep original OCR evidence for on-screen text and normalize separately; never feed obvious recognition noise directly to the editor. Also place editing projects or EDL/XML in this directory.
• remake-sop.md: sequential operational steps from topic migration, script, storyboard, asset preparation, editing, quality check, to publishing.
• capcut-execution-checklist.md: tracks, cut points, subtitle templates, keyframes, volume, export & pre-publish checks.
• asset-checklist.md: asset role, specifications, source/authorization status, alternatives; never reuse original video assets.
• word-for-word-script.md and transcript.json: preserve timestamps, speaker, confidence.
• quality-self-inspection-report.md: record evidence gaps, automatic downgrade results, gating results, and low-confidence lists; no need for human review before delivery.

"One-to-one remake" here only means one-to-one mapping of structural slots, rhythm nodes, and shot functions; lines, examples, people, brands, music, and visual assets must be original or licensed.

7. Run Production Gate

python3 scripts/validate_delivery.py <delivery directory>

Only output PASS to claim complete delivery. On failure, fix errors one by one; do not delete rules to bypass.

8. Progressive Remake Guidance After Analysis

After the analysis package passes the gate, do not only list file paths, and do not ask the user to submit all materials at once. Copy assets/templates/remake-brief.json to the delivery directory, then ask only one currently necessary question at a time in the following order; write the user's answer into the brief immediately, then proceed to the next step:

First, run the deterministic orchestration script so subsequent steps consume analysis artifacts:

python3 scripts/create_remake_project.py init --analysis <analysis delivery directory> --output <original remake project directory>

The script reads the report, remake production script, SOP, timeline, normalized storyboard, asset and CapCut checklists, generates remake-context.json, and returns the unique next_field/question. After each user answer, execute:

python3 scripts/create_remake_project.py set --output <original remake project directory> --field <next_field> --value "<user answer>"

1. New Topic: First ask "What new topic do you want to migrate this structure to?" This is the only required question without a reliable default.
2. Target Audience: Recommend an audience based on the topic and let the user confirm; if the user already has an account positioning, use it directly.
3. Duration & Aspect Ratio: Provide recommendations based on the reference video and publishing platform (e.g., Douyin default 60 seconds, 9:16); bundle these two strongly correlated parameters in one confirmation.
4. Presentation Style: Recommend one from: live talking head, screencast, PPT/text animation, pure stock footage montage; ask only for confirmation or change.
5. Ending Action: Recommend a primary CTA (follow, bookmark, comment question, or private domain redirect) based on the account stage.
6. Available Assets: Only at the end ask if the user has avatar, logo, screencast, images, voiceover, or brand colors. If no assets, do not block; provide a fallback plan with TTS + original placeholder graphics + pure text animation.

At each step, first show "Confirmed content + the single question to answer now." If the user says "you decide/default is fine," use the recommended value and continue without repeating the question. Once enough information is gathered, automatically generate the original remake project package: original vocal script, SRT, normalized storyboard, asset gap table, CapCut execution checklist, publishing copy, and render-manifest.json.

When the script returns status=ready, run:

python3 scripts/create_remake_project.py build --output <original remake project directory>

The Agent must then read generation-tasks.md, remake-context.json, and remake-brief.json, and fill in the original content of the project package; do not pass off placeholder skeletons generated by the script as completed work.

The current Skill's "one-click generation" boundary is: one-click generation of an executable remake project package, not a promise to output an MP4 directly. Only if the runtime has and actually verifies a Remotion, CapCut draft, or other rendering backend can render_backend be changed to that backend and a finished video be claimed.

The first prompt after analysis completion is always:

The analysis is done. Next, I can help you migrate it into an original video. We'll confirm one thing at a time. First, tell me: what new topic do you want to tell using this structure?

Downgrade Matrix

Available Evidence	Can Complete	Must Mark N/A
Video + FFmpeg + ASR + OCR	Full analysis	Platform data that cannot be verified
Video + FFmpeg + Whisper ASR	Media, audio candidates, shot candidates, visual observations, vocal with word-level timestamps	OCR metrics
Video + FFmpeg, no ASR/OCR	Media, acoustic pauses, shot candidates, visual observations	Vocal speed, semantic rhythm, stress, emotional curve, vocal scoring & OCR metrics; remove vocal dimensions from total score and re-normalize
Only audio/timestamped transcription	Vocal, narrative, partial interactions	Shot density, visual subtitle packaging
Only text	Script structure and candidate interactions	All precise audio-visual metrics
Link download fails	Information visible at link level	Per-second video analysis; request local file

Prohibited Items

• It is prohibited to fabricate play count, publish date, ASR, subtitle colors, shot count, or toolchain.
• It is prohibited to directly treat algorithm candidate cut points as auto-confirmed shot cuts.
• It is prohibited to require manual confirmation or set human review as a prerequisite for delivery; low-confidence results must be automatically downgraded.
• It is prohibited to estimate precise speech rate, stress, or semantic pauses without ASR.
• It is prohibited to fill in vocal semantic rhythm, emotional curve, or vocal scoring without ASR; these must be marked N/A and removed from the composite score denominator.
• It is prohibited to use long-interval tables in place of a per-second timeline.
• It is prohibited to pad the per-second timeline with repeated chapter summaries, or use full-video evidence as direct evidence for a specific second.
• It is prohibited to use ASR evidence to support visual facts (color, composition, shot, subtitle style), or to use a single composite confidence metric to mask modality evidence gaps.
• It is prohibited to claim "subtitles strictly synchronized throughout the video" under sparse OCR/keyframe sampling.
• It is prohibited to silently rewrite ASR original text; normalized text must retain raw_text and corrections for traceability.
• It is prohibited to manually estimate the total number of evidence items, or claim cross-validation with external sources without registering external_sources.
• It is prohibited for storyboards to continue using original misrecognized words already corrected by corrections; storyboards must include asset, evidence, and confidence fields.
• It is prohibited to place .venv, model cache, or temporary download files in the final delivery; it is also prohibited to delete the original video, keyframes, analysis audio, transcription, storyboards, or remake SOP.
• It is prohibited to write C-level toolchain inferences as definitive dependencies or installation/initialization/render commands without execution verification.
• It is prohibited to output composite scores that cannot be recalculated with fixed weights.
• It is prohibited to use "approximately"/"presumably" to cover up unsupported precise numbers.
• It is prohibited to copy long segments of original dialogue, brand packaging, music, or video assets.
• It is prohibited to output only a polished report without evidence.json and validation results.
• It is prohibited to terminate after yt-dlp's first failure: public Douyin share links must automatically attempt the share page CDN fallback; only request a local file after the fallback fails.
• It is prohibited to log or echo cookies, fully signed CDN URLs, or auth query parameters from the share page, nor use the fallback to bypass access controls.