srt-hyperframes-editorial-video

HyperFrames Editorial Video

把 SRT 字幕文件制作成 HyperFrames + GSAP 的 Editorial 风格视频。只支持 SRT 输入。

调用本 skill 时，用户必须提供 SRT 字幕文件路径。没有 srtPath 时，主 Agent 必须先暂停并 要求用户提供 .srt 文件路径。

制作前必须先选择主题：

• 暗色风格（dark-editorial）
• 牛皮纸风格（kraft-editorial）
• 克莱因蓝风格（klein-blue）
• 鼠尾草绿风格（sage-green）

SubAgent 使用授权与硬性要求

当用户要求“使用 HyperFrames，根据 SRT 字幕生成视频”或以其他方式触发本 skill 时，视为用户 已经显式要求按本 skill 工作流使用 SubAgent。主 Agent 不得因为通用工具说明中“仅在用户明确 要求 sub-agent 时使用”的限制而跳过本 skill 规定的 SubAgent 阶段。

第 3 步和第 4 步是强制 SubAgent 阶段。若当前运行环境没有可用 SubAgent 工具，主 Agent 必须 立即暂停并向用户说明阻塞原因，不得降级为主 Agent 自行完成这些阶段。

核心原则

• SRT 时间是唯一时间事实源。
• AI 只负责语义分组、视觉转译和局部场景设计。
• 脚本负责 SRT 解析、连续性校验、相对时间计算、creator 分片、scene-plan 校验和最终 composition 组装。
• creator 不直接修改最终 index.html，只写独立 scene 片段。

Path Contract

主 Agent 和所有 SubAgent 统一使用绝对路径：

• skillRoot: 当前 srt-hyperframes-editorial-video 目录绝对路径
• referencesRoot: {skillRoot}/references
• scriptsRoot: {skillRoot}/scripts
• themesRoot: {skillRoot}/themes
• srtPath: 用户提供的 SRT 文件绝对路径
• projectBaseDir: {dirname(srtPath)}/hyperframes-editorial-video-projects
• projectRoot: {projectBaseDir}/{yyyy-mm-dd-hh-mm-ss}

强制要求：

• SubAgent prompt 中必须写入展开后的绝对路径，不要只传变量名。
• 阶段协议文档只能从 referencesRoot 读取。
• 脚本只能从 scriptsRoot 执行。
• 所有运行态状态必须由主 Agent 显式传递。

工作流

0. 环境预检

进入正式制作前，主 Agent 必须先完成环境预检。预检失败时立即暂停并报告缺失项。

预检命令：

node --version
npm --version
npx hyperframes --version
ffmpeg -version

判定规则：

• node --version 必须是 v22.0.0 或更高。
• npm --version 必须成功输出版本号。
• npx hyperframes --version 必须成功输出版本号；若首次执行需要联网下载 CLI，应在正式制作前完成。
• ffmpeg -version 必须成功输出版本信息。
• 如果任一预检失败，必须明确告诉用户是哪一项环境不符合要求，并附上失败命令、实际输出或缺失原因。

1. 确定主题和 SRT 路径

SRT 字幕文件路径是必须输入条件。用户未提供 SRT 路径时，先暂停并要求用户提供。

用户必须明确选择一个主题。向用户展示主题时优先使用 theme.json 中的 nameZh，并同时标明 对应 themeId：

• 暗色风格（dark-editorial）
• 牛皮纸风格（kraft-editorial）
• 克莱因蓝风格（klein-blue）
• 鼠尾草绿风格（sage-green）

如果用户未指定主题，先暂停并要求用户从上述中文风格名中选择；不要默认代选。实际执行脚本时 使用括号内的 themeId。

如果用户给的是相对 SRT 路径，主 Agent 必须先解析为绝对路径并确认文件存在。后续所有 步骤统一使用最终确认过的 srtPath。

2. 初始化项目

执行：

node "{scriptsRoot}/init-project.mjs" --srt-path "{srtPath}" --theme "{themeId}"

脚本会创建 {dirname(srtPath)}/hyperframes-editorial-video-projects/{timestamp}/，复制模板样式、 复制主题 token，写入 .theme，并创建 src/scenes/ 与 scene-plans/。

3. 生成 groups.json 和 storyboard.json

本阶段必须使用 storyboard SubAgent 执行；用户触发本 skill 即视为已显式授权本阶段使用 SubAgent。主 Agent 禁止自行生成 groups.json 或直接生成 storyboard.json 来替代 storyboard SubAgent。主 Agent 只负责计算并展开：

