viralprinter — 編排與評分短影音,附結構證據
你正在驅動兩個部分。
- 本機、隨時可用。 本倉庫中的
viralprinterCLI:validate、compose(時間軸 JSON → 透過 ffmpeg 轉 mp4)以及grade(根據病毒式結構規則評分任何短片)。無需帳號、無需金鑰、無需上傳。 - 證據,可選。 Shorti 的唯讀 MCP 入口:已分析的實際短影音片段、它們的譜系(哪些元素被保留、哪些被改動、哪些被淘汰),以及每個片段的借用公式(keep / change / never_touch)與受眾證明。
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 與影片模式評分會呼叫它們。請先以 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 — 「幫我做一個關於 TOPIC 的短片」 / 「이거로 쇼츠 만들어줘」
- 使用主題呼叫
search_trend_genealogy。有時間限制的請求請傳入moved_within_days(「本週」用 7,「最近」用 30)。 - 選出最相關的結果(用一句話說明你的選擇和原因——除非真的不明確,否則不要提問)。
- 對該結果僅呼叫一次
get_trend_genealogy_card——這是借用公式:keep / change / never_touch、譜系、受眾證明。 - 為選定的片段呼叫
get_clone_kit_capsule——逐鏡頭的 콘티。 - 編譯封包(見下方),然後如果使用者有素材或想要渲染,繼續進行流程 F。
流程 B — 「幫我的產品做一個短片」
- 呼叫
suggest_trends_for_product——product_description=無需任何註冊即可使用;請使用使用者自己的話描述產品。 - 然後執行流程 A 的步驟 2-5。如果使用者擁有註冊了產品的 Shorti 帳號,
list_my_products+get_my_product_truth可以提升配對的精準度。
流程 C — 使用者貼上了一個短影音網址
貼上的網址絕不是搜尋。請先呼叫 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:
# <工作標題>
## 公式(借鑒自 <譜系參考>)
keep / change / never_touch — 來自譜系卡的原文,附帶證明。
## 鏡頭清單
來自複製套件的編號鏡頭:節拍、時長、構圖、動作、音訊提示。
## 逐鏡頭提示
你在片場會一次一個給出的提示(流程 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": "cold open on the reveal, no logo" } ], "subtitles": {"mode": "none"}, "provenance": {"packet": "shorti-packet-<slug>.md"} }beats[].t是絕對秒數,已排序,不重疊。role是hook | development | payoff | cta | other其中之一。必要欄位:version、canvas、beats,以及每個 beat 的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行的原因。影片無法暴露其自身的節拍角色,因此有些類別只能在時間軸模式下測量;這個差距是誠實的回答,而非失敗。 - 說明頻帶的意義:coarse、distilled、
provenance: provisional。它們描述的是在已分析片段中反覆出現的結構。它們不保證效能,而out_of_band行是需要回答的問題,不是缺陷。 - 然後要實用——指出影響最大的一項結構性改變,如果使用者希望套用,則進入流程 F。
失敗處理協定
- OAuth 未完成 → 用一句話告知使用者完成瀏覽器流程,然後重試一次。
- 需要參考的工具在冷啟動時被呼叫(缺少
trend_ref等)→ 你跳過了一個步驟;在流程中回退一次,而不是盲目重試。 - 持續的傳輸錯誤 → 逐字回報最後一個錯誤並停止。
- 找不到
viralprinter或ffmpeg→ 回報缺失的二進位檔以及安裝指令。絕不模擬渲染。 - Compose 失敗 → 錯誤訊息會包含 ffmpeg stderr 的尾部。引用它,然後修正時間軸。不要手動執行 ffmpeg 來繞過 composer。
- 驗證錯誤 → 修正時間軸並重新驗證。絕不將無效的時間軸傳遞給
compose。