video-tool

Video Tool CLI

ffmpeg 操作、ローカルまたはリモートの Parakeet/Whisper による文字起こし、コンテンツ生成に対応した AI 搭載の動画処理ツールキットです。

インストール状況

video-tool: !which video-tool > /dev/null && echo "INSTALLED" || echo "NOT INSTALLED - run installation below" uv: !which uv > /dev/null && echo "INSTALLED" || echo "NOT INSTALLED"

video-tool がインストールされていない場合は、続行する前に以下のインストールコマンドを実行してください。

インストール

# Install uv first (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install video-tool
uv tool install git+https://github.com/alejandro-ao/video-tool-cli.git

依存関係

• ffmpeg：すべての動画操作に必要です（macOS では brew install ffmpeg）。
• yt-dlp：動画のダウンロードに必要です（macOS では brew install yt-dlp）。
• ローカル文字起こしランタイムは任意です。Transcription & Timestamps に記載されている、プラットフォーム固有の追加機能をインストールしてください。

API キーの設定

API キーを設定します（いずれかの方法を選択してください）。

オプション 1：非対話型（Claude Code におすすめ）

video-tool config keys --set groq_api_key=YOUR_KEY
video-tool config keys --set openai_api_key=YOUR_KEY
# Multiple at once:
video-tool config keys --set groq_api_key=xxx --set openai_api_key=yyy

オプション 2：認証情報ファイルを直接編集 Claude Code にキーを共有したくない場合は、直接編集できます。

# File: ~/.config/video-tool/credentials.yaml
openai_api_key: sk-xxx
groq_api_key: gsk_xxx
bunny_library_id: xxx
bunny_access_key: xxx
replicate_api_token: xxx

オプション 3：対話型セットアップ

video-tool config keys

必須のキー：

• openai_api_key - CLI によるコンテンツ生成（説明、コンテキストカード、文字起こしベースのタイムスタンプ）

任意のキー：

• groq_api_key - リモートの Groq Whisper 文字起こし用。ローカルモデルでは不要です。
• bunny_library_id、bunny_access_key - Bunny.net CDN へのアップロード用
• replicate_api_token - 音声の補正用

video-tool config keys --show   # View configured keys (masked)
video-tool config keys --reset  # Clear all credentials

重要：認証エラーへの対処

コマンドが「AUTHENTICATION REQUIRED」または「API key not configured」で失敗した場合：

1. カスタムスクリプトを書いて問題を回避しようとしないでください
2. API を直接呼び出そうとしないでください
3. 代わりにAskUserQuestion を使って、ユーザーに 2 つの選択肢を提示してください。

オプション A：Claude にキーを渡す（簡単）

• ユーザーが API キーを直接渡します。
• 次を実行します：video-tool config keys --set KEY_NAME=VALUE
• より早く設定できますが、キーは会話内に表示されます。

オプション B：ユーザーが非公開で設定する（より安全）

• ユーザー自身がコマンドを実行するか、ファイルを直接編集します。
• キーは Claude との会話に表示されません。
• 次を実行するようユーザーに伝えます：video-tool config keys（対話型）
• または、次を編集します：~/.config/video-tool/credentials.yaml

AskUserQuestion のプロンプト例： 「このコマンドには [Groq/OpenAI] API キーが必要です。どの方法で設定しますか？」

• オプション 1：「キーを渡します」 - 手軽ですが、キーは Claude に表示されます。
• オプション 2：「自分で設定します」 - よりプライベートで、キーは Claude に表示されません。

どちらかの方法でユーザーが設定した後、元のコマンドを再試行してください。

認証情報が必要なコマンド：

• video-tool generate transcript -m groq/whisper-large-v3-turbo → Groq API キーが必要です。
• ローカル文字起こしモデル → API キーは不要ですが、任意のランタイムをインストールする必要があります。
• video-tool video timestamps -m transcript → OpenAI API キー（構造化出力）が必要です。
• video-tool upload bunny-* → Bunny.net の認証情報が必要です。
• video-tool video enhance-audio → Replicate API トークンが必要です。
• video-tool upload x / video-tool upload twitter → X OAuth 認証情報が必要です（video-tool config x-auth を実行）。
• video-tool upload linkedin → LinkedIn アクセストークン + author URNが必要です（video-tool config keys を実行するか、フラグを渡してください）。

