asr-transcribe-to-text
Transcribes audio or video to speaker-labeled, timestamped text, locally with MLX on Apple Silicon or remotely. Use for 转录 / 录音转文字 / 说话人分离 / 字幕, and also for preparing audio for ASR without transcribing: 转格式, 降采样到 16kHz, merging recorder segments, or compressing and speeding up audio before 飞书妙记 — e…
Install / Use
npx skills add daymade/claude-code-skills --skill asr-transcribe-to-textInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of asr-transcribe-to-text
asr-transcribe-to-text scores 84/100 on our quality scale, 2899th of 4,700 Development & Engineering skills we index.
Its SKILL.md is 52 KB long, well organised into 30 sections with 41 code examples: long enough that it reads more like full documentation than a focused instruction file, which agents can find harder to follow.
With 1,426 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so asr-transcribe-to-text is actively maintained.
- Our last check on 2026-10-14 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-03. Automated pattern scan on 2026-10-03. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
asr-transcribe-to-text compared with similar skills
All 4 of these similar skills score higher than asr-transcribe-to-text; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| asr-transcribe-to-text (this skill)by daymade | 84 | 1.4k | 53d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install asr-transcribe-to-text?
- Run
npx skills add daymade/claude-code-skills --skill asr-transcribe-to-text. The install tabs above show the steps for each supported agent. - Which AI agents does asr-transcribe-to-text work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is asr-transcribe-to-text safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is asr-transcribe-to-text still maintained?
- The repository was last updated about 2 months ago, so asr-transcribe-to-text is actively maintained.
Skill content
View source on GitHubname: asr-transcribe-to-text description: >- Transcribes audio or video to speaker-labeled, timestamped text, locally with MLX on Apple Silicon or remotely. Use for 转录 / 录音转文字 / 说话人分离 / 字幕, and also for preparing audio for ASR without transcribing: 转格式, 降采样到 16kHz, merging recorder segments, or compressing and speeding up audio before 飞书妙记 — even when it looks like a one-line ffmpeg job. argument-hint: "[audio-or-video-file-path-or-url ...]"
ASR Transcribe to Text
Transcribe audio/video to speaker-labeled text. Local execution has two explicit routes. Long or unattended recordings use checkpointed whisper.cpp + Silero VAD blocks, then late-fuse pyannote speakers. Short/medium recordings may use the Qwen3-ASR + mlx-whisper alignment route. Neither route cuts ASR input at diarization turns; speaker attribution happens after continuous-context ASR.
Route before ASR: the transcript is the result, not the run
Before starting transcription, check the owning project's transcript catalog, external source index, and declared prior-work carriers for an existing canonical transcript using source ID, date, title, and entity terms. A verified human-reviewed/current transcript ends the task unless the user explicitly asked for a new independent comparison. Raw audio existing is not a reason to regenerate text that already exists.
When no canonical transcript exists:
- For ordinary meeting/DJI recordings where cloud processing is allowed, use Feishu Minutes as the normal primary route (preprocess to a small M4A first).
- Use local ASR when the user requires offline/privacy handling, Feishu is
unavailable or failed, or the task explicitly needs an independent quality
comparison.
2b. For a second, independent speaker timeline, use StepFun's async file
endpoint via the
stepfun-asrskill'sasr_file.py. It is the only vendor diarization route here that does not share code or models with local pyannote, so agreement between the two is real corroboration rather than one tool agreeing with itself. Measured 2026-09-19 on a 10-minute film: both split the key turn identically, while Feishu Minutes mis-attributed it. The constraint is that it fetches a public URL — base64 is rejected — so it needs staging (seealiyun-multi-account.md); reach for it when an attribution is load-bearing, not for routine transcripts. - For non-meeting media or an explicit local/remote ASR request, choose the execution location by the audio-location rule below.
Do not run local ASR merely to make a two-route process look complete.
| Mode | When | Speed | Cost | |------|------|-------|------| | Local MLX | macOS Apple Silicon | 15-27x realtime | Free | | Remote API | Any platform, or when local unavailable | Depends on GPU | API/self-hosted |
Choosing between them is usually not about speed — it's about where the audio already is. A remote GPU can be several times faster (a 4090 running vLLM measured ~61x realtime against ~15x for local MLX), but that gap is small change next to moving the files: transcription output is text, and text is ~10,000× smaller than the audio it came from (18.5 h of speech ≈ 330 K characters ≈ 1 MB, from ~2.6 GB of WAV). So:
Transcribe where the audio already lives, and move only the transcript.
Pulling a few hundred MB across a slow link to reach a faster GPU routinely costs more
wall-clock than the entire transcription — measured once at 63 KB/s, which is over two
hours for 500 MB, to save minutes of compute. If the recording is already on the remote
box (it was recorded there, downloaded there, or lives in a share mounted there), run the
ASR there and bring back the .txt.
Configuration persists in ${CLAUDE_PLUGIN_DATA}/config.json.
Speaker labels are the default. Every run produces
[start-end] SPEAKER_xx: text
- CSV. Plain-text-only output is the opt-out (
--no-diarization) for monologues, podcasts, or when you just want a summary — see Step 3. It also drops every timestamp: the plain-text path returns the session text and nothing else. A monologue that needs line-level timestamps (subtitles, jump-to-moment archives) runs the full pipeline and ignores theSPEAKER_00labels.One-time setup for diarization: pyannote is a gated HuggingFace model — it needs a token once (
## Speaker Diarization & Identificationbelow). First run without it FAILS with setup steps; after setup, full capability is permanent and auto-detected.
Step 0: Detect Platform and Load Config
cat "${CLAUDE_PLUGIN_DATA}/config.json" 2>/dev/null
If config exists, read values and proceed to Step 1.
If config does not exist, auto-detect platform first:
python3 -c "
import sys, platform
is_mac_arm = sys.platform == 'darwin' and platform.machine() in ('arm64', 'aarch64')
print(f'Platform: {sys.platform} {platform.machine()}')
print(f'Apple Silicon: {is_mac_arm}')
if is_mac_arm:
print('RECOMMEND: local-mlx')
else:
print('RECOMMEND: remote-api')
"
Then use AskUserQuestion with platform-aware defaults:
For macOS Apple Silicon (recommended: local):
ASR setup — your Mac has Apple Silicon, so local transcription is recommended.
Q1: Transcription mode?
A) Local MLX — runs on your Mac's GPU, no API key needed, 15-27x realtime (Recommended)
B) Remote API — send audio to a server (vLLM, Tailscale workstation, etc.)
Q2: Does your network have an HTTP proxy that might intercept traffic?
A) Yes — bypass proxy for ASR traffic (Recommended if using Shadowrocket/Clash)
B) No — direct connection
For other platforms (recommended: remote):
ASR setup — local MLX requires macOS Apple Silicon. Using remote API mode.
Q1: ASR Endpoint URL?
A) https://asr.example.com/v1/audio/transcriptions (Self-hosted remote ASR)
B) http://localhost:8002/v1/audio/transcriptions (Local ASR server)
C) Custom URL
Q2: Proxy bypass needed?
A) Yes (Recommended for Shadowrocket/Clash/corporate proxy)
B) No
Save config:
mkdir -p "${CLAUDE_PLUGIN_DATA}"
python3 -c "
import json
config = {
'mode': 'MODE', # 'local-mlx' or 'remote-api'
'model': 'MODEL_ID', # local: 'mlx-community/Qwen3-ASR-1.7B-8bit', remote: 'Qwen/Qwen3-ASR-1.7B'
'max_tokens': 8192, # local only; PER 20-minute chunk, not per recording
'endpoint': 'URL', # remote only
'noproxy': True,
'max_timeout': 900 # remote only
# 'diarization_declined': True # set only after the user explicitly declines
# the pyannote setup in Step 3 — every run then warns + goes plain-text
# until an HF token appears (auto-detected)
}
with open('${CLAUDE_PLUGIN_DATA}/config.json', 'w') as f:
json.dump(config, f, indent=2)
print('Config saved.')
"
Step 1: Resolve Input
Accept local files, direct media URLs, or web/podcast episode pages.
- Web or podcast page URL: inspect the page for an existing transcript first. Use an official/platform transcript only when it is directly accessible to the user's account. If the transcript endpoint requires a login token and none is available, say that clearly and fall back to ASR from the audio URL.
- Local file, direct media URL, or page URL fallback: run the bundled resolver. It extracts media from common page metadata (
og:audio, media tags, JSON-LD, RSS-style enclosure links), downloads URLs with atomic temp-file replacement, verifies remoteContent-Lengthwhen present, computes SHA-256, and validates the result withffprobe.
uv run ${CLAUDE_SKILL_DIR}/scripts/resolve_media_input.py \
INPUT_FILE_OR_URL [INPUT_FILE_OR_URL2 ...] \
--output-dir OUTPUT_DIR \
--manifest OUTPUT_DIR/media_manifest.json
For suspicious or high-value downloads, add --decode-check to make ffmpeg decode the whole file before transcription:
uv run ${CLAUDE_SKILL_DIR}/scripts/resolve_media_input.py \
"https://www.xiaoyuzhoufm.com/episode/EPISODE_ID" \
--output-dir OUTPUT_DIR \
--manifest OUTPUT_DIR/media_manifest.json \
--decode-check
Expected output:
Downloaded ... bytes in ...s -> OUTPUT_DIR/episode-title.m4a
OUTPUT_DIR/episode-title.m4a
Use the printed local path as INPUT_AUDIO in later steps. If your runtime shows the literal ${CLAUDE_SKILL_DIR} instead of a substituted path, resolve the skill directory per the Troubleshooting entry at the bottom of this document.
For third-party public podcasts or copyrighted media, save the transcript as a local file for the user's personal analysis. Do not paste a full long transcript into chat; provide a path, previews, summaries, or short excerpts instead.
Step 2: Extract Audio (if input is video)
For video files (mp4, mov, mkv, avi, webm), extract as 16kHz mono WAV:
ffmpeg -i INPUT_VIDEO -vn -acodec pcm_s16le -ar 16000 -ac 1 OUTPUT.wav -y
Audio files (wav, mp3, m4a, flac, ogg) can be used directly. Get duration:
ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 INPUT_FILE
Cleanup: After transcription succeeds, delete extracted WAV files to save disk space.
Preprocess: Merge Segments & Shrink Metered Uploads (optional)
Run this BEFORE transcription when either applies:
- The recording is a multi-segment dump — body mics and field recorders split
sessions into fixed-length files (e.g.
TX02_MIC024_....wav,TX02_MIC025_....wav;TX01/TX02= DJI MIC MINI 2S internal recording — device roster and the recorder→Feishu-Minutes paths: the meeting-ingest skill'smeeting-ingest/references/architecture.md§①-L0). Merge them once to preserve session order; the explicit long-audio runner (Step 3 Path L) then owns stable source-time blocks. Transcribing device segments separately throws away cross-segment context inside those chunks. - The audio goes to a metered ASR (Feishu Minutes, any per-minute quota) — a pitch-PRESERVED speedup cuts billed duration directly, and modern ASR does not care: 1.3x was user-verified on Feishu Minutes (2026-07-16) with no perceptible recognition difference, and public Whisper benchmarks show no sharp WER drop until 2.0x (≤1.5x = safe zone, ~3% WER increase at 1.5x; >2x unusable).
Use the bundled script — it merges, normalizes to 16 kHz mono, optionally speeds up, and verifies its own output instead of trusting the ffmpeg exit code:
uv run ${CLAUDE_SKILL_DIR}/scripts/prepare_asr_input.py SEG1.wav SEG2.wav -o merged.wav # merge only
uv run ${CLAUDE_SKILL_DIR}/scripts/prepare_asr_input.py SEG*.wav -o upload.m4a --speed 1.3 # merge + quota-saving speedup
Expected output:
Merge order:
1. SEG1.wav [pcm_s24le 48000Hz ch=1 1800.14s]
2. SEG2.wav [pcm_s24le 48000Hz ch=1 1800.15s]
[OK] duration: 4946.19s vs expected 4946.18s (delta +0.00s)
[OK] boundary 1 @ 1384.7s: max_volume -15.5 dB
[info] overall: mean_volume -38.3 dB, max_volume 0.0 dB
Wrote upload.m4a
-
Segments sort by the
YYYYMMDD_HHMMSStimestamp embedded in their filenames when every file has one (recorder dumps do); otherwise the given order is kept with a note — eyeball the printed merge order before transcribing. -
Self-verification: output duration must equal Σsegments ÷ speed (±1.5 s, hard FAIL otherwise); each splice gets a 10 s volume spot-check (dead air at a boundary = wrong order or a missing segment); overall loudness prints for comparison with the source.
-
Speedup must be
atempo-style pitch-preserved stretch — never sample-rate trickery, which shifts pitch and breaks both ASR accuracy and diarization voiceprints. -
Pick the output format by destination — codec follows the file extension:
| Destination | Format | Why | |---|---|---| | Local MLX pipeline (Path A) |
.wavor.m4a| Both feed the pipeline directly (m4a verified 2026-07-18: a 3-min slice transcribed cleanly). M4A is ~5x smaller — 324 MB WAV → 63 MB M4A on a 2
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
