Communitygithub.com

alecs5am/ralphy

用於 HyperFrames 組合的資產前置處理——文字轉語音旁白 (Kokoro)、音訊/影片轉錄 (Whisper) 以及透明疊層的背景去除 (u2net)。

ralphy 是什麼?

此技能提供三個 CLI 指令,專為 HyperFrames 組合前置處理媒體資產:`tts` 使用本地的 Kokoro-82M 模型進行文字轉語音,無需 API 金鑰,支援多種語言和聲音;`transcribe` 使用 Whisper 模型生成具有逐字時間戳記的標準化 `transcript.json` 檔案,並附有嚴格的語言使用規則以避免意外翻譯;`remove-background` 使用 u2net_human_seg 模型從影片或影像中移除背景,以建立透明疊層,並支援同時輸出主體和背景層。所有指令首次執行時皆會下載各自的模型,並快取於 `~/.cache/hyperframes/` 目錄下。這些指令專為 HyperFrames HTML 組合設計,可無縫整合並輸出可直接在 `<video>` 元素中播放的 `.webm` 檔案,或供後期編輯用的 `.mov` 檔案。

相容平台~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/alecs5am/ralphy/tree/HEAD/.agents/skills/hyperframes-media

在你喜歡的 AI 中提問

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

預覽

來自技能 README

說明文件

HyperFrames 媒體前置處理

三個 CLI 指令,可為組合產生資產:tts(語音)、transcribe(時間戳記)和 remove-background(透明影片)。每個指令在首次執行時會下載模型,並快取在 ~/.cache/hyperframes/ 目錄下。將輸出放入專案中,然後從組合 HTML 中引用它——請參閱 hyperframes 技能以了解音訊/影片元素的慣例。

文字轉語音 (tts)

使用 Kokoro-82M 在本地生成語音音訊。無需 API 金鑰。

npx hyperframes tts "Text here" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma --output narration.wav
npx hyperframes tts --list                       # 所有 54 種聲音

聲音選擇

將聲音與內容匹配。預設為 af_heart。

內容類型聲音原因
產品示範af_heart/af_nova溫暖、專業
教學 / 指南am_adam/bf_emma中立、易於理解
行銷 / 促銷af_sky/am_michael充滿活力或權威
文件bf_emma/bm_george清晰的英式英語、正式
休閒 / 社交af_heart/af_sky平易近人、自然

多語言

聲音 ID 透過第一個字母編碼語言:a=美式英語,b=英式英語,e=西班牙語,f=法語,h=印地語,i=義大利語,j=日語,p=巴西葡萄牙語,z=中文。CLI 會自動從前綴偵測音素轉換器的區域設定——當聲音與文字相符時,無需 --lang。

npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
npx hyperframes tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav

僅在需要覆蓋自動偵測時(風格化口音)使用 --lang。有效代碼:en-us,en-gb,es,fr-fr,hi,it,pt-br,ja,zh。非英語音素轉換需要系統範圍安裝 espeak-ng(brew install espeak-ng / apt-get install espeak-ng)。

速度

  • 0.7-0.8 — 教學、複雜內容、無障礙
  • 1.0 — 自然速度(預設)
  • 1.1-1.2 — 簡介、過場、歡快的內容
  • 1.5+ — 很少合適;請仔細測試

長腳本

對於超過幾個段落的內容,請寫入一個 .txt 檔案並傳遞路徑。大約超過 5 分鐘語音的輸入可能受益於分割成多個片段。

需求

Python 3.8+ 搭配 kokoro-onnx 和 soundfile(pip install kokoro-onnx soundfile)。首次使用時下載模型(約 311 MB + 約 27 MB 聲音,快取在 ~/.cache/hyperframes/tts/ 目錄下)。

轉錄 (transcribe)

產生一個具有逐字時間戳記的標準化 transcript.json 檔案。

npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model small --language es
npx hyperframes transcribe subtitles.srt          # 匯入現有
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json

語言規則(不容協商)

除非使用者明確表示音訊是英語,否則絕不要使用 .en 模型。 .en 模型(small.en、medium.en)會將非英語音訊翻譯成英語,而不是進行轉錄。這會默默地破壞原始語言。

  1. 語言已知且非英語 → --model small --language <code>(無 .en 後綴)
  2. 語言已知且為英語 → --model small.en
  3. 語言未知 → --model small(無 .en,無 --language)— whisper 自動偵測

