audio-transcriber

目的

このスキルは、音声をテキストに文字起こしし、プロフェッショナルな Markdown 形式で出力する作業を自動化します。話者、タイムスタンプ、言語、ファイルサイズ、長さなどの豊富な技術メタデータを抽出し、構造化された議事録とエグゼクティブサマリーを生成します。設定不要で Faster-Whisper または Whisper を使用し、ハードコードされたパスや API キーなしで、あらゆるプロジェクトで利用できます。

Plaud のようなツールに着想を得たこのスキルは、録音された音声を実用的なドキュメントに変換するため、会議、インタビュー、講義、コンテンツ分析に最適です。

使用する場面

次の場合にこのスキルを呼び出してください。

• ユーザーが音声／動画ファイルをテキストに文字起こししたい場合
• ユーザーが録音から議事録を自動生成したい場合
• ユーザーが会話の話者識別（ダイアライゼーション）を必要としている場合
• ユーザーが字幕（SRT、VTT 形式）を必要としている場合
• ユーザーが長時間の音声コンテンツのエグゼクティブサマリーを必要としている場合
• ユーザーが「この音声を文字起こしして」「音声をテキストに変換して」「録音から議事録を生成して」などの依頼をした場合
• ユーザーが一般的な形式の音声ファイル（MP3、WAV、M4A、OGG、FLAC、WEBM）を持っている場合

ワークフロー

ステップ 0：検出（文字起こしツールの自動検出）

目的： ユーザーの設定なしで利用可能な文字起こしエンジンを特定します。

アクション：

検出コマンドを実行し、インストール済みのツールを確認します。

# Check for Faster-Whisper (preferred - 4-5x faster)
if python3 -c "import faster_whisper" 2>/dev/null; then
    TRANSCRIBER="faster-whisper"
    echo "✅ Faster-Whisper detected (optimized)"
# Fallback to original Whisper
elif python3 -c "import whisper" 2>/dev/null; then
    TRANSCRIBER="whisper"
    echo "✅ OpenAI Whisper detected"
else
    TRANSCRIBER="none"
    echo "⚠️  No transcription tool found"
fi

# Check for ffmpeg (audio format conversion)
if command -v ffmpeg &>/dev/null; then
    echo "✅ ffmpeg available (format conversion enabled)"
else
    echo "ℹ️  ffmpeg not found (limited format support)"
fi

文字起こしツールが見つからない場合：

付属のスクリプトを使用した自動インストールを提案します。

echo "⚠️  No transcription tool found"
echo ""
echo "🔧 Auto-install dependencies? (Recommended)"
read -p "Run installation script? [Y/n]: " AUTO_INSTALL

if [[ ! "$AUTO_INSTALL" =~ ^[Nn] ]]; then
    # Get skill directory (works for both repo and symlinked installations)
    SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
    
    # Run installation script
    if [[ -f "$SKILL_DIR/scripts/install-requirements.sh" ]]; then
        bash "$SKILL_DIR/scripts/install-requirements.sh"
    else
        echo "❌ Installation script not found"
        echo ""
        echo "📦 Manual installation:"
        echo "  pip install faster-whisper  # Recommended"
        echo "  pip install openai-whisper  # Alternative"
        echo "  brew install ffmpeg         # Optional (macOS)"
        exit 1
    fi
    
    # Verify installation succeeded
    if python3 -c "import faster_whisper" 2>/dev/null || python3 -c "import whisper" 2>/dev/null; then
        echo "✅ Installation successful! Proceeding with transcription..."
    else
        echo "❌ Installation failed. Please install manually."
        exit 1
    fi
else
    echo ""
    echo "📦 Manual installation required:"
    echo ""
    echo "Recommended (fastest):"
    echo "  pip install faster-whisper"
    echo ""
    echo "Alternative (original):"
    echo "  pip install openai-whisper"
    echo ""
    echo "Optional (format conversion):"
    echo "  brew install ffmpeg  # macOS"
    echo "  apt install ffmpeg   # Linux"
    echo ""
    exit 1
fi

これにより、ユーザーは確認ひとつで依存関係をインストールするか、必要に応じて手動インストールを選択できます。

文字起こしツールが見つかった場合：

ステップ 0b（CLI の検出）に進みます。

ステップ 1：音声ファイルの検証

目的： ファイルの存在と形式を確認し、メタデータを抽出します。

アクション：

1. ユーザーからファイルパスまたは URL を受け取ります。

   • ローカルファイル：meeting.mp3
   • URL：https://example.com/audio.mp3（一時ディレクトリにダウンロード）

2. ファイルの存在を確認します。

if [[ ! -f "$AUDIO_FILE" ]]; then
    echo "❌ File not found: $AUDIO_FILE"
    exit 1
fi

3. ffprobe またはファイルユーティリティを使ってメタデータを抽出します。