• storyboardReference = {referencesRoot}/storyboard-parser.md
• storyboardScript = {scriptsRoot}/generate-storyboard.mjs

SubAgent 先读取 storyboard-parser.md，再读取 SRT，按语义和时间生成 {projectRoot}/groups.json。随后运行：

node "{storyboardScript}" "{srtPath}" "{projectRoot}/groups.json" "{projectRoot}/storyboard.json"

脚本负责解析 SRT、校验 groups 连续性，并生成 storyboard.json。

4. 按 creator 分片并并行实现 scene

主 Agent 读取 {projectRoot}/storyboard.json 后，必须每 10 个 storyboard scene 分配一个 creator。creator 分片是并行 SubAgent 工作单元，不是主 Agent 的本地实现任务。 creator 命名规则固定：

const creatorId = `creator-${String(index + 1).padStart(2, "0")}`;

对每个 creator 执行：

node "{scriptsRoot}/generate-creator-scenes.mjs" \
  "{projectRoot}/storyboard.json" \
  "{creatorId}" \
  "10" \
  "{projectRoot}/scene-plans/{creatorId}.scenes.json"

必须为每个 creator 分片启动独立 creator SubAgent；如果 creator 数量大于 1，必须在同一轮尽量 并行启动全部 creator SubAgent，不要串行启动。每个 creator 只接收自己的 .scenes.json 事实源和 references/scene-creator.md 协议。全局 skill 和 creator 阶段参考文档由 scene-creator.md 按职责和选择结果要求读取，不在主流程重复列出。

主 Agent 禁止直接编写任何 SceneXXX.html、SceneXXX.css 或 SceneXXX.js 文件来代替 creator SubAgent。主 Agent 的职责是分片、启动 creator SubAgent、等待全部 creator 完成、审查 结果、组装 composition 和运行最终校验。

1. 生成 {projectRoot}/scene-plans/{creatorId}.json
2. 运行 validate-scene-plan.mjs
3. 编写 {projectRoot}/src/scenes/SceneXXX.html
4. 编写 {projectRoot}/src/scenes/SceneXXX.css
5. 编写 {projectRoot}/src/scenes/SceneXXX.js
6. 运行 validate-scene-js.mjs

creator 不得修改最终 index.html。

给 creator SubAgent 的 prompt 必须保持低噪声。creatorId 只用于主 Agent 分片和命名文件， 不要传给 SubAgent，也不要把 scene JSON 内联到 prompt。主 Agent 先展开：

scenesDataPath = "{projectRoot}/scene-plans/{creatorId}.scenes.json"
planPath = "{projectRoot}/scene-plans/{creatorId}.json"
tokensPath = "{projectRoot}/styles/tokens.css"
validateScript = "{scriptsRoot}/validate-scene-plan.mjs"
validateJsScript = "{scriptsRoot}/validate-scene-js.mjs"

然后使用推荐模板：

你是 HyperFrames Editorial scene creator，负责 scenesDataPath 中列出的所有 scenes。

## 路径

- projectRoot: "{projectRoot}"
- scenesDataPath: "{scenesDataPath}"
- planPath: "{planPath}"
- referencesRoot: "{referencesRoot}"
- tokensPath: "{tokensPath}"
- validateScript: "{validateScript}"
- validateJsScript: "{validateJsScript}"

## 任务

读取 "{referencesRoot}/scene-creator.md"，按其中协议完成 scene-plan、校验和
SceneXXX.html/css/js 片段实现。全局 skill 和二级参考文档的读取顺序以 scene-creator.md 为准。

scene-plan 校验命令：
node "{validateScript}" "{planPath}" "{scenesDataPath}"

写完 SceneXXX.html/css/js 后的 JS timing 校验命令：
node "{validateJsScript}" "{projectRoot}" "{scenesDataPath}"

不要修改最终 index.html。完成后按 scene-creator.md 的返回格式报告结果。

5. HyperFrames composition を組み立てる

すべての creator が完了したら、次を実行します。

node "{scriptsRoot}/generate-composition.mjs" \
  "{projectRoot}" \
  "{projectRoot}/storyboard.json"

スクリプトは最終的な {projectRoot}/index.html を生成し、1つの paused GSAP timeline を作成して、scene をハードカットで切り替え、各 scene のスニペットに登録された builder を呼び出します。

最終 HTML は、HyperFrames の次の2つの情報源に対応する必要があります。