預設模型是 small,不是 small.en。

模型大小

模型大小速度使用時機
tiny75 MB最快快速預覽、測試流程
base142 MB快短片段、清晰的音訊
small466 MB中等預設 — 大多數內容
medium1.5 GB慢重要內容、有雜音的音訊、音樂
large-v33.1 GB最慢製作品質

包含人聲的音樂:從 medium 開始;製作的曲目通常需要手動匯入 SRT/VTT。關於字幕品質檢查(每次轉錄後必做)、清理 JS、重試規則以及 OpenAI/Groq API 匯入路徑,請參閱 hyperframes/references/transcript-guide.md。

輸出格式

組合使用一個單詞物件的扁平陣列。id 欄位(w0、w1、...)是在標準化過程中添加的,以便在字幕覆蓋中獲得穩定的參考;為了向後相容,它是可選的。

[
  { "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 },
  { "id": "w1", "text": "world.", "start": 0.6, "end": 1.2 }
]

背景去除 (remove-background)

從影片或影像中移除背景,使主體(通常是人物——虛擬角色、簡報者、說話的頭像)作為組合中的透明疊層。

npx hyperframes remove-background subject.mp4 -o transparent.webm  # 預設:VP9 alpha WebM
npx hyperframes remove-background subject.mp4 -o transparent.mov   # ProRes 4444(編輯用)
 npx hyperframes remove-background portrait.jpg -o cutout.png       # 單張影像裁切
npx hyperframes remove-background subject.mp4 -o subject.webm \
  --background-output plate.webm                                   # 一次處理兩個圖層
npx hyperframes remove-background subject.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info                           # 偵測到的提供者

使用 u2net_human_seg(MIT 授權)。首次執行下載約 168 MB 的權重到 ~/.cache/hyperframes/background-removal/models/ 目錄。

不要對具有白色外框的鏤空貼紙使用 u2net

remove-background (u2net) 是顯著物件分割——它分割主體身體並切掉白色鏤空外框,因為圖形周圍的白色筆畫不是「物件」。對於在平坦已知顏色背景上以白色外框渲染的透明 Telegram / 訊息貼紙,請對背景進行去背,而不是分割主體:

  • 對平坦背景進行洪水填充。 從所有四個邊緣的點(步長約 24px)開始用 PIL ImageDraw.floodfill 進行填充,將填充的像素標記為 alpha 0,其他所有內容不透明。這會保留白色外框、內部相同顏色的道具以及分離的孤立部分(與身體分離的飛杯會保留自己的外框)。需要生成提示將主體放在平坦均勻的背景上,並明確要求白色鏤空外框。
  • 無外框變體(比去除烘焙外框更乾淨): 對每張影像重新執行圖生圖——將完成的渲染作為 --ref 傳遞,並提示「重新建立相同的姿勢/道具,但移除白色外框,並將其放在平坦的純色去背綠 (#00b140) 上」,然後使用軟去背,絕不使用二進位遮罩對綠色進行去背(alpha = clip((HIGH-(G-max(R,B)))/(HIGH-LOW),0,1),LOW≈30 HIGH≈95,加上全域去溢色 G = min(G, max(R,B)))。二進位洪水填充 + 腐蝕會產生階梯狀 / 鋸齒狀邊緣——對二進位 alpha 進行模糊處理(GaussianBlur(0.8))以獲得平滑邊緣,而不是進行腐蝕。
  • 訊息貼紙的尺寸調整: 裁剪到實心 alpha 邊界框,並將長邊縮放到完全等於目標(例如 512)——不要填充到 512² 正方形(這會使主體變小,周圍有空曠空間)。

不適用於:用於影片疊層的人物裁切(u2net 在那裡是正確的);沒有鏤空外框的藝術作品;處於非均勻 / 繁忙背景上的主體(洪水填充需要平坦的去背顏色)。

圖層分離 (--background-output)

傳遞 --background-output(或 -b)以在裁切影片之外再輸出一個透明影片:相同的來源 RGB,alpha 是 255 − 遮罩 而不是 遮罩。裁切影片是主體,帶有透明背景;背景圖層是原始環境,在主體所在位置有一個透明空洞。

檔案Alpha 是…用途
-o subject.webm遮罩——主體不透明,背景透明前景圖層,放置在最上方
--background-output plate.webm反向——周圍環境不透明,主體區域透明底層圖層;將文字或圖形放在此圖層與主體之間

兩個輸出共享相同的 --quality 預設值,並從單次推理處理中運行——編碼成本大約翻倍,分割成本保持不變。僅對影片輸入和 .webm/.mov 輸出有效。

裁切洞的背景圖層,不是修復後的乾淨背景圖層。 plate.webm 中的主體區域是完全透明的——在其下方合成一個不透明物件以填充空洞。判斷 --background-output 是否是正確工具的單一測試:主體曾經所在的位置,是否會有任何東西透過主體的輪廓變得可見?

使用案例正確工具
文字/圖形位於裁切主體和背景圖層之間(此指令存在的原因)裁切洞 (--background-output)
將主體放到不相關的場景僅 subject.webm;忽略背景圖層
單獨顯示_沒有_人物的房間,上方沒有其他內容乾淨背景圖層——需要修復工具(LaMa、ProPainter、E2FGVI)。不是這個指令。
用不同的主體替換主體乾淨背景圖層——同上

如果使用者要求「移除人物後的房間」並打算單獨顯示它,不要使用 --background-output。告訴他們需要一個修復工具。

典型的圖層組合(典型的裁切洞使用案例):

<!-- z=1 反向 alpha 背景圖層填充除了主體區域之外的所有內容 -->
<video
  src="plate.webm"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>

<!-- z=2 圖形/文字存在於兩個圖層之間 -->
<h1 id="headline" style="z-index:2; ...">使用 HYPERFRAMES 製作</h1>

<!-- z=3 裁切主體將主體浮在標題之上 -->
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3">
  <video
    src="subject.webm"
    data-start="0"
    data-duration="6"
    data-track-index="1"
    muted
    playsinline
  ></video>
</div>

這在功能上等同於下面的文字在主體後方的模式,但專案中不需要原始的 presenter.mp4——背景圖層取代了它。當您只想提供兩個透明圖層並讓使用者在它們之間放置任意內容時很有用。

輸出格式

格式時機
.webm(VP9 + alpha)預設。組合直接透過 <video> 播放。
.mov(ProRes 4444)在 DaVinci/Premiere/FCP 中編輯。檔案較大。
.png單張影像裁切(靜止主體,疊加在背景上)。

Chrome 瀏覽器原生解碼 VP9 alpha,因此 .webm 可以像任何其他靜音自動播放影片一樣插入組合——請參閱 hyperframes 技能以了解 <video> 軌道慣例。

品質預設

--quality fast|balanced|best 僅控制 VP9 編碼器的 CRF——分割品質是固定的。

預設CRF時機
fast30迭代時,檔案較小,顏色匹配較寬鬆
balanced18預設。對大多數使用情況來說視覺上相同
best12主版本 / 最終交付。檔案最大,匹配最嚴格

合成模式——選擇正確的模式

裁切後的 webm 是來源 mp4 RGB 的重新編碼副本。這個選擇會根據您放在其後方的內容而產生不同的後果:

模式裁切後方是什麼結果
裁切主體放在不同場景上(最常見)靜態影像、漸層或無關的影片看起來很棒。裁切主體的 RGB 是主體的唯一來源——沒有重疊,沒有邊緣光暈。這就是 remove-background 的設計目的。
裁切主體放在其自己的來源 mp4 上(文字在主體後方)與產生裁切主體相同的 mp4同一個人有兩個 RGB 來源。在預設的 --quality balanced(crf 18)下,重疊幾乎不可見;在 --quality fast(crf 30)下,你會看到輕微的顏色偏移 / 邊緣光暈。

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

alecs5am/ralphy

>- Composition and render craft — assembles scenario.json plus asset-manifest.json into a HyperFrames HTML composition and renders the mp4. Owns timing, transitions, captions, audio mix and ducking, the green zone, the render pipeline, and VO sync. Generates no media of its own. USE WHEN the user asks to "compose the video", "render", "preview", "fix the captions", "mix the audio", "tighten the transitions", "final cut", or edits HyperFrames composition code. TRIGGER (EN): "render it", "compose the video", "captions", "audio mix", "transitions", "final cut", "preview the composition".

alecs5am/ralphy

HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.

alecs5am/ralphy

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

alecs5am/ralphy

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For dev-loop CLI commands (init, lint, inspect, preview, render) see the hyperframes-cli skill; for asset preprocessing commands (tts, transcribe, remove-background) see the hyperframes-media skill.

alecs5am/ralphy

>- How to make a vivid, character-driven brand POSTER — a single still image, not a video. A generalized overlay on the art-director step: supplies the poster-as-landing architecture (top banner → massive beveled wordmark → chest-up hero photo → scattered vinyl-sticker collage → copy block → thin footer strip), the parameterized slot set (brand, exclamation word, hero, product, palette, original blob glyph, aesthetic register), the model stack (gpt-5.4-image-2 for crisp typography, gemini fallback), and the niche's failure modes. Works for ANY brand and ANY aesthetic the user names — Y2K streetwear, vaporwave, grunge zine, clean DTC — the skill supplies the layout know-how, the user supplies the subject + vibe. USE WHEN the user asks for a poster / flyer / drop poster / "poster-as-landing-page" / brand key-art / album-cover-style still / hype graphic, with no specific existing poster to reproduce. This is a content-niche craft-overlay SKILL (generalized), loaded on top of a poster-format template match — n...

alecs5am/ralphy

>- Compatibility shim for the legacy `/ralphy-remotion` skill name. Use when a saved Claude Code command, old project note, or user request still mentions Ralphy Remotion; redirect the task to HyperFrames and the current Ralphy render playbooks instead of authoring new Remotion code.

alecs5am/ralphy

>- Compatibility shim for the legacy `/remotion-to-hyperframes` skill name. Use when an old project, note, or user request asks to migrate Ralphy Remotion work; translate the intent into the current HyperFrames composition model and follow the editor and HyperFrames playbooks.

alecs5am/ralphy

The full extract → classify → blueprint → de-dup → publish pipeline for a finished `.ralphy/workspaces/<ws>/projects/<id>/`. Reads its `units/*/unit.json` (#069) as the Unit source of truth, then factors the project into ALL FIVE entities — Unit + the four typed blocks Template (structure), Style (look), Recipe (effect/treatment), Asset (reusable media). Applies the recipe-vs-tag split (#082/#083): a candidate is a Recipe only if it carries an extractable artifact (ffmpeg filtergraph / HyperFram

alecs5am/ralphy

>- How to make a realistic AI UGC ad for a product — generalized niche know-how that looks real and doesn't feel AI. A domain overlay on the standard pipeline: supplies the shooting-script shape (timestamp | VO | shot | mannerism), the creator-persona build, the problem-mirror hook, the trust-through-mannerisms rule, and the 9:16 ~15s UGC format defaults. Works for ANY product the user names — their skincare line, a no-name app, a gadget. The skill supplies the know-how; the user supplies the product. USE WHEN the user asks for a UGC ad / creator-style product ad / "make an ad that looks like a real person reviewing my product" / testimonial-style or problem-solution short for TikTok / Reels / Shorts, with no specific existing video to reproduce. This is a niche SKILL (generalized), not a remix TEMPLATE. For "remix this exact ad but swap the product/person", use the remix path (docs/skills-vs-templates.md). For swapping the creator in an existing clip, see /ugc-model-swap.

alecs5am/ralphy

When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing strategies,' 'marketing tactics,' 'ways to promote,' 'ideas to grow,' 'what else can I try,' 'I don't know how to market this,' 'brainstorm marketing,' or 'what marketing should I do.' Use this as a starting point whenever someone is stuck or looking for inspiration on how to grow. For specific channel execution, see the relevant skill (paid-ads, social-content, email-sequence, etc.).

alecs5am/ralphy

Full end-to-end workflow for generating a realistic AI UGC ad for a product. 15-second format. Looks real. Doesn't feel AI.

相關技能