---

コンテンツ生成：CLI コマンドと直接生成の比較

一部の CLI コマンドは OpenAI を使ってコンテンツを生成します。Claude がこのスキルを実行する場合、別の LLM を呼び出すより、Claude が直接コンテンツを生成するほうが適切なことがよくあります。

CLI コマンドを使用（OpenAI API キーが必要）：

• video timestamps -m transcript - 高精度な JSON を得るために構造化出力を使用します。

Claude として直接生成します（OpenAI は不要です）：

これらのタスクでは、トランスクリプト／タイムスタンプを読み込み、リンク先のテンプレートを使ってコンテンツを生成します。

• 説明：templates/description.mdを参照してください
• SEO キーワード：templates/seo-keywords.mdを参照してください
• LinkedIn／Twitter の投稿：templates/social-posts.mdを参照してください
• コンテキストカード：templates/context-cards.mdを参照してください

CLI コマンドに関する注意

CLI には、OpenAI を使用する generate description や generate context-cards などのコマンドがあります。これらは CLI を手動で使うためのものです。ユーザーから CLI コマンドの実行を明示的に依頼された場合は、その依頼に従ってください（OpenAI キーが必要になる場合があります）。それ以外の場合は、コンテンツを直接生成してください。

---

出力先

ファイル（トランスクリプト、説明、タイムスタンプなど）を生成する前に、保存先が指定されていない場合は、AskUserQuestion を使ってユーザーに確認してください。

質問例： 「出力ファイルはどこに保存しますか？」

• 選択肢 1：「現在のディレクトリ」— . または ./output/ に保存します
• 選択肢 2：「動画と同じフォルダー」— ソース動画と同じ場所に保存します
• 選択肢 3：「パスを指定する」— ユーザーが保存先を指定します

ユーザーが指定しなかった場合のデフォルトの動作： 一時ディレクトリを想定せず、確認してください。

---

長時間実行される処理：tmux を使用

ダウンロードや、長時間かかる可能性のある動画処理は、エージェントのシェルをブロックせず、名前付きの tmux セッション内でコマンドを実行してください。これには、YouTube／動画のダウンロード、アップロード、無音部分の削除、音声の補正、文字起こし、大規模なレンダリング／トランスコードが含まれます。

推奨パターン：

# Start the job in the background
tmux new-session -d -s video_download 'video-tool video download -u "URL" -o "./output/video.mp4"'

# Check progress/log output
tmux capture-pane -pt video_download

# Reattach if needed
tmux attach -t video_download

# Clean up after completion
tmux kill-session -t video_download

video_download、video_transcribe、video_upload、video_process_<slug> など、用途が分かるセッション名を使用してください。tmux ジョブの起動後は、完了するまで tmux capture-pane -pt <session> で進捗を確認し、想定される出力ファイルが存在することを検証してください。

---

YouTube 認証

YouTube へのアップロードには、OAuth2 のセットアップを実行してください：

video-tool config youtube-auth

---

コマンドリファレンス

動画処理

動画のダウンロード

YouTube またはその他の対応サイトからダウンロードします。

video-tool video download -u "URL" -o ./output/my-video.mp4
video-tool video download -u "URL" -o ./output/%(title)s.%(ext)s

オプション	説明
-u, --url	動画の URL
-o, --output-path	出力ファイルのパス（ディレクトリを指定した場合はタイトルテンプレートを使用。デフォルトは ./output/%(title)s.%(ext)s）

動画情報の取得

長さ、解像度、コーデック、ビットレートなどのメタデータを取得します。

video-tool video info -i video.mp4

無音部分の削除

動画から無音部分を削除します。

video-tool video silence-removal -i input.mp4 -o output.mp4 -t 1.0

オプション	説明
-i, --input	入力動画
-o, --output-path	出力先のパス
-t, --threshold	削除する無音部分の最小時間（デフォルト：1.0s）