• GSAP メイン timeline：各 scene は tl.addLabel(scene.id, scene.startTime / 1000) で label を登録し、SRT の時間に従ってハードカットで表示する必要があります。
• Studio／デバッグ時間軸：各 <section id="scene_xxx" class="ed-scene"> に、generate-composition.mjs が class="clip"、data-start、data-duration、data-track-index="0" を自動で補完する必要があります。data-start は storyScene.startTime / 1000 に由来します。最後以外の scene の data-duration には、「次の scene までの間隔から 0.001 秒を引いた値」を使用し、浮動小数点の境界によって npx hyperframes lint が overlapping_clips_same_track と判定するのを避けます。

creator のスニペットで、これらの clip メタデータを記述する必要はありません。また、記述してはいけません。これらは最終組み立てスクリプトの役割です。

6. 納品前の検証

最低限、次を実行します。

node "{scriptsRoot}/validate-ed.mjs" "{projectRoot}/index.html" "{projectRoot}/storyboard.json"
npx hyperframes lint "{projectRoot}"
storyboardDerivedTimes=$(node "{scriptsRoot}/generate-inspect-times.mjs" "{projectRoot}/storyboard.json")
npx hyperframes inspect "{projectRoot}" --at "$storyboardDerivedTimes" --json

generate-inspect-times.mjs は {projectRoot}/storyboard.json から storyboardDerivedTimes を計算します。形式はカンマ区切りの秒数です。各時刻は、各 scene の重要な画面をカバーします。

• scene 開始から約 0.2s 後。
• skeleton の構築後の安定した時点。通常は scene 開始から約 1.0s 後ですが、短い scene では適宜早めます。
• 各 segment の scene.startTime + segment.relativeStart 付近。
• scene 終了の約 0.2s 前。

inspect では --strict を使用しません。errors は修正する必要があります。warnings を修正する必要があるかどうかは、メイン Agent が意味を踏まえて判断します。

npx hyperframes lint は errorCount: 0 になる必要があります。特に、次のエラーが発生してはいけません。

• timed_element_missing_clip_class
• overlapping_clips_same_track

scene の数、data-start、data-duration、class="clip" のいずれかを再生成し、ユーザーが Studio／デバッグモードを使用している場合、メイン Agent は {projectRoot}/.thumbnails をバックアップするか削除して、デバッグ時間軸が最新の scene clip インデックスを再読み込みできるようにする必要があります。.thumbnails.bak-<timestamp> など、まずは元に戻せるバックアップディレクトリを使用してください。

例外：ghost テキストは意図的に画面からはみ出してもかまいません。inspect で報告された text_box_overflow が、.ed-ghost-type、.sh-ghost、.es-ghost、または意味的に同等の ghost heading／text など、ghost クラスの装飾的な大きなテキストでのみ発生し、主要コンテンツ、字幕、図表、ラベル、重要なビジュアルが隠れたり切り取られたりしていない場合は、デザイン上許容される overflow とみなします。このエラーをなくすために ghost の位置、フォントサイズ、bottom、overflow、切り抜き方法を調整しないでください。メイン Agent は検証の要約で、これらの text_box_overflow は ghost のデザイン上のはみ出しであると記載して、そのままレンダリングを続行してください。

7. 最終動画をレンダリングする

納品前の検証に合格したら、次を実行します。

npx hyperframes render "{projectRoot}" --quality high --output "{projectRoot}/output.mp4" > "{projectRoot}/render.log" 2>&1
node "{scriptsRoot}/validate-render-log.mjs" "{projectRoot}/render.log"

最終動画の出力先は常に {projectRoot}/output.mp4 です。ファイルがすでに存在する場合、メイン Agent は現在のレンダリングで旧ファイルを上書きすべきか、事前に確認する必要があります。最終動画を既定の renders/ タイムスタンプ付きディレクトリに出力しないでください。

レンダリングの完了後、必ず {projectRoot}/render.log を確認してください。ログに timeline が登録されていない、JS exception、q(...) が DOM 要素として使用されている、または GSAP target not found が記録されている場合、メイン Agent は該当する src/scenes/SceneXXX.js に戻って修正し、その後 generate-composition.mjs、納品前の検証、render を再実行する必要があります。最終的な index.html だけを修正しないでください。

データ構造

storyboard.json

