Communitygithub.com

viralprinter

結構優先的短影音工具。將主題、產品或貼上的短影音網址,轉換為以證據為基礎的拍攝方案;將宣告式時間軸透過 ffmpeg 編譯成 mp4;並根據病毒式結構規則評分任何短片——包括任何 AI 影片生成器的輸出。AI 代理人負責推理與編排;證據由外部提供,絕不虛構。

viralprinter 是什麼?

viralprinter 是一個結構優先的短影音創作與評分技能,適合用於 Claude Code、Coder 或任何 MCP 相容的 AI 代理人。它將主題、產品描述或短影音網址,轉換為以證據為基礎的拍攝方案 (packet),並能將方案中的 shotlist 編譯為 JSON 時間軸,再透過 ffmpeg 渲染成 mp4 影片。此外,它還能根據病毒式結構規則評分任何現有短片——包括 AI 影片生成器的輸出——且評分時不需要任何外部帳號。其核心設計原則是:AI 代理人負責推理與編排,而證據(例如來自 Shorti 的趨勢譜系、借用公式與受眾證明)由外部工具提供,且當證據不足時工具會誠實放棄,代理人絕不填補或虛構數據。viralprinter 支援完整的 CLI 工具鏈(validate、compose、grade),並可選用 Shorti 的 MCP 伺服器來獲取趨勢分析與評分基準。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ds4psb-ai/viralprinter/tree/main

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

viralprinter — 編排與評分短影音,附結構證據

你正在驅動兩個部分。

  • 本機、隨時可用。 本倉庫中的 viralprinter CLI: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 帳號;證據封包是唯一需要此帳號的部分。

操作規則

  1. 最多一個複合問題。 如果缺少輸入(主題 vs 產品 vs URL、目標比例、語言),請一次問完。絕不在工具呼叫之間要求確認。
  2. 語言地區。 在每個接受 locale 參數的呼叫中傳入與使用者語言相符的值(en、ko、ja),並完全以使用者的語言回答。
  3. 數字。 證據結果中的 observed_metrics 是來自語料庫的實際計數——請將其引用為證據。評分器的數字是對目前檔案的測量值——請將其引用為測量值。絕不產生預測性數字:不預測觀看次數、不提供「N×」倍數、不給出 ROI 百分比。只做結構上的陳述,不做成果的承諾。
  4. 誠實的缺席。 證據薄弱或放棄代表工具正常運作,評分類別回報 state: not_measured 並附上原因也是如此。請如實回報放棄情況;絕不猜測替代值或分數。
  5. 不要貼原始 JSON。 請重新組織。使用者閱讀的是散文、封包檔案和評分卡——而不是酬載。
  6. 重試紀律。 每次失敗呼叫最多重試一次。如果參數被拒絕,請重新閱讀工具描述,而不是再次猜測。
  7. 絕不虛構媒體。 時間軸只能引用存在於磁碟上的檔案。如果片段缺失,請說明是哪幾個並在封包階段就停止。

流程 A — 「幫我做一個關於 TOPIC 的短片」 / 「이거로 쇼츠 만들어줘」

  1. 使用主題呼叫 search_trend_genealogy。有時間限制的請求請傳入 moved_within_days(「本週」用 7,「最近」用 30)。
  2. 選出最相關的結果(用一句話說明你的選擇和原因——除非真的不明確,否則不要提問)。
  3. 對該結果僅呼叫一次 get_trend_genealogy_card——這是借用公式:keep / change / never_touch、譜系、受眾證明。
  4. 為選定的片段呼叫 get_clone_kit_capsule——逐鏡頭的 콘티。
  5. 編譯封包(見下方),然後如果使用者有素材或想要渲染,繼續進行流程 F。

流程 B — 「幫我的產品做一個短片」

  1. 呼叫 suggest_trends_for_product——product_description= 無需任何註冊即可使用;請使用使用者自己的話描述產品。
  2. 然後執行流程 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(閉合迴圈)

封包是一個計劃;這一步將其轉換為檔案。沒有媒體時不要開始此流程。

  1. 定位媒體。 一次詢問使用者片段目錄,或使用已經在磁碟上的提供者輸出。你寫入的每個 src 都必須能解析。

  2. 自行編寫時間軸。 將封包的鏡頭清單轉譯為一個 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。

  3. viralprinter validate <timeline.json>——修正時間軸中的所有錯誤。絕不安撫驗證錯誤;它是在告訴你計劃無法渲染。

  4. viralprinter compose <timeline.json> -o out.mp4——如果渲染時間很長或不熟悉媒體,請先使用 --dry-run。

  5. 用文字報告你建構了什麼,然後精確輸出一行機器可讀的文字:

    VIDEO_FILE=<絕對路徑>
    
  6. 提供評分選項,或者如果使用者要求一個完成的短片,直接執行:viralprinter grade out.mp4 --markdown,然後遵循流程 G 的回報規則。

流程 G — 「評分這個短片」(不需要 Shorti 帳號)

適用於使用者指定的任何檔案,包括任何 AI 影片產生器的原始輸出,也適用於還未渲染任何幀的 JSON 時間軸。

  1. viralprinter grade <file.mp4 | timeline.json> --markdown(機器使用時加 --json)。
  2. 回報評分卡。沒有總分——評分卡本身就是結果。 不要計算平均,不要創造分數,不要對影片排名。
  3. 大聲讀出 not_measured 行的原因。影片無法暴露其自身的節拍角色,因此有些類別只能在時間軸模式下測量;這個差距是誠實的回答,而非失敗。
  4. 說明頻帶的意義:coarse、distilled、provenance: provisional。它們描述的是在已分析片段中反覆出現的結構。它們不保證效能,而 out_of_band 行是需要回答的問題,不是缺陷。
  5. 然後要實用——指出影響最大的一項結構性改變,如果使用者希望套用,則進入流程 F。

失敗處理協定

  • OAuth 未完成 → 用一句話告知使用者完成瀏覽器流程,然後重試一次。
  • 需要參考的工具在冷啟動時被呼叫(缺少 trend_ref 等)→ 你跳過了一個步驟;在流程中回退一次,而不是盲目重試。
  • 持續的傳輸錯誤 → 逐字回報最後一個錯誤並停止。
  • 找不到 viralprinter 或 ffmpeg → 回報缺失的二進位檔以及安裝指令。絕不模擬渲染。
  • Compose 失敗 → 錯誤訊息會包含 ffmpeg stderr 的尾部。引用它,然後修正時間軸。不要手動執行 ffmpeg 來繞過 composer。
  • 驗證錯誤 → 修正時間軸並重新驗證。絕不將無效的時間軸傳遞給 compose。

相關技能