Communitygithub.com

YouTube トランスクリプトダウンローダー

ユーザーが YouTube の URL を提供したり、YouTube からトランスクリプトをダウンロード/取得/フェッチするよう依頼した場合に、YouTube 動画のトランスクリプトをダウンロードします。また、ユーザーが YouTube 動画から文字起こしやキャプション/字幕を取得したい場合にも使用します。

YouTube トランスクリプトダウンローダー とは?

このスキルは、yt-dlp と Whisper を活用して、YouTube 動画のトランスクリプト(字幕/キャプション)をダウンロード・処理するための強力なツールです。主に手動字幕(高品質)と自動生成字幕を優先し、どちらも利用できない場合の最終手段として Whisper による音声文字起こしを行います。また、ダウンロードした VTT ファイルから重複を除去したプレーンテキストへの変換機能も備えています。このスキルは Claude Code、Cursor、Codex などの AI エージェントプラットフォームで動作し、ユーザーに YouTube 動画のテキストコンテンツを提供するための完全なワークフローを実装しています。インストール確認、字幕の利用可能性チェック、ダウンロード戦略の段階的な実行、エラーハンドリング、そしてクリーンアップまでを自動化しているため、開発者やコンテンツ分析者にとって非常に有用です。

対応✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/IGTA-Tech/claude-skills-research/tree/HEAD/tapestry-skills-for-claude-code/youtube-transcript

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

YouTube トランスクリプトダウンローダー は何をしますか?

このスキルは、yt-dlp を使用して YouTube 動画からトランスクリプト(字幕/キャプション)をダウンロードするのに役立ちます。

このスキルを使用するタイミング

ユーザーが次のような場合にこのスキルを有効にします:

  • YouTube の URL を提供し、トランスクリプトを希望する
  • 「YouTube からトランスクリプトをダウンロード」したい
  • 動画の「キャプション」や「字幕」を取得したい
  • 「YouTube 動画を文字起こし」したい
  • YouTube 動画からテキストコンテンツを必要としている

動作の仕組み

優先順位:

  1. yt-dlp がインストールされているか確認 - 必要に応じてインストール
  2. 利用可能な字幕を一覧表示 - 実際に何が利用可能かを確認
  3. 手動字幕を最初に試す (--write-sub) - 最高品質
  4. 自動生成字幕にフォールバック (--write-auto-sub) - 通常利用可能
  5. 最終手段: Whisper による文字起こし - 字幕がない場合(ユーザーの確認が必要)
  6. ダウンロードを確認し、ファイルが保存された場所をユーザーに表示
  7. オプションで VTT 形式をクリーンアップし、ユーザーがプレーンテキストを希望する場合

インストール確認

重要: まず常に yt-dlp がインストールされているか確認します:

which yt-dlp || command -v yt-dlp

インストールされていない場合

システムに基づいて自動インストールを試みます:

macOS (Homebrew):

brew install yt-dlp

Linux (apt/Debian/Ubuntu):

sudo apt update && sudo apt install -y yt-dlp

代替方法 (pip - すべてのシステムで動作):

pip3 install yt-dlp
# または
python3 -m pip install yt-dlp

インストールに失敗した場合: ユーザーに手動で yt-dlp をインストールする必要があることを伝え、https://github.com/yt-dlp/yt-dlp#installation からインストール手順を提供します。

利用可能な字幕を確認

ダウンロードを試みる前に常にこれを行います:

youtube-dl --list-subs "YOUTUBE_URL"

これにより、何もダウンロードせずに利用可能な字幕タイプが表示されます。以下のものを確認します:

  • 手動字幕(高品質)
  • 自動生成字幕(通常利用可能)
  • 利用可能な言語

ダウンロード戦略

オプション 1: 手動字幕(推奨)

これを最初に試します - 最高品質、人間が作成:

youtube-dl --write-sub --skip-download --output "OUTPUT_NAME" "YOUTUBE_URL"

オプション 2: 自動生成字幕(フォールバック)

手動字幕が利用できない場合:

youtube-dl --write-auto-sub --skip-download --output "OUTPUT_NAME" "YOUTUBE_URL"

どちらのコマンドも .vtt ファイル(WebVTT 字幕形式)を作成します。

オプション 3: Whisper による文字起こし(最終手段)

手動字幕と自動生成字幕の両方が利用できない場合にのみ使用します。

ステップ 1: ファイルサイズを表示し、確認を求める

# 音声ファイルサイズの推定値を取得
youtube-dl --print "%(filesize,filesize_approx)s" -f "bestaudio" "YOUTUBE_URL"