# Get file size
FILE_SIZE=$(du -h "$AUDIO_FILE" | cut -f1)

# Get duration and format using ffprobe
DURATION=$(ffprobe -v error -show_entries format=duration \
    -of default=noprint_wrappers=1:nokey=1 "$AUDIO_FILE" 2>/dev/null)
FORMAT=$(ffprobe -v error -select_streams a:0 -show_entries \
    stream=codec_name -of default=noprint_wrappers=1:nokey=1 "$AUDIO_FILE" 2>/dev/null)

# Convert duration to HH:MM:SS
DURATION_HMS=$(date -u -r "$DURATION" +%H:%M:%S 2>/dev/null || echo "Unknown")

4. ファイルサイズを確認します（クラウド API に対して大きい場合は警告します）。

SIZE_MB=$(du -m "$AUDIO_FILE" | cut -f1)
if [[ $SIZE_MB -gt 25 ]]; then
    echo "⚠️  Large file ($FILE_SIZE) - processing may take several minutes"
fi

5. 形式を検証します（対応形式：MP3、WAV、M4A、OGG、FLAC、WEBM）。

EXTENSION="${AUDIO_FILE##*.}"
SUPPORTED_FORMATS=("mp3" "wav" "m4a" "ogg" "flac" "webm" "mp4")

if [[ ! " ${SUPPORTED_FORMATS[@]} " =~ " ${EXTENSION,,} " ]]; then
    echo "⚠️  Unsupported format: $EXTENSION"
    if command -v ffmpeg &>/dev/null; then
        echo "🔄 Converting to WAV..."
        ffmpeg -i "$AUDIO_FILE" -ar 16000 "${AUDIO_FILE%.*}.wav" -y
        AUDIO_FILE="${AUDIO_FILE%.*}.wav"
    else
        echo "❌ Install ffmpeg to convert formats: brew install ffmpeg"
        exit 1
    fi
fi

ステップ 3：Markdown 出力の生成

目的： メタデータ、文字起こし、議事録、サマリーを含む構造化された Markdown を作成します。

出力テンプレート：

# Audio Transcription Report

## 📊 Metadata

| Field | Value |
|-------|-------|
| **File Name** | {filename} |
| **File Size** | {file_size} |
| **Duration** | {duration_hms} |
| **Language** | {language} ({language_code}) |
| **Processed Date** | {process_date} |
| **Speakers Identified** | {num_speakers} |
| **Transcription Engine** | {engine} (model: {model}) |


## 📋 Meeting Minutes

### Participants
- {speaker_1}
- {speaker_2}
- ...

### Topics Discussed
1. **{topic_1}** ({timestamp})
   - {key_point_1}
   - {key_point_2}

2. **{topic_2}** ({timestamp})
   - {key_point_1}

### Decisions Made
- ✅ {decision_1}
- ✅ {decision_2}

### Action Items
- [ ] **{action_1}** - Assigned to: {speaker} - Due: {date_if_mentioned}
- [ ] **{action_2}** - Assigned to: {speaker}


*Generated by audio-transcriber skill v1.0.0*  
*Transcription engine: {engine} | Processing time: {elapsed_time}s*

コンテンツ抽出の並列処理

文字起こしが完了したら、3 つの抽出エージェントを同時に起動します。

エージェント	役割
TopicExtractor	キーワードの近接性と時間的なまとまりを使って、文字起こしのセグメントをトピックごとに分類します。出力：タイムスタンプ付きのトピック一覧。
ActionExtractor	すべてのアクション項目を抽出します。手がかり：「will」「should」「needs to」「by [date]」、担当者の割り当て、確約。出力：担当者と期限を含むアクション一覧。
DecisionExtractor	行われたすべての決定を抽出します。手がかり：「decided」「agreed」「we will」「the plan is」「confirmed」。出力：理由を含む決定事項一覧。

各エージェントへのプロンプトは、次の内容で始めます。

# {AgentName} — Transcript Analysis Agent
Role: Analyze the transcript below and extract ONLY {topic/action items/decisions}. Return structured list with timestamps.
Input: [full transcript text with speaker labels]

3 つすべての処理が完了するまで待ちます。出力を統合し、Markdown の議事録ドキュメントに反映します。

バッチモード（複数の音声ファイル）： ファイルごとに、パイプライン全体（文字起こしと 3 つの抽出エージェント）を同時に起動します。すべてのファイルの処理が完了した後、出力を統合します。

実装：

インテリジェントな要約には、AI モデル（Claude/GPT）とともに Python または bash を使用します。

