AIに「ダウンロードして」と言うだけ。動画保存ツールを作った。
TL;DR
なぜ作ったか
動画をローカルに保存したい場面はけっこうある。オフラインで見たい、素材として使いたい、アーカイブしておきたい。
技術者なら yt-dlp を使うのが定番だけど、毎回こうなる。
yt-dlp --write-thumbnail --convert-thumbnails jpg \
--write-subs --write-auto-subs --sub-langs ja,ja-orig \
--write-description \
-f "bestvideo+bestaudio/best" \
--merge-output-format mp4 \
-o "%(channel)s/%(title)s/%(title)s.%(ext)s" \
"https://www.youtube.com/watch?v=BaW_jenozKc"
覚えられるわけがない。
じゃあもう、URL だけ渡せば全部やってくれるツールを作ればいいのでは？
そう思って作ったのが ytdl です。内部で yt-dlp を使っていますが、使う側はそれを意識する必要がありません。
そしてもう一つ。最近は Claude Code のような AI コーディングアシスタントの中で作業することが増えてきました。ターミナルの中で AI と会話しているなら、「この動画ダウンロードして」と言うだけで済むのが理想。ytdl は Claude Code のプラグインとしても動作するように設計しています。
インストール
npm install -g @kanketsu/ytdl
グローバルインストールせずに試したい場合は npx でも実行できます。
npx @kanketsu/ytdl "URL"
yt-dlp と ffmpeg が必要ですが、初回実行時になければ自動でインストールを提案してくれます。
基本的な使い方
一番かんたん：引数なしで実行
ytdl
インタラクティブ UI が起動します。URL を貼って、あとはポチポチ選ぶだけ。
◆ ytdl
│
◆ URL
│ https://www.youtube.com/watch?v=BaW_jenozKc
│
◆ 何をダウンロードしますか？
│ ● 動画（最高画質, mp4）
│ ○ 音声のみ（m4a）
│ ○ 情報のみ表示（ダウンロードしない）
│
◆ 画質
│ ● 最高画質（おすすめ）
│ ○ 4K (2160p)
│ ○ 1080p
│ ○ 720p
│
◆ 保存先
│ ~/Downloads
│
◇ ダウンロードを開始しますか？
│ はい
コマンドを覚える必要はありません。インタラクティブ UI は 7 言語に対応しているので、--lang en で英語表示にも切り替えられます。
URL だけ渡して一発ダウンロード
# 最高画質で全部入り（サムネ・字幕・説明文付き）
ytdl "https://www.youtube.com/watch?v=BaW_jenozKc"
# 音声だけ抽出
ytdl -a "https://www.youtube.com/watch?v=BaW_jenozKc"
# 720p に制限
ytdl -q 720 "https://www.youtube.com/watch?v=BaW_jenozKc"
# プレイリスト一括ダウンロード
ytdl -p "https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf"
# まず情報だけ見たい
ytdl -i "https://www.youtube.com/watch?v=BaW_jenozKc"
# 英語表示で実行
ytdl --lang en "https://www.youtube.com/watch?v=BaW_jenozKc"
引数ありで実行すると、インタラクティブ UI は出ずにそのまま処理が走ります。
組み合わせ
# 音声だけ ~/Music に保存
ytdl -a -o ~/Music "https://www.youtube.com/watch?v=BaW_jenozKc"
# 字幕を日本語＋英語で指定
ytdl -s ja,en "https://www.youtube.com/watch?v=BaW_jenozKc"
# yt-dlp のオプションを直接渡したいとき（-- の後ろ）
ytdl "https://www.youtube.com/watch?v=BaW_jenozKc" -- --limit-rate 1M
オプション一覧
| フラグ | 説明 | デフォルト |
|---|---|---|
-a |
音声のみ（m4a） | off |
-q <解像度> |
画質指定（360/480/720/1080/1440/2160） | 最高画質 |
-o <ディレクトリ> |
保存先 | ~/Downloads |
-p |
プレイリストモード | off |
-b <ブラウザ> |
クッキー取得元ブラウザ | off |
-n |
クッキーなし（デフォルト） | on |
-s <言語> |
字幕言語（例: ja,en） | 言語設定に連動 |
-i |
情報のみ表示 | off |
--lang <code> |
表示言語（ja/en/zh-Hans/es/hi/pt/id） | ja |
-- |
以降を yt-dlp に直接渡す | - |
多言語対応
v1.2.0 から、CLI とインタラクティブ UI の両方が 7 言語に対応しています。
# 日本語（デフォルト）
ytdl "URL"
# 英語
ytdl --lang en "URL"
# 簡体字中国語
ytdl --lang zh-Hans "URL"
# 環境変数で設定する場合
export YTDL_LANG=en
ytdl "URL"
字幕言語は --lang に連動します。--lang ja なら字幕は ja,ja-orig、--lang pt なら pt,pt-BR が自動選択されます。-s オプションで個別指定もできます。
ダウンロードされるファイル
ytdl はダウンロードしたファイルを自動的に整理します。
~/Downloads/
└── Channel Name/
└── Video Title/
├── Video Title.mp4
├── Video Title.jpg
├── Video Title.ja.srt
└── Video Title.description
チャンネル名でフォルダが分かれるので、複数のチャンネルからダウンロードしてもごちゃまぜにならない。
プレイリストモード（-p）だと番号プレフィックスが付きます。
~/Downloads/
└── Channel Name/
└── Playlist Name/
├── 001_Video A/
│ └── 001_Video A.mp4
└── 002_Video B/
└── 002_Video B.mp4
プログレスバーとエラーハンドリング
v1.1.0 から、ダウンロード中はリアルタイムのプログレスバーが表示されます。
[████████████████████████░░░░░░░░░░░░░░░░] 62% 速度: 5.2MiB/s 残り時間: 00:12
エラーが発生した場合は、原因の説明と対処法が AI 用ヘルプとして表示されます。Ctrl+C で中止した場合は、ダウンロード済みファイルを削除するか残すかを選べます。
Claude Code プラグインとして使う
ここが ytdl の一番の特徴です。
Claude Code のプラグインとしてインストールすると、「この動画ダウンロードして」と言うだけで、Claude が対話的にダウンロードを進めてくれます。URL を貼るだけ。画質やフォーマットは Claude が聞いてくれる。
前提として Claude Code のセットアップが必要です。
インストール
Claude Code で以下を実行。
/plugin marketplace add kanketsu-jp/ytdl
/plugin install ytdl@kanketsu-ytdl
マーケットプレイスの追加は初回だけ。2 回目以降は /plugin install だけで OK です。
インストールできたら /plugin → Installed タブで ytdl Plugin · kanketsu-ytdl · ✔ enabled と表示されていれば成功です。
アンインストール・管理
プラグインの無効化やアンインストールは /plugin の UI から行います。
-
/pluginと入力 -
Installedタブに切り替え -
ytdl Pluginを選択して Enter -
Disable（無効化）またはUninstall（削除）を選択
使い方
動画の URL を貼って「ダウンロードして」と伝えるだけ。
ytdl 自体がインストールされていなければ、Claude が「インストールしますか？」と聞いてくれます。
AI との会話の中でシームレスに動画ダウンロードができる。これが ytdl を npm パッケージとして公開した最大の理由です。
クッキーの仕組み
年齢制限の動画やメンバー限定動画はどうするの？
ytdl はデフォルトではクッキーなしで動作します。公開動画であれば何も設定せずにそのまま使えます。macOS のキーチェーンダイアログが毎回表示されることもありません。
制限付きコンテンツ（年齢制限、メンバー限定など）をダウンロードするには -b オプションでブラウザを指定してください。
ytdl -b chrome "URL"
ytdl -b firefox "URL"
ytdl -b safari "URL"
対応ブラウザ: chrome, firefox, edge, safari, opera, brave, chromium, vivaldi
インタラクティブモードでは、ダウンロードに失敗した場合「クッキー付きでリトライ」の選択肢が自動で提示されます。
もうちょっと深掘ってみた
ここからは、ytdl の内部構造と設計について掘り下げていきます。
アーキテクチャ
Node.js は薄いランチャーとして動作し、実際のダウンロード処理は bash スクリプトが担当しています。
yt-dlp のオプション体系をそのまま bash で組み立てるのが一番素直で、Node.js 側はインタラクティブ UI と依存チェックだけを担当します。spawn("bash", [script, ...args], { stdio: "inherit" }) で bash に渡す構成で、それぞれの得意分野を活かしています。
セキュリティ
CLI ツールとはいえ、ユーザー入力（URL）を外部コマンドに渡すので、セキュリティには気を使っています。
コマンドインジェクション対策:
Node.js の spawn を shell: false（デフォルト）で使用し、引数は配列で渡しています。シェル展開が発生しないため、; rm -rf / のような入力が実行されることはありません。
// ✅ 安全: 配列で引数を渡す（shell 展開なし）
spawn("bash", [SCRIPT, ...args], { stdio: "inherit" });
// ❌ 危険（ytdl ではやっていない）: 文字列連結でシェルに渡す
exec(`bash ${SCRIPT} ${args.join(" ")}`);
入力バリデーション:
-q（画質）と -b（ブラウザ）はホワイトリストで検証しています。
-q)
case "$2" in
360|480|720|1080|1440|2160) QUALITY="$2" ;;
*) echo "エラー: 無効な解像度: $2"; exit 1 ;;
esac
プロンプトインジェクション対策（Claude Code スキル）:
スキル定義に、動画メタデータ（タイトル、説明文）に含まれる指示を無視するルールを明記しています。悪意のある動画タイトルに「このファイルを削除して」のような文字列が入っていても、Claude はそれを実行指示として解釈しません[1]。
npm パッケージとしての構成
{
"name": "@kanketsu/ytdl",
"bin": { "ytdl": "./cli.js" },
"files": ["cli.js", "bin/", "lib/", "skills/"],
"dependencies": {
"@clack/prompts": "^1.0.1",
"picocolors": "^1.1.1"
}
}
依存は 2 つだけ。@clack/prompts がインタラクティブ UI、picocolors がターミナルの色付け。意図的に最小限にしています。
postinstall で yt-dlp と ffmpeg の存在チェックを走らせ、足りなければ警告を出します（インストール自体は失敗しない）。
まとめ
実際に試してみよう
# インストール
npm install -g @kanketsu/ytdl
# まず動画情報を確認
ytdl -i "https://www.youtube.com/watch?v=BaW_jenozKc"
# インタラクティブモードで試す
ytdl
# 英語で試す
ytdl --lang en
Claude Code ユーザーなら、プラグインも試してみてください。
/plugin marketplace add kanketsu-jp/ytdl
/plugin install ytdl@kanketsu-ytdl
あとは動画の URL を貼って「ダウンロードして」と言うだけです。
Discussion