youtube-publisher

🔴 厳格な実行ルール（最優先）

この SKILL.md に記載されているすべての指示、手順、確認事項を、逸脱することなく記載どおりに正確に実行してください。

• スクリプトは必ず実際に実行してください：youtube-upload.ts スクリプトを、必須の全パラメーターを指定して実行してください。実行をシミュレートしたり、API 呼び出しを手動で組み立てたりしないでください。
• 手順を省略したり統合したりしないでください：認証、メタデータのサニタイズ、アップロードを、定義された順序で実行してください。次の手順に進む前に、各手順が成功している必要があります。
• 確認事項を省略しないでください：すべてのメタデータ検証（タイトル ≤100 文字、説明 ≤5000 文字、タグ ≤500 文字）とアップロードの検証を完全に実行してください。
• 設定はファイルから読み込んでください：OAuth 認証情報とデフォルト設定は、設定済みのファイルから読み込んでください。ハードコードしないでください。

---

YouTube Publisher

初めてですか？ 上記の setup_complete: false の場合は、まず ./SETUP.md を実行してから、setup_complete: true に設定してください。

メタデータを細かく制御して、動画を YouTube にアップロードします。

ライブ配信とエンコーダーのストリーム

youtube-live.ts を使用して、YouTube Live のライブ配信とエンコーダーのストリームを一覧表示、確認、スケジュール設定、更新、紐付け、切り替え、削除できます。変更を伴うコマンドは --dry-run に対応しています。破壊的な削除、ライブ状態／完了状態の切り替え、ストリームキーの開示には、明示的な --yes が必要です。通常の出力ではストリームキーが伏せられます。

安全なデフォルトでは、独立した各番組／イベントに専用の名前付きエンコーダーストリームを 1 つ使用します。配信中または配信予定の複数の配信で意図的に同じストリームを再利用するには、--allow-shared-stream を指定してください。

ライブイベントを操作する前に、references/live-streaming.md をお読みください。スケジュールのタイムスタンプには、明示的なタイムゾーン（Z または ±HH:MM）を含める必要があります。

ユーザーがクリーンなプロファイルを要求しない限り、このスキルは作成前に --inherit-previous を渡します。この明示的なフラグがない場合、未加工の CLI は決定的に動作し、オフラインで実行されます。

中断された動画の挿入は、youtube-upload.ts 内では再試行されません。復旧するには、検証済みの 0 以外の再生時間を持つ、同じタイトルの最新の動画を 1 件だけ特定する必要があります。P0D が継続する場合は PERSISTENT_P0D_VIDEO_ID とともに終了コード 42 で終了します。確認できない、または判断できない場合は AMBIGUOUS_UPLOAD_VIDEO_ID とともに終了コード 43 で終了します。別の動画を挿入する前に、チャンネルを確認してください。

字幕の復旧では、正確に一致する言語／名前のトラックをその場で更新するか、新しいトラックを挿入します。置き換えのアップロードが成功する前に、既存の字幕を削除することはありません。

メタデータのサニタイズ

• タイトル／説明の > は自動的に 》 に書き換えられます
• タイトル／説明の < は自動的に 《 に書き換えられます
• 特殊文字が原因で YouTube がメタデータを拒否した場合に使用します

クイックスタート

cd ~/.claude/skills/youtube-publisher/scripts

# First time: authenticate
npx ts-node youtube-upload.ts --auth

# Upload video
npx ts-node youtube-upload.ts \
  --video /path/to/video.mp4 \
  --title "My Awesome Video" \
  --description "Check out this amazing content!" \
  --tags "tech,ai,tutorial" \
  --privacy unlisted

# Upload as YouTube Short (vertical video)
npx ts-node youtube-upload.ts \
  --video /path/to/short.mp4 \
  --title "Quick Tip #Shorts" \
  --description "A quick tip for you!" \
  --privacy public \
  --short

オプション

