SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsaudio-transcribe

audio-transcribe

Office & productivity

View repository

Updated 10-16 05:07

About this skill

Audio Transcription Capability

Positioning

Scenario capability skill, comparable to the role of web-access.

  • web-access: gives you internet capability (search/scrape/browse), regardless of what you do with the content
  • audio-transcribe: gives you audio-to-text capability (transcription/speaker diarization), regardless of what you do with the text

The transcription output israw material, not the final state. The caller decides whether this text becomes meeting minutes, weekly report material, a podcast summary, or something else.

Pre-checks

Check environment dependencies before use:

bash ~/.claude/skills/audio-transcribe/scripts/check-deps.sh

When not passed, guide the user to install:

  • ffmpeg: required for audio normalization.brew install ffmpeg
  • dashscope: Alibaba Cloud ASR service.pip install dashscope
  • DASHSCOPE_API_KEY: Alibaba Cloud Bailian API Key
  • HF_TOKEN(required when downloading the pyannote model for the first time): HuggingFace token
  • pyannote.audio(optional): speaker diarization.pip install pyannote.audio, requires accepting the model agreement

Key persistence: store the API Key in ~/.claude/.env, the script loads it automatically, persisting across sessions:

DASHSCOPE_API_KEY=sk-xxx
HF_TOKEN=hf_xxx

Priority: environment variables > ~/.claude/.env. After the pyannote model is cached locally, HF_TOKEN is no longer needed afterward.

Workflow

原始录音（.wav/.m4a/.mp3/.aac/...各种格式和采样率）
    ↓  Stage 1: 标准化
标准化音频（16kHz mono MP3，ASR 最优格式）
    → 存放：/tmp/audio-transcribe/{batch-id}/normalized/
    ↓  Stage 2: 上传 + ASR 转录
原始转录句子（字级时间戳）
    ↓  Stage 3: 说话人分离
带说话人标识的句子
    ↓  Stage 4: 格式化输出
结构化转录文本（.transcript.md + .transcript.json）
    → 存放：调用方指定的 --output-dir，或源文件同目录

The importance of speaker diarization

Speaker diarization is the default behavior, not an option. In multi-person conversation recordings, "who said what" is a core dimension of the information—transcribed text without speaker identification loses attribution relationships, and the quality of downstream processing (meeting minutes, research distillation) drops significantly.

  • Enabled by default: unless the user explicitly specifies --no-diarization(such as monologue, podcast, and other single-speaker scenarios), speaker diarization must be performed during transcription
  • Pre-check: before transcription, confirm that HF_TOKEN is configured (~/.claude/.env or environment variable) and that the pyannote model is cached. If missing, remind the user rather than silently skipping
  • Re-run mechanism: if transcription is already complete but lacks speaker diarization (such as transcription before HF_TOKEN was first configured), use --diarize-only to re-run—reuse the existing ASR result (.transcript.json), run only pyannote speaker diarization and update the output, avoiding repeated consumption of ASR resources

Artifact storage rules

Artifact Nature Storage location
Normalized audio Pure intermediate artifact, discarded after transcription /tmp/audio-transcribe/{batch-id}/
.transcript.md Readable transcribed text, the caller's input --output-dir or the source file's same directory
.transcript.json Raw data (word-level timestamps, etc.), for traceability Same as above

Script API

In the following commands, transcribe.py all refer to python3 ~/.claude/skills/audio-transcribe/scripts/transcribe.py。

Basic usage

# 单文件转录
transcribe.py meeting.m4a

# 批量转录（每个文件独立处理）
transcribe.py file1.m4a file2.wav file3.mp3

# 指定输出目录
transcribe.py *.m4a --output-dir /path/to/transcripts/

# 同一场会议的多段录音（合并时间轴为一份转录）
transcribe.py seg1.wav seg2.wav seg3.wav --merge

# 跳过说话人分离
transcribe.py audio.mp3 --no-diarization