def generate_meeting_minutes(segments):
    """Extract topics, decisions, action items from transcription."""
    
    # Group segments by topic (simple clustering by timestamps)
    topics = cluster_by_topic(segments)
    
    # Identify action items (keywords: "should", "will", "need to", "action")
    action_items = extract_action_items(segments)
    
    # Identify decisions (keywords: "decided", "agreed", "approved")
    decisions = extract_decisions(segments)
    
    return {
        "topics": topics,
        "decisions": decisions,
        "action_items": action_items
    }

def generate_summary(segments, max_paragraphs=5):
    """Create executive summary using AI (Claude/GPT via API or local model)."""
    
    full_text = " ".join([s["text"] for s in segments])
    
    # Use Chain of Density approach (from prompt-engineer frameworks)
    summary_prompt = f"""
    Summarize the following transcription in {max_paragraphs} concise paragraphs.
    Focus on key topics, decisions, and action items.
    
    Transcription:
    {full_text}
    """
    
    # Call AI model (placeholder - user can integrate Claude API or use local model)
    summary = call_ai_model(summary_prompt)
    
    return summary

出力ファイル名：

# v1.1.0: Use timestamp to avoid overwriting
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
TRANSCRIPT_FILE="transcript-${TIMESTAMP}.md"
SUMMARY_FILE="summary-${TIMESTAMP}.md"

echo "$TRANSCRIPT_CONTENT" > "$TRANSCRIPT_FILE"
echo "✅ Transcript saved: $TRANSCRIPT_FILE"

if [[ -n "$SUMMARY_CONTENT" ]]; then
    echo "$SUMMARY_CONTENT" > "$SUMMARY_FILE"
    echo "✅ Summary saved: $SUMMARY_FILE"
fi

シナリオ A：ユーザーがカスタムプロンプトを指定した場合

ワークフロー：