interface Storyboard {
  totalDuration: number;
  sceneCount: number;
  scenes: {
    id: string;
    startTime: number;
    duration: number;
    displayDuration?: number;
    segments: {
      text: string;
      relativeStart: number;
      relativeDuration: number;
    }[];
  }[];
}

リソースガイド

• assets/template/：HyperFrames composition のスタイルテンプレート。
• themes/：組み込みテーマ。各テーマには theme.json と tokens.css が含まれます。
• references/storyboard-parser.md：SRT から groups／storyboard を生成するためのプロトコル。
• references/scene-creator.md：creator の計画とスニペット実装のプロトコル。
• references/TIMING-CANON.md：SRT の相対時間と focus cue のルール。
• references/VISUAL-SYSTEM.md：token、primitive class、テーマのルール。
• references/BEAT-ARCHETYPES.md：layout インデックス、グラフィカルな選択ルール、layout 共通の仕様。
• references/layout-patterns/：layout_id に応じて段階的に読み込む、各 layout の詳細な制約。
• references/MOTION-CANON.md：GSAP と HyperFrames 共通のアニメーションルール。
• scripts/init-project.mjs：SRT とテーマからプロジェクトを作成します。
• scripts/generate-storyboard.mjs：SRT と groups から storyboard を生成します。
• scripts/generate-creator-scenes.mjs：creator 用に scenesData をローカル scenes に分割します。
• scripts/validate-scene-plan.mjs：creator の scene-plan を検証します。
• scripts/validate-scene-js.mjs：creator の段階で SceneXXX.js の timing を検証します。
• scripts/generate-composition.mjs：最終的な index.html を組み立てます。
• scripts/generate-inspect-times.mjs：storyboard.json から inspect --at の時刻を生成します。
• scripts/validate-ed.mjs：静的チェックを追加で実行します。
• scripts/validate-render-log.mjs：最終 render ログに黒画面につながる実行時エラーがないか確認します。

ユーザー向けショートカット指示

4K 60 フレーム版を生成する

ユーザーが「動画を 4K 60 フレーム版にする」「4K60 を生成する」「4k 60fps で書き出す」など、意味が同等の指示をした場合、 メインエージェントは SRT のグループ化、scene creator、composition の生成プロセスを再度実行せずに、この手順を自動的に実行します。

まず projectRoot を特定します。

• ユーザーが HyperFrames プロジェクトディレクトリを指定した場合は、そのディレクトリをそのまま使用します。
• ユーザーが {projectRoot}/output.mp4、output.mp4、またはプロジェクトルートにある別の動画ファイルを指定し、 同じディレクトリに index.html がある場合は、その動画ファイルがあるディレクトリを projectRoot として使用します。
• 単独の動画ファイルしかなく、同じディレクトリから HyperFrames プロジェクトディレクトリを推定できない場合は、まず対応する HyperFrames プロジェクトディレクトリをユーザーに提示してもらいます。npx hyperframes render は composition から再レンダリングするものであり、通常の動画トランスコードではありません。

実行前に {projectRoot}/output-4k.mp4 がすでに存在する場合は、必ず上書きしてよいかユーザーに確認します。明確な同意がない場合は上書きしないでください。

実行します。

npx hyperframes render "{projectRoot}" \
  --resolution landscape-4k \
  --fps 60 \
  --quality high \
  --output "{projectRoot}/output-4k.mp4" \
  > "{projectRoot}/render-4k.log" 2>&1
node "{scriptsRoot}/validate-render-log.mjs" "{projectRoot}/render-4k.log"

説明：

• landscape-4k は 3840x2160 で出力します。このスキルのデフォルトである 1920x1080 の横長 composition に適しています。
• --fps 60 は 60fps で出力し、--quality high は最終納品用に使用します。
• 出力ファイル名は {projectRoot}/output-4k.mp4 に固定します。
• レンダリング完了後、必ず render-4k.log を確認します。ログに timeline が登録されていない、JS exception、 q(...) が DOM 要素として使用されている、または GSAP target not found が含まれている場合は、該当する src/scenes/SceneXXX.js を修正してから generate-composition.mjs を再実行し、4K 60 フレーム版を再レンダリングします。

デバッグモードを開始する

ユーザーが「デバッグモードを開始する」「デバッグモードに入る」「デバッグプレビュー」など、意味が同等の指示をした場合、メインエージェントはこの手順を自動的に実行します。 デバッグモードでは HyperFrames Studio preview を使用します。