# または、再生時間を取得して推定
youtube-dl --print "%(duration)s %(title)s" "YOUTUBE_URL"

重要: ファイルサイズをユーザーに表示し、次のように尋ねます:「字幕が利用できません。音声(約 X MB)をダウンロードし、Whisper を使用して文字起こしできます。続行しますか?」

続行する前にユーザーの確認を待ちます。

ステップ 2: Whisper のインストールを確認

command -v whisper

インストールされていない場合、ユーザーに尋ねます:「Whisper がインストールされていません。pip install openai-whisper でインストールしますか(モデルに約1〜3GB必要)?これは一度だけのインストールです。」

インストール前にユーザーの確認を待ちます。

承認された場合にインストール:

pip3 install openai-whisper

ステップ 3: 音声のみをダウンロード

youtube-dl -x --audio-format mp3 --output "audio_%(id)s.%(ext)s" "YOUTUBE_URL"

ステップ 4: Whisper で文字起こし

# 言語を自動検出(推奨)
whisper audio_VIDEO_ID.mp3 --model base --output_format vtt

# または、言語がわかっている場合
whisper audio_VIDEO_ID.mp3 --model base --language en --output_format vtt

モデルオプション(今は base を使用):

  • tiny - 最速、精度は低い(約1GB)
  • base - 良いバランス(約1GB)← これを使用
  • small - より良い精度(約2GB)
  • medium - 非常に良い(約5GB)
  • large - 最高精度(約10GB)

ステップ 5: クリーンアップ

文字起こしが完了したら、ユーザーに尋ねます:「文字起こしが完了しました!音声ファイルを削除して容量を節約しますか?」

はいの場合:

rm audio_VIDEO_ID.mp3

動画情報の取得

動画タイトルの抽出(ファイル名用)

youtube-dl --print "%(title)s" "YOUTUBE_URL"

これを使用して、動画タイトルに基づいた意味のあるファイル名を作成します。ファイルシステム互換性のためにタイトルをクリーニングします:

  • / を - に置き換え
  • 問題を引き起こす可能性のある特殊文字を置き換え
  • サニタイズ版の使用を検討:$(youtube-dl --print "%(title)s" "URL" | tr '/' '-' | tr ':' '-')

後処理

プレーンテキストへの変換(推奨)

YouTube の自動生成 VTT ファイルには、キャプションが重複するタイムスタンプで段階的に表示されるため、重複行が含まれています。プレーンテキストに変換する際は、元の話し順序を維持しながら常に重複を除去します。

python3 -c "
import sys, re
seen = set()
with open('transcript.en.vtt', 'r') as f:
    for line in f:
        line = line.strip()
        if line and not line.startswith('WEBVTT') and not line.startswith('Kind:') and not line.startswith('Language:') and '-->' not in line:
            clean = re.sub('<[^>]*>', '', line)
            clean = clean.replace('&amp;', '&').replace('&gt;', '>').replace('&lt;', '<')
            if clean and clean not in seen:
                print(clean)
                seen.add(clean)
" > transcript.txt

動画タイトルを使った完全な後処理

# 動画タイトルを取得
VIDEO_TITLE=$(youtube-dl --print "%(title)s" "YOUTUBE_URL" | tr '/' '_' | tr ':' '-' | tr '?' '' | tr '"' '')

# VTT ファイルを検索
VTT_FILE=$(ls *.vtt | head -n 1)

# 重複除去して変換
python3 -c "
import sys, re
seen = set()
with open('$VTT_FILE', 'r') as f:
    for line in f:
        line = line.strip()
        if line and not line.startswith('WEBVTT') and not line.startswith('Kind:') and not line.startswith('Language:') and '-->' not in line:
            clean = re.sub('<[^>]*>', '', line)
            clean = clean.replace('&amp;', '&').replace('&gt;', '>').replace('&lt;', '<')
            if clean and clean not in seen:
                print(clean)
                seen.add(clean)
" > "${VIDEO_TITLE}.txt"

echo "✓ 保存先: ${VIDEO_TITLE}.txt"

# VTT ファイルを削除
rm "$VTT_FILE"
echo "✓ 一時的な VTT ファイルを削除しました"

出力形式

  • VTT 形式 (.vtt): タイムスタンプと書式を含み、動画プレーヤーに適しています
  • プレーンテキスト (.txt): テキストコンテンツのみ、読み取りや分析に適しています

ヒント

  • ファイル名は {output_name}.{language_code}.vtt になります(例: transcript.en.vtt)
  • ほとんどの YouTube 動画には自動生成された英語字幕があります
  • 一部の動画には複数の言語オプションがある場合があります
  • 自動字幕が利用できない場合は、代わりに手動字幕用の --write-sub を試してください