1. ユーザーのプロンプトを表示します。

   📝 User-provided prompt:
   ┌──────────────────────────────────┐
   │ [User's prompt preview]          │
   └──────────────────────────────────┘
   

2. 利用可能な場合は、プロンプトエンジニアを使って自動的に改善します。

   🔧 Improving prompt with prompt-engineer...
   [Invokes: gh copilot -p "improve this prompt: {user_prompt}"]
   

3. 両方のバージョンを表示します。

   ✨ Improved version:
   ┌──────────────────────────────────┐
   │ Role: You are a documentarian... │
   │ Instructions: Transform...       │
   │ Steps: 1) ... 2) ...             │
   │ End Goal: ...                    │
   └──────────────────────────────────┘
   
   📝 Original version:
   ┌──────────────────────────────────┐
   │ [User's original prompt]         │
   └──────────────────────────────────┘
   

4. どちらを使用するか尋ねます。

   💡 Use improved version? [y/n] (default: y):
   

5. 選択されたプロンプトで処理します。

   • 「s」の場合：改善版を使用
   • 「n」の場合：元のプロンプトを使用

LLM による処理（両方のシナリオ）

プロンプトが確定したら：

from rich.progress import Progress, SpinnerColumn, TextColumn

def process_with_llm(transcript, prompt, cli_tool='claude'):
    full_prompt = f"{prompt}\n\n---\n\nTranscription:\n\n{transcript}"

    with Progress(
        SpinnerColumn(),
        TextColumn("[progress.description]{task.description}"),
        transient=True
    ) as progress:
        progress.add_task(
            description=f"🤖 Processing with {cli_tool}...",
            total=None
        )
        
        if cli_tool == 'claude':
            result = subprocess.run(
                ['claude', '-'],
                input=full_prompt,
                capture_output=True,
                text=True,
                timeout=300  # 5 minutes
            )
        elif cli_tool == 'gh-copilot':
            result = subprocess.run(
                ['gh', 'copilot', 'suggest', '-t', 'shell', full_prompt],
                capture_output=True,
                text=True,
                timeout=300
            )
    
    if result.returncode == 0:
        return result.stdout.strip()
    else:
        return None

進行状況の出力：

🤖 Processing with claude... ⠋
[After completion:]
✅ Summary generated successfully!

最終出力

成功（両方のファイル）：

💾 Saving files...

✅ Files created:
  - transcript-20260203-023045.md  (raw transcript)
  - summary-20260203-023045.md     (processed with LLM)

🧹 Removed temporary files: metadata.json, transcription.json

✅ Done! Total time: 3m 45s

文字起こしのみ（ユーザーが LLM の使用を辞退した場合）：

💾 Saving files...

✅ File created:
  - transcript-20260203-023045.md

ℹ️  Summary not generated (LLM processing declined by user)

🧹 Removed temporary files: metadata.json, transcription.json

✅ Done!

ステップ 5：結果の概要を表示する

目的： 完了状況と次のステップを示します。

出力：

echo ""
echo "✅ Transcription Complete!"
echo ""
echo "📊 Results:"
echo "  File: $OUTPUT_FILE"
echo "  Language: $LANGUAGE"
echo "  Duration: $DURATION_HMS"
echo "  Speakers: $NUM_SPEAKERS"
echo "  Words: $WORD_COUNT"
echo "  Processing time: ${ELAPSED_TIME}s"
echo ""
echo "📝 Generated:"
echo "  - $OUTPUT_FILE (Markdown report)"
[if alternative formats:]
echo "  - ${OUTPUT_FILE%.*}.srt (Subtitles)"
echo "  - ${OUTPUT_FILE%.*}.json (Structured data)"
echo ""
echo "🎯 Next steps:"
echo "  1. Review meeting minutes and action items"
echo "  2. Share report with participants"
echo "  3. Track action items to completion"

エラー処理

エラー	考えられる原因	対応
文字起こしツールが見つからない	faster-whisper と openai-whisper がインストールされていない	pip install faster-whisper で自動インストールするか確認し、手動での手順を示します
サポートされていない音声形式	ファイル拡張子がサポート対象の一覧（MP3/WAV/M4A/OGG/FLAC/WEBM）に含まれていない	ffmpeg が利用可能な場合は自動で変換し、利用できない場合は ffmpeg のインストールを促します
ファイルが見つからない	パスが間違っているか、ファイルが移動されている	正確なパスのエラーを表示し、ユーザーに確認のうえ正しいパスを指定するよう依頼します
ファイルが大きすぎる（>1 GB）	録音時間が非常に長い	処理時間について警告し、ffmpeg でファイルを分割するか確認します
文字起こしの品質が低い／判読できない	音質が悪い、背景ノイズがある、または話者が複数いる	信頼度に関する問題を報告し、録音し直すか、より良い音声ソースを使うよう提案します
ffmpeg が見つからない	システムに ffmpeg がインストールされていない	ユーザーに通知し、使用 OS に応じたインストールコマンド（brew/apt/choco）を示します
LLM の処理がタイムアウトした	AI モデルが非常に長い文字起こしの処理に時間をかけすぎた	文字起こしをより小さなセクションに分割し、入力を小さくして再試行します
アクセスが拒否された	ファイルがロックされているか、昇格されたアクセス権が必要	ファイルのアクセス許可を確認するか、アクセス可能な場所にファイルをコピーするよう依頼します

使用例

例 1：基本的な文字起こし

ユーザー入力：

copilot> transcribe audio to markdown: meeting-2026-02-02.mp3

スキルの出力：

✅ Faster-Whisper detected (optimized)
✅ ffmpeg available (format conversion enabled)

📂 File: meeting-2026-02-02.mp3
📊 Size: 12.3 MB
⏱️  Duration: 00:45:32

🎙️  Processing...
[████████████████████] 100%

✅ Language detected: Portuguese (pt-BR)
👥 Speakers identified: 4
📝 Generating Markdown output...

✅ Transcription Complete!

📊 Results:
  File: meeting-2026-02-02.md
  Language: pt-BR
  Duration: 00:45:32
  Speakers: 4
  Words: 6,842
  Processing time: 127s

📝 Generated:
  - meeting-2026-02-02.md (Markdown report)

🎯 Next steps:
  1. Review meeting minutes and action items
  2. Share report with participants
  3. Track action items to completion

例 3：バッチ処理

ユーザー入力：

copilot> transcribe these audio files: recordings/*.mp3

スキルの出力：

📦 Batch mode: 5 files found
  1. team-standup.mp3
  2. client-call.mp3
  3. brainstorm-session.mp3
  4. product-demo.mp3
  5. retrospective.mp3

🎙️  Processing batch...

[1/5] team-standup.mp3 ✅ (2m 34s)
[2/5] client-call.mp3 ✅ (15m 12s)
[3/5] brainstorm-session.mp3 ✅ (8m 47s)
[4/5] product-demo.mp3 ✅ (22m 03s)
[5/5] retrospective.mp3 ✅ (11m 28s)

✅ Batch Complete!
📝 Generated 5 Markdown reports
⏱️  Total processing time: 6m 15s

例 5：大容量ファイルの警告

ユーザー入力：

copilot> transcribe audio to markdown: conference-keynote.mp3

スキルの出力：

✅ Faster-Whisper detected (optimized)

📂 File: conference-keynote.mp3
📊 Size: 87.2 MB
⏱️  Duration: 02:15:47
⚠️  Large file (87.2 MB) - processing may take several minutes

Continue? [Y/n]:

ユーザー： Y

🎙️  Processing... (this may take 10-15 minutes)
[████░░░░░░░░░░░░░░░░] 20% - Estimated time remaining: 12m

このスキルはプラットフォームに依存せず、GitHub Copilot CLI を利用できるあらゆるターミナル環境で動作します。特定のプロジェクト設定や外部 API に依存せず、ゼロコンフィギュレーションの理念に従っています。