AutoCliper.AI — エージェントスキル
1本の長いYouTube動画を、中国語でパッケージングされ、ハードサブタイトル(焼き込み字幕)が付いた5〜15本のショートクリップに変換します。
このドキュメントは、AutoCliperパイプラインを実行するあらゆるAIエージェントの唯一の情報源です。番号付きの各ステップを順番に従ってください。ステップをスキップしないでください。ファイル名を推測しないでください — 書き込み操作のたびにファイルシステムを確認してください。
0. 事前チェック
他のことをする前に、環境を確認してください。いずれかのチェックに失敗した場合は、正確なブロッカーを報告して停止してください。
| チェック項目 | コマンド | 合格条件 |
|---|---|---|
| yt-dlp がインストールされている | which yt-dlp | パスが返される |
| ffmpeg がインストールされている | which ffmpeg | パスが返される。ない場合は python3 -c "import imageio_ffmpeg; print(imageio_ffmpeg.get_ffmpeg_exe())" を試す |
| Python 3.9+ | python3 --version | >= 3.9 |
| スキルリポジトリが利用可能 | スキルルートからの相対パスで corekit/ ディレクトリが存在することを確認 | corekit/__init__.py が存在する |
以降のすべてのコマンドのために環境を設定します:
export PYTHONPATH="<AutoCliper.AI-リポジトリへのパス>"
以下の python3 -m corekit.* コマンドはすべて、この PYTHONPATH が設定されていることを前提としています。
1. ワークスペースの作成
この動画のための出力ディレクトリ構造を作成します。<slug> は動画のタイトルまたはIDから導出します — 小文字、ハイフン、スペースなし、特殊文字なし。
mkdir -p "studio/<slug>/intake"
mkdir -p "studio/<slug>/intel"
mkdir -p "studio/<slug>/exports"
期待される結果:
studio/<slug>/
├── intake/ ← 生の動画と字幕がここに配置される
├── intel/ ← 分析成果物がここに配置される
└── exports/ ← クリップごとのフォルダがここに配置される
2. ソースアセットの取得
YouTubeから動画と字幕をダウンロードします:
python3 -m corekit.fetch_source "<YouTube_URL>" "studio/<slug>/intake"
内部で行われること: ダウンローダーは最初に英語字幕(en, en-US, en-orig)を試し、中国語(zh-Hans, zh-CN, zh)にフォールバックします。認証されたアクセスのために --cookies-from-browser chrome を使用します。
コマンドが終了したら、intakeフォルダをリストし、以下を特定します:
.mp4動画ファイル(ファイル名に動画のタイトルとIDが含まれている場合があります).srt字幕ファイル(.en.srtや.zh-Hans.srtなどの言語タグが付いている場合があります)- サイドカーファイル(
.ytdl,.jpgなど) — それらに注意しますが必要ありません
ダウンロードが失敗した場合:
- Cookieエラー → ユーザーにChromeのYouTubeログインを更新してから再試行するよう伝える
- 字幕が見つからない → 「この動画では字幕が利用できません」と報告して停止する
- 動画ダウンロードエラー → 異なるフォーマットで一度再試行する。それでも失敗する場合はエラーを報告する
次のステップのために正確なファイル名を記録します。名前を推測したりハードコードしたりしないでください。
3. 字幕をJSONに解析
SRT字幕ファイルを構造化されたJSONに変換して分析を容易にします:
python3 -m corekit.subtitle_to_json \
"studio/<slug>/intake/<正確なSRTファイル名>" \
"studio/<slug>/intel/transcript.json"
出力ファイルが存在し、cueオブジェクトの配列を含んでいることを確認します。各cueは以下の構造を持ちます:
{
"index": 1,
"start": "00:00:01,234",
"end": "00:00:03,456",
"start_seconds": 1.234,
"end_seconds": 3.456,
"text": "発話された内容"
}
トランスクリプトが空であるか、10個未満のcueしかない場合は、「トランスクリプトが短すぎるか破損しています」と報告して停止してください。
4. トランスクリプトを分析し、候補を提案する
これは最も重要な知的ステップです。分析を開始する前に、以下のファイルを読んでください:
- playbooks/clip-contract.md —
selected_clips.jsonの正確なJSONスキーマを定義 - playbooks/content-analysis-playbook.md — マルチパス分析手法、スコアリングルーブリック、レビューフォーマットを定義
4a. マルチパス分析
1回のパスでクリップを選択しようとしないでください。以下の順序に従ってください:
パス1 — 概観とフラグ付け: transcript.json を読み、印象的で情報密度が高く、意見が明確で、直感に反する、または感情的鋭さを含む箇所を探します。寛大にフラグを立ててください — 多すぎても少なすぎても問題ありません。
パス2 — 境界の微調整: フラグを立てた各箇所について、前後のcue(5〜10個)を再読します。適切な開始点と終了点を選んでください:
- 開始点は、クリップの最初の3秒以内に視聴者を引き込む行でなければなりません
- 終了点は、話者が考えを言い終わった後でなければなりません — 文の途中で切らないでください
- 有望な瞬間に数秒のコンテキストが必要な場合は、開始点を早めに延長します
- 考えが尻切れとんぼになっている場合は、それが解決するまで終了点を延長します
パス3 — 完全性チェック: 各候補について、以下を確認します:
- 長さが20〜180秒である(見合う見返りがあれば3分まで延長可)
- 1つの明確なアイデアのみを含む
- 冒頭の行がフックであり、無駄な言葉ではない
- 最後の行で考えが完結している
- 動画の残りを見なくても理解できる
- 挨拶、スポンサー読み上げ、Q&A前振り、長い脱線ではない
パス4 — スコアリングとランク付け: 各候補を4つの次元でスコアリングします(1〜5):
hook— 最初の3秒での冒頭の魅力度clarity— 1つの明確なアイデアで、あいまいさが少ないかstandalone— 事前のコンテキストなしで単独で成り立つかpayoff— 結末が有用、印象的、または共有したくなるものか
加重合計でランク付けします: hook × 0.35 + clarity × 0.25 + standalone × 0.2 + payoff × 0.2
4b. 候補数のガイダンス
| ソースの長さ | 目標候補数 |
|---|---|
| 20分未満 | 5 – 8 |
| 20 – 60分 | 8 – 12 |
| 60分以上 | 10 – 15 |
デフォルトの失敗モードは「多すぎる」ではなく「少なすぎる」であるべきです。 迷ったら、多く含めてください。ユーザーが選別します。
4c. 自動生成(ノイズの多い)字幕の扱い
YouTubeの自動キャプションには、しばしば以下が含まれます:
- 繰り返される断片(同じフレーズが連続するcueに現れる)
- 句読点と大文字小文字の欠落
- 聞き間違え(特に名前、専門用語)
ソース字幕が自動生成の場合:
- 意図された意味を控えめに推測する — 主張を作り出さない
- クリップ境界を判断する際は重複する断片を無視する
- 周囲のコンテキストを使用して文が実際にどこで終わるかを判断する
- ソースの品質が低い場合は、候補の要約にその旨を記す
4d. 出力を書き込む
2つのファイルを書き込みます:
-
studio/<slug>/intel/selected_clips.json— 機械可読なクリップ決定。playbooks/clip-contract.mdのスキーマに正確に従う必要があります。 -
studio/<slug>/intel/candidate-board.md— 人間が読めるレビューテーブル。
5. ユーザーレビューのために候補を提示する
候補リストをレビューしやすい形式で表示します。各候補について、以下を表示します:
| フィールド | フォーマット | 例 |
|---|---|---|
| ID | clip-XX | clip-01 |
| 時間範囲 | HH:MM:SS → HH:MM:SS | 00:12:03 → 00:13:22 |
| 長さ | 人間が読める形式 | 1m 19s |
| タイトル | 12文字以下の挑発的な中国語タイトル | AI终将取代一切? |
| 要約 | 中国語で正確に2文 | 文1: 何についてか。文2: なぜ見る価値があるか。 |
番号付きテーブルとして表示し、ユーザーがIDで返信できるようにします。
ユーザーが「続行」または「自動選択」と言った場合: 自分で最上位の候補を選択します。1時間の動画の場合、少なくとも8つをエクスポートします。
ユーザーが特定のIDを選んだ場合: それらのみをエクスポートします。
6. 選択された各クリップをエクスポートする
ユーザーが選択した(または自動選択した)各クリップについて、ステップ6aから6fまでを順番に実行します。次のクリップに移る前に、1つのクリップの全サブステップを完了してください。
6a. 動画セグメントを切り出す
python3 -m corekit.cut_video \
"studio/<slug>/intake/<正確なMP4ファイル名>" \
<開始秒> <終了秒> \
"studio/<slug>/exports/<クリップフォルダ>/clip.mp4"
<クリップフォルダ> の命名規則は XX-<タイトルスラッグ>, 例: 01-ai-will-replace です。
出力ファイルが存在し、サイズがゼロでないことを確認します。
6b. ソース字幕をウィンドウ化する
python3 -m corekit.window_subtitles \
"studio/<slug>/intake/<正確なSRTファイル名>" \
<開始秒> <終了秒> \
"studio/<slug>/exports/<クリップフォルダ>/clip.src.srt"
これにより、クリップウィンドウに重なるcueのみが抽出され、クリップが 00:00:00,000 で開始されるようにすべてのタイムスタンプがシフトされます。
出力SRTに少なくとも1つのcueがあることを確認します。
6c. 中国語字幕に翻訳する
clip.src.srt を読み、簡体字中国語に翻訳します。結果を同じフォルダの clip.zh.srt に書き込みます。
翻訳ルール(厳守すること):
- 自然な話し言葉の中国語 — 書き言葉や正式な中国語ではありません。視聴者はショート動画を見ており、文書を読んでいるわけではありません。
- タイムスタンプを正確に保持する — 読みやすさのために2つのcueをマージする必要がある場合を除き、タイミングを恣意的に変更しないでください。
- 固有名詞を正確に保持する — 人名、会社名、製品名、数字、引用句は忠実に保持する必要があります。
- 簡潔な行 — ショートフォーム動画のペースに合う短い中国語フレーズを優先します。長くスクロールする字幕はリテンションを殺します。
- 必要に応じてcue間でバランスを取る — 英語の文が3つのcueに分割されている場合、中国語のテキストを同じ3つのcueに再配分しても構いません。cueの順序は保持します。
- cueをまとめない — 40個のcueを持つcue密度の高い英語SRTは、10個ではなくおおよそ35〜45個の中国語cueを生成する必要があります。デフォルトの失敗モードは、少なすぎるのではなく、やや多すぎることです。
- 真の重複のみを削除する — 自動キャプションはしばしば同じ断片を連続するcueで繰り返します。重複は削除しても構いませんが、最初の出現は保持します。
- ソースがすでに中国語の場合 — 翻訳しないでください。明らかな自動キャプションノイズ(繰り返される断片、壊れた文字)のみをクリーンアップします。
6d. タイトルと説明文を生成する
各クリップについて、以下を作成します:
タイトル(最初の1秒のオーバーレイ用):
- シャープでクリックしたくなる、意見が明確
- フォントサイズ48で画面にきれいに収まるよう12中国語文字以下を目標とする
- 挑発的または反対意見でも構わないが、話者の意味に忠実でなければならない
- 好奇心、緊張感、または見続けたいという衝動を生み出すべき
説明文(プラットフォーム配信用):
- 140中国語文字以下
- 誰が話しているか、どの番組/インタビューからのものか、どのトピックが議論されているか、主な主張やポイントは何かを必ず記載する
両方を studio/<slug>/exports/<クリップフォルダ>/metadata.txt に書き込みます:
标题:AI终将取代一切?
描述:Sam Altman 在 Lex Fridman 播客中谈到 AGI 的时间表——他认为大多数人严重低估了 AI 的发展速度,未来三年将改变一切。
6e. 中国語字幕とタイトルを動画に焼き込む
python3 -m corekit.render_hardsubs \
"studio/<slug>/exports/<クリップフォルダ>/clip.mp4" \
"studio/<slug>/exports/<クリップフォルダ>/clip.zh.srt" \
"studio/<slug>/exports/<クリップフォルダ>/clip.hardsub.mp4" \
--title "<6dからのタイトル>"
重要: 中国語の clip.zh.srt ファイルを渡してください。clip.src.srt ではありません。これは最も一般的なエージェントのミスです — 翻訳ではなくソース言語の字幕を渡してしまうことです。
焼き込みステップでは以下を行います:
- libassを自動検出。利用できない場合はdrawtextレンダリングにフォールバック(あなたからのアクションは不要)
- 現在のマシンに最適なH.264エンコーダーを自動選択
- 最初の1秒間に、フォントサイズ48、3pxの黒い輪郭でタイトルを中央にレンダリング
- 残りのクリップの間、フレーム下部に字幕のcueをレンダリング
出力 clip.hardsub.mp4 が存在し、clip.mp4 よりもファイルサイズが大きいことを確認します(フィルターチェーンが視覚データを追加するため)。
6f. パッケージングコピーに追加する
各クリップがエクスポートされた後、そのタイトルと説明文を結合パッケージングファイルに追加します:
studio/<slug>/intel/packaging-copy.md
フォーマット:
## clip-01: AI终将取代一切?
**标题**: AI终将取代一切?
**描述**: Sam Altman 在 Lex Fridman 播客中谈到 AGI 的时间表...
**文件**: studio/<slug>/exports/01-ai-will-replace/clip.hardsub.mp4
**时长**: 1m 19s
---
7. 最終出力
すべてのクリップがエクスポートされた後、ユーザーに以下を返します:
- ソースアセットフォルダ:
studio/<slug>/intake/ - 候補リスト: ステップ5の完全なテーブル(タイムスタンプ、長さ、タイトル、要約)
- パッケージングファイル:
studio/<slug>/intel/packaging-copy.md - エクスポートされたクリップ: 各
clip.hardsub.mp4パスをリスト
ワークスペースレイアウトリファレンス
studio/<動画スラッグ>/
├── intake/ # YouTubeからの生アセット
│ ├── <タイトル> [<ID>].mp4 # ソース動画(yt-dlpからのファイル名)
│ └── <タイトル> [<ID>].<言語>.srt # ソース字幕
├── intel/ # 分析成果物
│ ├── transcript.json # 構造化された字幕cue(ステップ3から)
│ ├── selected_clips.json # クリップ決定(ステップ4から)
│ ├── candidate-board.md # レビューテーブル(ステップ4から)
│ └── packaging-copy.md # すべてのタイトルと説明文(ステップ6fから)
└── exports/ # エクスポートされたクリップごとのフォルダ
└── 01-<スラッグ>/
├── clip.mp4 # 生のカット(字幕なし)
├── clip.src.srt # ウィンドウ化されたソース言語字幕
├── clip.zh.srt # 翻訳された中国語字幕
├── clip.hardsub.mp4 # 最終納品物(焼き込み字幕とタイトル)
└── metadata.txt # このクリップのタイトルと説明文
モジュールリファレンス
| モジュール | 呼び出し方 | 引数 |
|---|---|---|
corekit.fetch_source | python3 -m corekit.fetch_source <url> <output_dir> | YouTube URL, 出力ディレクトリ |
corekit.subtitle_to_json | python3 -m corekit.subtitle_to_json <input.srt> <output.json> | SRTファイルパス, JSON出力パス |
corekit.cut_video | python3 -m corekit.cut_video <input.mp4> <start_sec> <end_sec> <output.mp4> | ソース動画, 開始秒 (float), 終了秒 (float), 出力パス |
corekit.window_subtitles | python3 -m corekit.window_subtitles <input.srt> <start_sec> <end_sec> <output.srt> | ソースSRT, 開始秒 (float), 終了秒 (float), 出力パス |
corekit.render_hardsubs | python3 -m corekit.render_hardsubs <input.mp4> <input.srt> <output.mp4> --title "..." | クリップ動画, 中国語SRT, 出力パス, オプションのタイトルテキスト |
render_hardsubs のオプションフラグ:
--font-size <size>— 字幕フォントサイズ(デフォルト: 36)--encoding <enc>— ビデオエンコーダーを手動で指定(例:libx264,h264_videotoolbox)--no-title— タイトルオーバーレイをスキップ(--title が指定されていない場合に有用)--debug— フィルターチェーンを試行する前に詳細なデバッグ情報を出力する