完全なワークフロー例

VIDEO_URL="https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# ファイル名用の動画タイトルを取得
VIDEO_TITLE=$(youtube-dl --print "%(title)s" "$VIDEO_URL" | tr '/' '_' | tr ':' '-' | tr '?' '' | tr '"' '')
OUTPUT_NAME="transcript_temp"

# ============================================
# ステップ 1: yt-dlp がインストールされているか確認
# ============================================
if ! command -v yt-dlp &> /dev/null; then
    echo "yt-dlp が見つかりません。インストールを試みます..."
    if command -v brew &> /dev/null; then
        brew install yt-dlp
    elif command -v apt &> /dev/null; then
        sudo apt update && sudo apt install -y yt-dlp
    else
        pip3 install yt-dlp
    fi
fi

# ============================================
# ステップ 2: 利用可能な字幕を一覧表示
# ============================================
echo "利用可能な字幕を確認中..."
youtube-dl --list-subs "$VIDEO_URL"

# ============================================
# ステップ 3: 最初に手動字幕を試す
# ============================================
echo "手動字幕のダウンロードを試みます..."
if youtube-dl --write-sub --skip-download --output "$OUTPUT_NAME" "$VIDEO_URL" 2>/dev/null; then
    echo "✓ 手動字幕のダウンロードが成功しました!"
    ls -lh ${OUTPUT_NAME}.*
else
    # ============================================
    # ステップ 4: 自動生成字幕にフォールバック
    # ============================================
    echo "手動字幕が利用できません。自動生成を試します..."
    if youtube-dl --write-auto-sub --skip-download --output "$OUTPUT_NAME" "$VIDEO_URL" 2>/dev/null; then
        echo "✓ 自動生成字幕のダウンロードが成功しました!"
        ls -lh ${OUTPUT_NAME}.*
    else
        # ============================================
        # ステップ 5: 最終手段 - Whisper による文字起こし
        # ============================================
        echo "⚠ この動画には字幕が利用できません。"

        # ファイルサイズを取得
        FILE_SIZE=$(youtube-dl --print "%(filesize_approx)s" -f "bestaudio" "$VIDEO_URL")
        DURATION=$(youtube-dl --print "%(duration)s" "$VIDEO_URL")
        TITLE=$(youtube-dl --print "%(title)s" "$VIDEO_URL")

        echo "動画: $TITLE"
        echo "再生時間: $((DURATION / 60)) 分"
        echo "音声サイズ: 約 $((FILE_SIZE / 1024 / 1024)) MB"
        echo ""
        echo "Whisper でダウンロードして文字起こししますか? (y/n)"
        read -r RESPONSE

        if [[ "$RESPONSE" =~ ^[Yy]$ ]]; then
            # Whisper を確認
            if ! command -v whisper &> /dev/null; then
                echo "Whisper がインストールされていません。今すぐインストールしますか? (約1〜3GB必要) (y/n)"
                read -r INSTALL_RESPONSE
                if [[ "$INSTALL_RESPONSE" =~ ^[Yy]$ ]]; then
                    pip3 install openai-whisper
                else
                    echo "Whisper なしでは続行できません。終了します。"
                    exit 1
                fi
            fi

            # 音声をダウンロード
            echo "音声をダウンロード中..."
            youtube-dl -x --audio-format mp3 --output "audio_%(id)s.%(ext)s" "$VIDEO_URL"

            # 実際の音声ファイル名を取得
            AUDIO_FILE=$(ls audio_*.mp3 | head -n 1)

            # 文字起こし
            echo "Whisper で文字起こし中(数分かかる場合があります)..."
            whisper "$AUDIO_FILE" --model base --output_format vtt

            # クリーンアップ
            echo "文字起こしが完了しました!音声ファイルを削除しますか? (y/n)"
            read -r CLEANUP_RESPONSE
            if [[ "$CLEANUP_RESPONSE" =~ ^[Yy]$ ]]; then
                rm "$AUDIO_FILE"
                echo "音声ファイルを削除しました。"
            fi

            ls -lh *.vtt
        else
            echo "文字起こしをキャンセルしました。"
            exit 0
        fi
    fi
fi

# ============================================
# ステップ 6: 重複除去して読みやすいプレーンテキストに変換
# ============================================
VTT_FILE=$(ls ${OUTPUT_NAME}*.vtt 2>/dev/null || ls *.vtt | head -n 1)
if [ -f "$VTT_FILE" ]; then
    echo "読みやすい形式に変換し、重複を削除中..."
    python3 -c "