まず projectRoot を特定します。現在の会話でプロジェクトディレクトリが明確でない場合は、まず HyperFrames プロジェクトディレクトリをユーザーに提示してもらいます。このディレクトリには index.html が含まれている必要があります。

続いて、デバッグ用音声ファイルのパスをユーザーに提示してもらいます。音声を受け取ったら：

1. 音声ファイルが存在することを確認します。
2. 音声が {projectRoot} 内にない場合は、{projectRoot}/assets/debug-audio{ext} にコピーします。assets/ が存在しない場合は、先に作成します。
3. {projectRoot}/index.html で固定のデバッグ音声スロットを探し、スロット内の内容のみを置き換えます。通常生成される index.html にはすでにこのスロットが用意されています。音声がない場合、スロットは空であり、preview や render に影響しません。

音声を挿入すると、次のようになります。

<audio
  id="ed-debug-audio"
  data-start="0"
  data-track-index="99"
  src="assets/debug-audio.mp3"
  data-volume="1"
></audio>

ルール：

• ED_DEBUG_AUDIO_SLOT_START と ED_DEBUG_AUDIO_SLOT_END の間にのみデバッグ音声を書き込むか、削除します。 <div id="main"> を検索したり、scene の位置をもとに挿入位置を独自に判断したりしないでください。
• スロット内に古いデバッグ用 <audio> がすでにある場合は、スロット内の内容を直接置き換えます。複数の <audio> を重複して挿入しないでください。
• 音声はデバッグ補助としてのみ使用します。src/scenes/SceneXXX.* に書き込んだり、storyboard.json を変更したり、再グループ化したりしないでください。
• generate-composition.mjs を再実行して index.html が上書きされた場合、空のスロットが保持されます。preview の前に、デバッグ音声を再度そのスロットに書き込む必要があります。
• audio.play() を呼び出さないでください。メディア再生と timeline sync は HyperFrames が処理します。

preview を起動します。

npx hyperframes preview "{projectRoot}" --port "{port}"

未使用のポートを選択し、まず 3002 を使用します。使用中の場合は番号を増やします。デバッグモードを停止するため、preview プロセスの PID / session を記録します。起動に成功したら、Studio URL をユーザーに伝えます。

http://localhost:{port}/#project/{project-directory-name}

preview でブラウザーが自動的に開かない場合は、システムの起動コマンドを使用して上記の Studio URL を開きます。

デバッグモード中に、ユーザーが「第 N シーンに何か問題がある」「scene_00N に問題がある」「特定の画面要素が隠れる、 ずれている、表示されない、テンポがおかしい」などの具体的なフィードバックをした場合：

1. ユーザーの説明に基づいて storyboard scene を特定します。scene_00N が指定されている場合はそれを優先して照合します。「第 N シーン」と言われた場合は、 SceneNNN.html/css/js と scene_00N に対応付けます。
2. 対応する src/scenes/SceneNNN.html、SceneNNN.css、SceneNNN.js、関連する scene-plan、および storyboard.json の該当部分を読み取ります。
3. 対応する scene のソースファイルのみを変更します。最終的な index.html に連結された部分を直接修正しないでください。
4. composition を再構成して、preview をホットリロードします。

node "{scriptsRoot}/generate-composition.mjs" "{projectRoot}" "{projectRoot}/storyboard.json"

5. generate-composition.mjs を実行するとスロットが空に戻るため、デバッグ音声を固定スロットに再度書き込みます。
6. preview を実行したままにし、ユーザーが Studio で引き続き確認できるようにします。デバッグモード中は検証スクリプトを自動実行しないでください。ユーザーから明示的に確認、検収、またはレンダリング前の確認を求められた場合に限り、 validate-scene-js.mjs、validate-ed.mjs、または npx hyperframes inspect を実行します。

デバッグモードを停止する

ユーザーが「デバッグモードを停止する」「デバッグモードを終了する」「デバッグを終了する」など、意味が同等の指示をした場合：

1. {projectRoot}/index.html の ED_DEBUG_AUDIO_SLOT_START から ED_DEBUG_AUDIO_SLOT_END の間にある一時音声を消去します。 スロットのコメント自体は残します。
2. 以前に記録した npx hyperframes preview のプロセス / session を停止します。
3. ユーザーの元の音声ファイルは削除しません。{projectRoot}/assets/debug-audio{ext} はデバッグ用コピーなので、残してかまいません。ユーザーから明示的に削除を求められた場合にのみ削除します。
4. デバッグモードを停止したことと、デバッグ音声を timeline から削除したことを報告します。