動画のトリミング

動画の冒頭や末尾をカットします。

video-tool video trim -i input.mp4 -o output.mp4 -s 00:00:10 -e 00:05:00

オプション	説明
-s, --start	開始タイムスタンプ（HH:MM:SS、MM:SS、または秒数）
-e, --end	終了タイムスタンプ
-g, --gpu	GPU アクセラレーションを使用

セグメントの抽出

動画から特定の部分だけを残します。

video-tool video extract-segment -i input.mp4 -o output.mp4 -s 00:01:00 -e 00:02:30

セグメントのカット

動画の途中の部分を削除します。

video-tool video cut -i input.mp4 -o output.mp4 -f 00:01:00 -t 00:02:00

オプション	説明
-f, --from	削除するセグメントの開始位置
-t, --to	削除するセグメントの終了位置

再生速度の変更

動画を早送りまたはスローモーションにします。

video-tool video speed -i input.mp4 -o output.mp4 -f 1.5

オプション	説明
-f, --factor	速度係数（0.25-4.0）。2.0 は 2 倍、0.5 は半分
-p, --preserve-pitch	元の音声のピッチを維持します（デフォルト：yes）

動画の連結

複数の動画を 1 つに結合します。

video-tool video concat -i ./clips/ -o ./output/final.mp4 -f

オプション	説明
-i, --input-dir	動画を含むディレクトリ
-o, --output-path	出力ファイルのパス
-f, --fast-concat	再エンコードを省略します（高速ですが、同じコーデックが必要です）

音声処理

音声の抽出

音声トラックを MP3 に抽出します。

video-tool video extract-audio -i video.mp4 -o audio.mp3

音声の補正

Resemble AI を使って音質を改善します（Replicate API トークンが必要です）。

video-tool video enhance-audio -i input.mp4 -o enhanced.mp4
video-tool video enhance-audio -i input.mp4 -o denoised.mp4 -d  # denoise only

音声の置換

動画の音声トラックを入れ替えます。

video-tool video replace-audio -v video.mp4 -a new_audio.mp3 -o output.mp4

文字起こしとタイムスタンプ

トランスクリプトを生成する

自動選択されたインストール済みランタイム、明示的に指定したローカルモデル、または Groq を使って VTT 字幕を作成します。

マシンで初めて文字起こしを行う前に、推奨内容と利用可能なモデル ID を確認してください：

video-tool config transcription --recommend
video-tool config transcription --list-models

ローカルで文字起こしを行う場合は、適切なオプションのランタイムをインストールしてください：

# Apple Silicon: MLX Parakeet (English) and MLX Whisper (multilingual)
uv tool install --force 'video-tool[transcription-mlx] @ git+https://github.com/alejandro-ao/video-tool-cli.git'

# Portable CPU/CUDA Whisper
uv tool install --force 'video-tool[transcription-faster-whisper] @ git+https://github.com/alejandro-ao/video-tool-cli.git'

# Standard Hugging Face Transformers Whisper
uv tool install --force 'video-tool[transcription-transformers] @ git+https://github.com/alejandro-ao/video-tool-cli.git'

# NVIDIA NeMo Parakeet on Linux/CUDA
uv tool install --force 'video-tool[transcription-nemo] @ git+https://github.com/alejandro-ao/video-tool-cli.git'

自動選択または明示的に指定したモデルを使って文字起こしを行います：

video-tool generate transcript -i video.mp4 -o transcript.vtt
video-tool generate transcript -i video.mp4 -o transcript.vtt -m mlx/parakeet-tdt-0.6b-v2 --language en
video-tool generate transcript -i video.mp4 -o transcript.vtt -m mlx/whisper-large-v3-turbo --language es
video-tool generate transcript -i video.mp4 -o transcript.vtt -m groq/whisper-large-v3-turbo

モデルの選択ガイド：