import sys, re
seen = set()
with open('$VTT_FILE', 'r') as f:
    for line in f:
        line = line.strip()
        if line and not line.startswith('WEBVTT') and not line.startswith('Kind:') and not line.startswith('Language:') and '-->' not in line:
            clean = re.sub('<[^>]*>', '', line)
            clean = clean.replace('&amp;', '&').replace('&gt;', '>').replace('&lt;', '<')
            if clean and clean not in seen:
                print(clean)
                seen.add(clean)
" > "${VIDEO_TITLE}.txt"
    echo "✓ 保存先: ${VIDEO_TITLE}.txt"

    # 一時的な VTT ファイルを削除
    rm "$VTT_FILE"
    echo "✓ 一時的な VTT ファイルを削除しました"
else
    echo "⚠ 変換する VTT ファイルが見つかりません"
fi

echo "✓ 完了しました!"

注: この完全なワークフローは、すべてのシナリオを適切なエラーチェックと各決定ポイントでのユーザープロンプトで処理します。

エラーハンドリング

よくある問題と解決策:

1. yt-dlp がインストールされていない

  • システムに基づいて自動インストールを試みる(Homebrew/apt/pip)
  • インストールに失敗した場合は、手動インストールのリンクを提供
  • 続行する前にインストールを確認

2. 字幕が利用できない

  • 最初に利用可能な字幕を一覧表示して確認
  • --write-sub と --write-auto-sub の両方を試す
  • 両方が失敗した場合は、Whisper 文字起こしオプションを提供
  • 音声をダウンロードする前にファイルサイズを表示し、ユーザーの確認を求める

3. 無効な動画またはプライベート動画

  • URL の形式が正しいか確認: https://www.youtube.com/watch?v=VIDEO_ID
  • 一部の動画はプライベート、年齢制限、または地域制限されている場合があります
  • yt-dlp からの具体的なエラーをユーザーに知らせる

4. Whisper のインストールに失敗

  • システム依存関係(ffmpeg、rust)が必要な場合があります
  • フォールバックを提供: 「手動でインストール: pip3 install openai-whisper」
  • 利用可能なディスク容量を確認(モデルはサイズに応じて1〜10GB必要)

5. ダウンロードが中断または失敗

  • インターネット接続を確認
  • 十分なディスク容量を確認
  • SSL の問題が発生した場合は --no-check-certificate を指定して再試行

6. 複数の字幕言語

  • デフォルトでは、yt-dlp は利用可能なすべての言語をダウンロード
  • --sub-langs en で英語のみ指定可能
  • 最初に --list-subs で利用可能なものを一覧表示

ベストプラクティス:

  • ✅ ダウンロードを試みる前に常に利用可能なものを確認(--list-subs)
  • ✅ 各ステップで成功を確認してから次に進む
  • ✅ 大規模なダウンロード(音声ファイル、Whisper モデル)の前にユーザーに確認を求める
  • ✅ 処理後に一時ファイルをクリーンアップ
  • ✅ 各段階で何が起こっているかについて明確なフィードバックを提供
  • ✅ エラーを適切に処理し、役立つメッセージを表示

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

IGTA-Tech/claude-skills-research

Use when localizing apps, using String Catalogs, generating type-safe symbols (Xcode 26+), handling plurals, RTL layouts, locale-aware formatting, or migrating from .strings files - comprehensive i18n patterns for Xcode 15-26

IGTA-Tech/claude-skills-research

Use when implementing SwiftUI animations, understanding VectorArithmetic, using @Animatable macro, choosing between spring and timing curve animations, or debugging animation behavior - comprehensive animation reference from iOS 13 through iOS 26

IGTA-Tech/claude-skills-research

Use when CAAnimation completion handler doesn't fire, spring physics look wrong on device, animation duration mismatches actual time, gesture + animation interaction causes jank, or timing differs between simulator and real hardware - systematic CAAnimation diagnosis with CATransaction patterns, frame rate awareness, and device-specific behavior

IGTA-Tech/claude-skills-research

This skill should be used when comparing two videos to analyze compression results or quality differences. Generates interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Triggers when users mention "compare videos", "video quality", "compression analysis", "before/after compression", or request quality assessment of compressed videos.

IGTA-Tech/claude-skills-research

Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems.

IGTA-Tech/claude-skills-research

Write high-converting landing page copy using proven frameworks like PAS (Problem-Agitate-Solution), AIDA, and StoryBrand. Creates headlines, value propositions, CTAs, and full page sections optimized for conversion. Use when users need landing page copy, sales page content, or marketing website text.

IGTA-Tech/claude-skills-research

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

関連スキル