オプション	短縮形	説明
--video	-v	動画ファイルのパス（必須）
--title	-t	動画のタイトル（必須）
--description	-d	動画の説明
--tags		カンマ区切りのタグ
--privacy	-p	公開範囲：public、unlisted、private（デフォルト：unlisted）
--category	-c	カテゴリー ID（デフォルト：22 = People & Blogs）
--thumbnail		カスタムサムネイル画像（ローカルパスまたは URL）
--subtitles		字幕ファイルのパス（SRT/VTT）
--subtitle-lang		字幕の言語コード（デフォルト：zh）
--subtitle-name		字幕の表示名（デフォルト：中文）
--short		YouTube Short として設定
--auth		OAuth2 認証フローを実行
--dry-run		アップロードせずにプレビュー

プレイリストカタログのエクスポート

認証済みチャンネルが所有する公開プレイリストをすべてエクスポートします。順序付きの動画 ID とサムネイルも含まれます。ブログ同期ツールは、この決定的な JSON を使用して /series/、GitHub のシリーズページ、リソースサイトのガイドハブを構築します。

このコマンドは読み取り専用です。最終通知を依頼する前に、作成者がプレイリストのメンバーを手動で管理します。export-playlists.ts がプレイリストのメンバーを追加、削除、並べ替え、または推測することは決してありません。通知パイプラインはエクスポートを新たに実行し、ブログのトピックページをデプロイして、公開フィンガープリントを検証してから通知を送信します。

cd ~/.codex/skills/youtube-publisher/scripts
npm run export:playlists -- --output /absolute/path/youtube-playlists.json

カテゴリ ID

ID	カテゴリ
1	映画・アニメーション
2	自動車・乗り物
10	音楽
15	ペット・動物
17	スポーツ
19	旅行・イベント
20	ゲーム
22	人物・ブログ
23	コメディ
24	エンターテインメント
25	ニュース・政治
26	ハウツー・スタイル
27	教育
28	科学・テクノロジー

認証

初回のセットアップでは OAuth2 認証が必要です。

1. npx ts-node youtube-upload.ts --auth を実行します
2. ブラウザーで Google のログイン画面が開きます
3. 動画のアップロードを許可します
4. トークンが .youtube-token.json に保存されます

トークンは自動的に更新されます。有効期限が切れた場合は、--auth を再実行してください。

環境

scripts/.env を作成します。

YOUTUBE_CLIENT_ID=your_client_id
YOUTUBE_CLIENT_SECRET=your_client_secret

Google Cloud Console から認証情報を取得します。

1. console.cloud.google.com でプロジェクトを作成します
2. YouTube Data API v3 を有効にします
3. OAuth2 認証情報（デスクトップアプリ）を作成します
4. client_id と client_secret をダウンロードして抽出します

使用例

チュートリアル動画をアップロードする

npx ts-node youtube-upload.ts \
  -v tutorial.mp4 \
  -t "How to Use Claude Code - Complete Guide" \
  -d "Learn everything about Claude Code in this comprehensive tutorial.

Timestamps:
00:00 Introduction
02:30 Getting Started
05:00 Advanced Features

#ClaudeCode #AI #Tutorial" \
  --tags "claude code,ai,tutorial,anthropic,coding" \
  --category 28 \
  --privacy public

YouTube Short をアップロードする

npx ts-node youtube-upload.ts \
  -v short_video.mp4 \
  -t "Mind-blowing AI trick! #Shorts" \
  -d "This will change how you work! #AI #Tech" \
  --privacy public \
  --short

サムネイルと字幕を付けてアップロードする

npx ts-node youtube-upload.ts \
  -v tutorial.mp4 \
  -t "Tutorial with Subtitles" \
  -d "Learn step by step with subtitles" \
  --thumbnail /path/to/cover.jpg \
  --subtitles /path/to/subtitles.srt \
  --subtitle-lang zh \
  --subtitle-name "中文" \
  --privacy public

ローカルのサムネイルを付けてアップロードする

npx ts-node youtube-upload.ts \
  -v video.mp4 \
  -t "My Video Title" \
  --thumbnail "/Users/m/Downloads/shell/work/cover.jpg" \
  --privacy public

失敗したサムネイルのみ再試行する

動画がすでに存在し、カスタムサムネイルのみを再アップロードする必要がある場合は、専用の復旧コマンドを使用します。このコマンドは動画 ID とローカルの JPG/PNG ファイルを検証し、一時的な失敗を再試行して、対象の動画が読み取り可能であることを確認し、構造化された結果マーカーを出力します。

