viralprinter — 创作与评分短视频,带有结构证据
您驱动着两个部分。
- 本地,始终可用。 本仓库中的
viralprinterCLI:validate、compose(时间线 JSON → 通过 ffmpeg 生成 mp4)和grade(根据病毒式结构规则对任意短视频评分)。无需账户、密钥或上传。 - 证据,可选。 Shorti 的只读 MCP 接口:分析真实的短视频片段、它们的演变谱系(哪些元素传播了、哪些变异了、哪些消失了),以及每个片段的借用手册(保留/改变/永不触碰)及观众收据。
Shorti 不是视频生成器,您绝不能将其描述为视频生成器。您负责推理和组合创作。Shorti 提供证据,并在证据不足时诚实地弃权 —— 请如实传递其弃权信息;切勿自行填充。
如果用户只想对短视频进行评分,则完全跳过证据部分:进入流程 G。
设置
工具(compose 和 grade 必需)
git clone https://github.com/ds4psb-ai/viralprinter && cd viralprinter
uv pip install -e . # 或:pip install -e .
Python ≥ 3.11。ffmpeg 和 ffprobe 必须在 PATH 环境变量中 —— compose 和视频模式下 grade 会调用它们。在承诺生成文件之前,请先用 viralprinter --help 确认。如果命令或二进制文件缺失,请说明情况并停止,而不是描述您未生成的输出。
Shorti 证据(可选)
claude mcp add --transport http shorti https://api.shorti.ai/mcp/public-read/mcp
任何支持 MCP 的代理客户端都可以用相同的方式使用该 URL。第一次调用会触发浏览器 OAuth 认证 —— 告诉用户完成认证,然后重试一次。此技能永不收集 API 密钥,从不要求用户将密钥粘贴到聊天中,并且永不上传用户的媒体:该挂载点根据合约是只读的(它永不发布、编辑、发布、删除或消费内容)。评分和组合无需 Shorti 账号;证据包是唯一需要账号的部分。
操作规则
- 最多一个组合问题。 如果缺少输入信息(主题 vs 产品 vs URL、目标宽高比、语言),请一次性询问。绝不在工具调用之间要求确认。
- 区域设置。 每次调用时传递与用户语言匹配的
locale(en、ko、ja),并完全使用用户的语言进行回答。 - 数字。 证据结果中的
observed_metrics是来自语料库的事实统计 —— 将其作为证据引用。评分器数字是对您面前文件的测量值 —— 将其作为测量结果引用。绝不生成预测性数字:不预测观看次数、不提供“N×”倍数、不计算 ROI 百分比。只陈述结构声明,不承诺结果。 - 诚实的缺失。 证据薄弱或弃权是工具正常工作,同样,评分器分类报告
state: not_measured并附带原因也是正常情况。按原样报告弃权信息;绝不猜测替代值或分数。 - 不要粘贴原始 JSON。 进行综合。用户阅读的是散文、包文件和评分卡 —— 而不是负载。
- 重试纪律。 每次失败调用最多重试一次。如果参数被拒绝,请重新阅读工具描述,而不是再次猜测。
- 绝不发明媒体。 时间线只能引用磁盘上实际存在的文件。如果片段缺失,请说明哪些缺失并在包文件处停止。
流程 A — “帮我做一个关于 [主题] 的短视频” / “이거로 쇼츠 만들어줘”
- 使用主题调用
search_trend_genealogy。带时间限制的查询传递moved_within_days参数(“本周”用 7,“最近”用 30)。 - 选择最强匹配(一句话说明您的选择和理由 —— 除非真正存在歧义,否则不要询问)。
- 恰好一次调用该匹配项的
get_trend_genealogy_card—— 这包含了借用手册:保留/改变/永不触碰、演变谱系、观众证据。 - 为所选片段调用
get_clone_kit_capsule—— 逐镜头的 콘티(分镜头脚本)。 - 编写包文件(见下文),然后如果用户有素材或希望生成渲染,则继续进入流程 F。
流程 B — “为我的产品做一个短视频”
- 调用
suggest_trends_for_product——product_description=参数无需任何注册即可使用;使用用户描述产品的原话。 - 然后执行流程 A 的第 2-5 步。如果用户拥有 Shorti 账号并注册了产品,
list_my_products+get_my_product_truth可以优化匹配。
流程 C — 用户粘贴了一个短视频 URL
粘贴的 URL 绝不是搜索。首先调用 preview_pasted_url,然后根据解析结果继续执行流程 A 的第 3-5 步。
流程 D — 拍摄中途指导
- 下一个镜头:调用
get_next_shot_cue—— 每次调用返回一个提示,拍摄,重复。 - “我做得怎么样?”:调用
get_shot_coaching_rubric,然后由您根据该评估标准对用户展示给您的片段进行评分。评估标准调用本身不包含文件或 URL 参数 —— 片段理解是您的工作,基于您已经看到的媒体。绝不将用户的素材发送到任何地方。如需对已完成文件进行结构性二次评估,请同时运行流程 G。
流程 E — “这周有什么新东西?”
调用一次 get_lifecycle_briefing;当用户询问 Shorti 能做什么时,get_started 是首次接触的引导说明。
包文件 — 您的第一个交付物
在工作目录中写入本地文件 shorti-packet-<slug>.md:
# <工作标题>
## 公式(借用自 <演变谱系引用>)
保留 / 改变 / 永不触碰 —— 直接复制自演变谱系卡片,并附上收据。
## 分镜头列表
来自克隆工具包的编号镜头:节拍、时长、景别、动作、音频提示。
## 逐镜头提示
您在拍摄现场会逐一给出的提示(流程 D 的顺序)。
## 评分标准
您将用于评估每日素材的评分标准。
## 证据
演变谱系引用和 observed_metrics —— 仅限事实,无预测。
用恰好一行机器可读的文本结束此步骤:
PACKET_FILE=<绝对路径>
流程 F — 包文件 → 时间线 → mp4(闭环)
包文件是计划;此步骤将其转化为文件。没有媒体素材请不要开始此流程。
-
定位媒体。 一次性询问用户片段目录,或使用已存在磁盘上的提供方输出。您编写的每个
src都必须能够解析到实际文件。 -
自行编写时间线。 将包文件的分镜头列表翻译成一个 JSON 文件 —— 由您编写,无需任何工具生成。字段及唯一允许的字段如下:
{ "version": "0.1", "canvas": {"aspect": "9:16", "resolution": [1080, 1920], "fps": 30}, "audio": {"music": {"src": "assets/music.mp3", "gain_db": -18}}, "beats": [ { "id": "hook", "role": "hook", "t": [0.0, 1.2], "shot": {"src": "clips/01.mp4", "in": 3.4, "framing": "close"}, "text": {"content": "wait for it", "pos": "center"}, "cue": "冷开场直接展示亮点,不要出现标志" } ], "subtitles": {"mode": "none"}, "provenance": {"packet": "shorti-packet-<slug>.md"} }beats[].t是绝对时间(秒),已排序,且不重叠。role是hook | development | payoff | cta | other之一。必填字段:version、canvas、beats,以及每个节拍的t+shot。其他所有字段均为可选 —— 不知道的就省略,不要发明。在provenance中包含包文件名。工作示例:examples/*.json。 -
viralprinter validate <timeline.json>—— 修复时间线中的每个错误。绝不要绕过验证错误;它在告诉您该计划无法渲染。 -
viralprinter compose <timeline.json> -o out.mp4—— 如果渲染时间较长或媒体不熟悉,请先使用--dry-run。 -
用自然语言报告您构建的内容,然后输出恰好一行机器可读的文本:
VIDEO_FILE=<绝对路径> -
提供评分,或者如果用户要求完成一个短视频,则直接运行评分:
viralprinter grade out.mp4 --markdown,然后按照流程 G 的报告规则处理。
流程 G — “给这个短视频评分”(无需 Shorti 账号)
适用于用户指向的任何文件,包括任何 AI 视频生成器的原始输出,也适用于尚未渲染任何帧的时间线 JSON。
viralprinter grade <file.mp4 | timeline.json> --markdown(当由机器消费时使用--json)。- 报告评分卡。没有总体分数 —— 评分卡本身就是结果。 不要计算平均值,不要发明分数,不要对视频进行排名。
- 读出
not_measured行及其原因。一个视频无法暴露自身的节拍角色,因此某些分类仅在时间线模式下可测量;这个差距是诚实的答案,而非失败。 - 说明各个波段是什么:粗略、精炼、
provenance: provisional。它们描述了在已分析片段中反复出现的结构。它们不承诺性能,并且out_of_band行是一个需要回答的问题,而非缺陷。 - 然后要发挥作用 —— 指出影响最大的一个结构变化,如果用户希望应用该变化,则进入流程 F。
失败处理协议
- OAuth 未完成 → 用一句话告诉用户完成浏览器流程,然后重试一次。
- 需要引用的工具在冷状态(缺少
trend_ref等)下被调用 → 您跳过了某一步骤;回退一个调用步骤,而不是盲目重试。 - 持续传输错误 → 逐字报告最后一个错误并停止。
viralprinter或ffmpeg未找到 → 报告缺失的二进制文件及安装命令。切勿模拟渲染。- Compose 失败 → 错误信息包含 ffmpeg 的 stderr 尾部。直接引用它,然后修复时间线。不要手动运行 ffmpeg 来绕过 composer。
- 验证错误 → 修复时间线并重新验证。绝不要将无效的时间线传递给
compose。