• Apple Silicon ＋ 英語：mlx/parakeet-tdt-0.6b-v2
• Apple Silicon ＋ 多言語：mlx/whisper-large-v3-turbo
• ポータブル CPU/CUDA：faster-whisper/large-v3-turbo
• 標準の Transformers/MPS/CUDA：transformers/whisper-large-v3-turbo
• NVIDIA Linux/CUDA ＋ 英語：nemo/parakeet-tdt-0.6b-v2
• ローカルランタイムがない場合、またはリモート処理を優先する場合：groq/whisper-large-v3-turbo

Parakeet TDT 0.6B V2 は英語のみ対応しています。モデルは初回使用時にダウンロードされ、ローカルにキャッシュされます。オプションのランタイムが不足している場合は、インストールコマンドが表示されます。Groq での文字起こしには Groq API キーが必要です。

詳細オプション：

オプション	説明
--backend	バックエンドの上書き：auto、groq、mlx-parakeet、mlx-whisper、faster-whisper、transformers、nemo
-m, --model	登録済みモデル ID。バックエンドのみを選択する場合より優先されます
--language	auto、または en、es、fr などの言語コード
--device	auto、cpu、mps、または cuda
--compute-type	float16 や int8 などのランタイム精度

デフォルトを保存または確認します：

video-tool config transcription --model mlx/parakeet-tdt-0.6b-v2 --language en
video-tool config transcription --show
video-tool config transcription --reset

このスキルを実行する際は、ランタイムがインストール済みであれば、推奨されるローカルモデルを優先してください。大きなオプションのランタイムのインストールやモデルの重みのダウンロードを行う前に、ユーザーに確認してください。ユーザーがリモート処理を希望する場合、またはローカルのハードウェアやランタイムが適していない場合は、Groq を使用してください。

タイムスタンプを生成する

チャプターマーカーを作成します（トランスクリプトモードでは OpenAI API キーが必要です）。

# From video clips directory
video-tool video timestamps -m clips -i ./clips/ -o timestamps.json

# From transcript
video-tool video timestamps -m transcript -i transcript.vtt -o timestamps.json -g medium

オプション	説明
-m, --mode	clips または transcript
-g, --granularity	low、medium、high（トランスクリプトモード）
-n, --notes	LLM への追加指示

アップロード

YouTube へのアップロード

動画を下書きとしてアップロードします（video-tool config youtube-auth による OAuth2 認証が必要です）。

video-tool upload youtube-video -i video.mp4 -t "Title" -d "Description" -p private
video-tool upload youtube-video -i video.mp4 --metadata-path metadata.json

オプション	説明
-t, --title	動画のタイトル
-d, --description	説明文
--description-file	ファイルから説明文を読み込みます
--tags	カンマ区切りのタグ
--tags-file	ファイルからタグを読み込みます（1 行に 1 つ）
-c, --category	YouTube カテゴリ ID（デフォルト：27 Education）
-p, --privacy	private（下書き）または unlisted のみ
--thumbnail	サムネイル画像のパス

YouTube メタデータの更新

既存動画のメタデータを更新します。

video-tool upload youtube-metadata -v VIDEO_ID --description-file description.md

YouTube へのトランスクリプトのアップロード

YouTube 動画に字幕を追加します。

video-tool upload youtube-transcript -v VIDEO_ID -t transcript.vtt -l en

Bunny.net へのアップロード

Bunny.net CDN にアップロードします（config keys による Bunny 認証情報の設定が必要です）。

video-tool upload bunny-video -v video.mp4
video-tool upload bunny-transcript -v VIDEO_ID -t transcript.vtt
video-tool upload bunny-chapters -v VIDEO_ID -c timestamps.json

X（Twitter）への投稿

X（Twitter）にスレッドを投稿します（video-tool config x-auth による X OAuth 認証が必要です）。

video-tool upload x --text "First post" --thread-item "Follow-up" --video-path video.mp4
video-tool upload twitter --text-file post.txt --thread-file thread.txt

オプション	説明
--text / --text-file	最初の投稿のテキスト
--thread-item / --thread-file	追加のスレッド項目（繰り返し指定するか、--- 区切りを使用）
--video-path / --video-url	添付する動画ファイルまたは URL
--output-dir	メタデータの出力ディレクトリ

