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*

并行提取内容

转录完成后，同时启动三个提取 Agent：

Agent	角色
TopicExtractor	使用关键词邻近关系和时间分组，按主题归类转录片段。输出：带时间戳的有序主题列表。
ActionExtractor	查找所有行动项。信号词：“will”“should”“needs to”“by [date]”、负责人分配、承诺。输出：包含负责人和截止日期的行动项列表。
DecisionExtractor	查找所有已做出的决策。信号词：“decided”“agreed”“we will”“the plan is”“confirmed”。输出：包含理由的决策列表。

每个 Agent 的提示词都以以下内容开头：

# {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]

等待三个 Agent 全部完成。将输出合并到 Markdown 会议纪要文档中。

批处理模式（多个音频文件）： 对每个文件同时启动完整流程（转录 + 3 个提取 Agent）。所有文件处理完成后，再合并全部输出。

实现方式：

使用 Python 或 bash 搭配 AI 模型（Claude/GPT）进行智能摘要：

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. 自动改进提示词（如果有 prompt-engineer）：

   🔧 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”：使用原版

大模型处理（两种场景均适用）

提示词确定后：

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

仅转录文本（用户拒绝使用大模型）：

💾 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	告知用户；显示适用于其操作系统的安装命令（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，遵循零配置理念。