npx ts-node upload-thumbnail.ts \
  --video-id VIDEO_ID \
  --thumbnail /path/to/cover.jpg \
  --attempts 3

このコマンドが動画を削除またはアップロードすることは決してありません。動画 ID やローカルパスをハードコードした、その場限りの復旧スクリプトを作成しないでください。

出力

成功すると、以下を返します。

• 動画 ID
• 動画 URL（https://youtu.be/VIDEO_ID）
• ステータス

制限事項

• 最大ファイルサイズ：256GB（YouTube の制限）
• 対応形式：MP4、MOV、AVI、WMV、FLV、3GP、MPEG
• 対応字幕形式：SRT、VTT
• 1 日あたりのアップロード割り当て：10,000 ユニット（通常は 1 日あたり約 6 本）
• タイトルの最大文字数：100 文字
• 説明の最大文字数：5,000 文字
• タグの合計最大文字数：500 文字

変更履歴

v1.7.1 - 未知のフラグを即時エラーにする処理（2026-09-28）

• youtube-update-description.ts v1.8（2026-10-01）チャプター表示契約ゲート：アップロード前に、説明内のチャプターブロックが YouTube の必須ルール（最初のチャプターは 0:00／各チャプターは 10 秒以上／チャプターは 3 つ以上）を満たしているか検証します。違反がある場合はアップロードを拒否して exit 3で終了し、具体的な違反を列挙します。理由：条件を 1 つでも満たさないと、YouTube はチャプターリスト全体をサイレントに無視します。説明は正常に見えても、再生バーにチャプターが表示されません（2026-10-01、charles_schwab の 0:00／0:01 が隣接する 1 秒間隔となり、18 個すべてのチャプターが無効化）。説明にチャプターブロックがまったくない場合は WARN を出すだけで、処理はブロックしません。修正には duanku-youtube-publish/scripts/split_description_chapters.py（自己修復機能を内蔵）を使用し、--validate で再検証してください。
• youtube-update-description.ts は未知の -- パラメーターを検出するとエラーを報告して終了（exit 2）し、サイレントに無視することはなくなりました。背景：同日のテストで、存在しないフラグ --dry-run がサイレントに無視され、切り詰められたテストファイルが実際にアップロードされました。即時エラーにすることで、同様の誤操作を防ぎます。

v1.7.0 - ベースラインヘッダーのアップロードガード（2026-09-28）

• youtube-update-description.ts は、アップロード前に duanku のベースラインヘッダーを自動的に削除するようになりました。--description-file の内容が # YouTube description baseline で始まる場合（run_pipeline v2.46 以降が保存する、手動差分確認用ファイル）、先頭のコメントブロックを削除してからアップロードし、NOTE: stripped baseline header before upload (v1.7 guard) を出力します。
• 背景：9/15（tello）、9/27（capital_one）、9/28（maya）の 3 回にわたり、エージェント主導の説明編集でヘッダー付きのベースラインファイルがそのまま再アップロードされ、# コメント 6 行が YouTube の説明欄に公開されました（tello と capital_one はユーザーが手動で削除し、maya はこのバージョンで修正済み）。ガードはアップロード箇所に設けられているため、今後はどの呼び出し経路からもヘッダーが公開されることはありません。

v1.6.0 - サムネイルのみの安全な復旧（2026-07-28）

• パラメーター検証、回数を制限した再試行、対象動画の検証、構造化出力を備えた upload-thumbnail.ts を追加しました。
• 固定の動画 ID も削除する、ハードコードされたサムネイル修復スクリプトを削除しました。
• サムネイル復旧コマンドも対象に含めるよう、本番用 TypeScript ゲートを拡張しました。

v1.1 - 再開可能なアップロード + リトライ（2026-04-22）

• 進行状況を追跡する再開可能なアップロードに切り替え、大容量ファイルのアップロード時に発生する EPIPE エラーを修正しました
• 一時的なネットワークエラー（EPIPE、ETIMEDOUT、ECONNRESET）に対する自動リトライ（最大 3 回）を追加しました
• アップロードの進行状況ログを追加しました（10% ごと）
• アップロード互換性を高めるため、media.mimeType を追加しました

v1.0 - 初回リリース

• メタデータ付きの基本的な動画アップロード
• サムネイル、字幕、プレイリストに対応
• OAuth2 認証