LinkedIn への投稿

LinkedIn に投稿を公開します（video-tool config keys による LinkedIn 認証情報の設定が必要です）。

video-tool upload linkedin --text-file post.md --video-path video.mp4

オプション	説明
--text / --text-file	投稿テキスト
--video-path / --video-url	添付する動画ファイルまたは URL
--output-dir	メタデータの出力ディレクトリ
--access-token	アクセストークンを上書きします
--author-urn	作成者 URN を上書きします

設定

video-tool config keys                        # Configure API keys (interactive)
video-tool config keys --set KEY=VALUE        # Set key non-interactively
video-tool config keys --show                 # View configured keys
video-tool config llm                         # Configure LLM settings and persistent links
video-tool config transcription --recommend  # Recommend a transcription model
video-tool config transcription --list-models # List supported transcription models
video-tool config transcription --show       # Show saved transcription defaults
video-tool config x-auth                      # Set up X OAuth credentials
video-tool config youtube-auth                # Set up YouTube OAuth2
video-tool config youtube-status              # Check YouTube credentials

---

スキル用コマンドテンプレート

他のスキルから名前を指定して参照できる、よく使われるタスクです。

動画の文字起こし

自動選択またはモデルの明示的な指定により、動画／音声ファイルから VTT 形式の文字起こしを生成します。

video-tool config transcription --recommend
video-tool generate transcript -i <INPUT_FILE> -o <OUTPUT_FILE> [-m <MODEL_ID>] [--language <LANGUAGE>]

入力：

• <INPUT_FILE>：動画または音声ファイルのパス
• <OUTPUT_FILE>：出力する VTT ファイルのパス
• <MODEL_ID>：任意。登録済みのローカルモデルまたは Groq モデルの ID
• <LANGUAGE>：任意。言語コード。Parakeet を使用する場合は en を指定します

要件： 選択したローカルランタイムの追加機能、または Groq を選択した場合に限り Groq API キーが必要です

---

動画の連結

複数の動画クリップを 1 つのファイルに連結します。

video-tool video concat -i <INPUT_DIR> -o <OUTPUT_FILE> --fast-concat

入力：

• <INPUT_DIR>：連番のクリップが含まれるディレクトリ（01-.mp4、02-.mp4 など）
• <OUTPUT_FILE>：出力する動画ファイルのパス
• --fast-concat：再処理をスキップします（任意。速度向上のため推奨）

注： 正しい順序で処理されるよう、クリップ名には数字の接頭辞を付ける必要があります。

---

クリップからタイムスタンプを生成

クリップのファイル名からチャプターのタイムスタンプを作成します。

video-tool video timestamps --mode clips -i <INPUT_DIR> -o <OUTPUT_FILE>

入力：

• <INPUT_DIR>：連番のクリップが含まれるディレクトリ
• <OUTPUT_FILE>：出力する JSON ファイルのパス

出力形式：

{
  "timestamps": [
    {"time": "00:00:00", "title": "Introduction"},
    {"time": "00:05:30", "title": "Main Content"}
  ]
}

---

YouTube にアップロード

メタデータとともに動画を YouTube にアップロードします。

video-tool upload youtube-video \
  -i <VIDEO_FILE> \
  -t "<TITLE>" \
  --description-file <DESCRIPTION_FILE> \
  --tags-file <TAGS_FILE> \
  --privacy <PRIVACY>

入力：

• <VIDEO_FILE>：動画ファイルのパス
• <TITLE>：動画のタイトル（引用符で囲みます）
• <DESCRIPTION_FILE>：Markdown 形式の説明ファイルのパス
• <TAGS_FILE>：タグを 1 行に 1 つずつ記載したテキストファイルのパス
• <PRIVACY>：private、unlisted、public のいずれか

要件： YouTube OAuth2 認証（video-tool config youtube-auth）

出力： video_id と url を含む JSON（publish スキル用に youtube-upload.json として保存します）

---

一般的なワークフロー

詳しい例については、workflows.md を参照してください。