# 补跑说话人分离（复用已有 ASR 转录，只跑 diarization）
transcribe.py audio.m4a --diarize-only --output-dir /path/to/transcripts/

Parameter description

Parameter Description Default value
files Audio file path (multiple supported) Required
--output-dir Transcription file output directory Same directory as the source file
--diarize-only Only rerun speaker diarization (requires an existing .transcript.json) No
--merge Treat multiple files as the same meeting, merge the timeline and output one transcript No (each file is independent)
--no-diarization Skip speaker diarization (not needed for monologues, podcasts, etc.) No
--hf-token HuggingFace token (the HF_TOKEN environment variable can also be used) Environment variable

Output Files

Each audio file (or a group of files in merge mode) produces two files:

{name}.transcript.md — readable transcript text:

# 转录：{原始文件名}

> 时长：42:15 | 说话人：3 | 转录时间：2026-04-10

[00:00] SPEAKER_00: 开场白...
[00:05] SPEAKER_01: 回应...
[01:23] SPEAKER_00: 继续讨论...

{name}.transcript.json — structured raw data:

{
  "source_files": ["meeting.m4a"],
  "duration_seconds": 2535,
  "speakers": ["SPEAKER_00", "SPEAKER_01", "SPEAKER_02"],
  "sentences": [
    {
      "begin_time": 0,
      "end_time": 4500,
      "text": "开场白...",
      "speaker": "SPEAKER_00",
      "emotion": "neutral",
      "words": [...]
    }
  ]
}

Caller Integration Modes

Mode A: Sub-agent batch transcription

Suitable for processing multiple recordings at once (e.g., vc-report receiving 10+ roadshow recordings):

主 Agent
  ├─ 子 Agent 1: transcribe.py file1.m4a --output-dir /tmp/...
  ├─ 子 Agent 2: transcribe.py file2.m4a --output-dir /tmp/...
  └─ ...
  主 Agent 读取所有 .transcript.md，按自己的格式要求加工

Each sub-agent independently processes one file, with no conflicts when run in parallel.

Mode B: Direct invocation

Suitable for a single file or a small number of files:

Agent 直接调用 transcribe.py → 读取 .transcript.md → 加工

Caller Responsibilities

audio-transcribe producesraw transcript text with timestamps and speakers. The caller is responsible for:

  • Deciding the transcript'spurpose(meeting minutes? weekly report material? log?)
  • Deciding thesummary format(investment insights? action items? key decisions?)
  • Deciding thefinal output location(where under the project directory)
  • Mapping speaker IDs (SPEAKER_00)to real identities(if needed)

Technical Details

Audio Normalization Parameters

ffmpeg -i input.wav -ar 16000 -ac 1 -b:a 24k output.mp3 -y
  • -ar 16000: 16kHz, the standard ASR sampling rate (human voice frequencies are below 8kHz, so there is no loss)
  • -ac 1: mono (stereo is meaningless for ASR)
  • -b:a 24k: 24kbps, clear speech, extremely small size (about 5MB for 30 minutes)

ASR Service

Uses qwen3-asr-flash-filetrans(Alibaba Cloud Model Studio), asynchronous long-audio transcription, supporting up to 12 hours.

The transcription process requires an audio URL accessible to the ASR server. Use the DashScope Files API to upload to Alibaba Cloud OSS and obtain a signed URL for ASR to read.

Speaker Diarization

Uses pyannote/speaker-diarization-3.1 (local model), aligned with ASR results by timestamp.

For first use, you need to accept the model agreement on HuggingFace:

After the model is downloaded, it is cached locally and subsequently fully offline. Apple MPS acceleration is available.

Multi-segment File Merging

--merge mode, the time offset of each segment is calculated based on the timestamp in the filename and merged into a unified timeline. Currently supports the DJI Mic 3 filename format (TX02_MIC001_20260319_090113.wav), and other formats are concatenated in file order.

References Index

File When to load
references/troubleshooting.md When encountering ASR/pyannote errors