acestep-lyrics-transcription

歌词转录技能

通过 OpenAI Whisper 或 ElevenLabs Scribe API，将音频文件转录为带时间戳的歌词（LRC/SRT/JSON）。

API 密钥配置指南

转录前，必须检查用户是否已配置 API 密钥。 运行以下命令进行检查：

cd "{project_root}/{.claude or .codex}/skills/acestep-lyrics-transcription/" && bash ./scripts/acestep-lyrics-transcription.sh config --check-key

此命令只会报告当前使用的服务商的 API 密钥是否已设置或为空，不会打印密钥的实际值。切勿读取或显示用户的 API 密钥内容。 请勿对密钥字段使用 config --get，也不要直接读取 config.json。config --list 命令是安全的——它会自动在输出中将 API 密钥屏蔽为 ***。

如果命令报告密钥为空，必须停止操作，并指导用户完成配置后再继续。没有有效密钥时请勿尝试转录，否则操作会失败。

使用 AskUserQuestion 询问用户是否要提供 API 密钥，并提供以下选项和说明：

1. 告知用户当前使用的服务商（openai 或 elevenlabs）以及其 API 密钥尚未配置，并说明没有密钥就无法继续转录。
2. 清楚说明如何获取密钥：
   • OpenAI：访问 https://platform.openai.com/api-keys 获取 API 密钥——需要拥有已启用计费功能的 OpenAI 账户。Whisper API 的费用约为每分钟 $0.006。
   • ElevenLabs：访问 https://elevenlabs.io/app/settings/api-keys 获取 API 密钥——需要 ElevenLabs 账户。免费套餐包含有限额度。
3. 同时提供切换到另一家服务商的选项，供已有该服务商密钥的用户选择。
4. 用户提供密钥后，使用以下命令进行配置：

   cd "{project_root}/{.claude or .codex}/skills/acestep-lyrics-transcription/" && bash ./scripts/acestep-lyrics-transcription.sh config --set <provider>.api_key <KEY>
   

5. 如果用户希望切换服务商，也要运行：

   cd "{project_root}/{.claude or .codex}/skills/acestep-lyrics-transcription/" && bash ./scripts/acestep-lyrics-transcription.sh config --set provider <provider_name>
   

6. 配置完成后，重新运行 config --check-key，确认密钥已设置后再继续。

如果 API 密钥已经配置，直接开始转录，无需询问。

快速入门

# 1. cd to this skill's directory
cd {project_root}/{.claude or .codex}/skills/acestep-lyrics-transcription/

# 2. Configure API key (choose one)
./scripts/acestep-lyrics-transcription.sh config --set openai.api_key sk-...
# or
./scripts/acestep-lyrics-transcription.sh config --set elevenlabs.api_key ...
./scripts/acestep-lyrics-transcription.sh config --set provider elevenlabs

# 3. Transcribe
./scripts/acestep-lyrics-transcription.sh transcribe --audio /path/to/song.mp3 --language zh

# 4. Output saved to: {project_root}/acestep_output/<filename>.lrc

前置条件

• curl、jq、python3（或 python）
• OpenAI 或 ElevenLabs 的 API 密钥

脚本用法

./scripts/acestep-lyrics-transcription.sh transcribe --audio <file> [options]

Options:
  -a, --audio      Audio file path (required)
  -l, --language   Language code (zh, en, ja, etc.)
  -f, --format     Output format: lrc, srt, json (default: lrc)
  -p, --provider   API provider: openai, elevenlabs (overrides config)
  -o, --output     Output file path (default: acestep_output/<filename>.lrc)

转录后的歌词校正（必须执行）

重要：转录完成后，在将 LRC 文件用于 MV 渲染前，必须手动校正。转录模型在处理演唱歌词时经常会出错：

• 专有名词：“ACE-Step” → “AC step”，“Spotify” → “spot a fly”
• 发音相似的词：“arrives” → “eyes”，“open source” → “open sores”
• 合并或拆分的词：“lighting up” → “lightin' nup”

校正流程

1. 使用 Read 工具读取转录得到的 LRC 文件
2. 从 ACE-Step 输出 JSON 文件中读取原始歌词
3. 将原始歌词作为整体参考：请勿尝试逐行对齐——转录结果与原文的分行方式经常不同，可能会拆分、合并或重新排列歌词行。应通读原始歌词以了解正确措辞，然后逐行检查 LRC，根据对原始歌词的理解修正所有识别错误。
4. 修正转录错误：将识别错误的词替换为正确的原词，并保留时间戳
5. 使用 Write 工具将校正后的 LRC 写回文件

校正内容

• 将识别错误的词替换为对应的正确原词
• 保持所有 [MM:SS.cc] 时间戳完全不变（转录得到的时间戳是准确的）
• 请勿添加 [Verse] 或 [Chorus] 等结构标签——LRC 中只能包含带时间戳的文本行

示例

转录结果（错误）：

[00:46.96]AC step alive,
[00:50.80]one point five eyes.

原始歌词参考：

ACE-Step alive
One point five arrives

校正结果（正确）：

[00:46.96]ACE-Step alive,
[00:50.80]One point five arrives.

配置

配置文件：scripts/config.json

# Switch provider
./scripts/acestep-lyrics-transcription.sh config --set provider openai
./scripts/acestep-lyrics-transcription.sh config --set provider elevenlabs

# Set API keys
./scripts/acestep-lyrics-transcription.sh config --set openai.api_key sk-...
./scripts/acestep-lyrics-transcription.sh config --set elevenlabs.api_key ...

# View config
./scripts/acestep-lyrics-transcription.sh config --list

选项	默认值	描述
provider	openai	当前使用的提供商：openai 或 elevenlabs
output_format	lrc	默认输出格式：lrc、srt 或 json
openai.api_key	""	OpenAI API 密钥
openai.api_url	https://api.openai.com/v1	OpenAI API 基础 URL
openai.model	whisper-1	OpenAI 模型（whisper-1 用于词级时间戳）
elevenlabs.api_key	""	ElevenLabs API 密钥
elevenlabs.api_url	https://api.elevenlabs.io/v1	ElevenLabs API 基础 URL
elevenlabs.model	scribe_v2	ElevenLabs 模型

提供商说明

提供商	模型	词级时间戳	定价
OpenAI	whisper-1	支持（片段级和词级）	$0.006/分钟
ElevenLabs	scribe_v2	支持（词级）	因套餐而异

• OpenAI 的 whisper-1 是唯一支持词级时间戳的 OpenAI 模型
• ElevenLabs 的 scribe_v2 返回词级时间戳，并支持按类型筛选
• 两者均支持多语言转录

示例

# Basic transcription (uses config defaults)
./scripts/acestep-lyrics-transcription.sh transcribe --audio song.mp3

# Chinese song to LRC
./scripts/acestep-lyrics-transcription.sh transcribe --audio song.mp3 --language zh

# Use ElevenLabs, output SRT
./scripts/acestep-lyrics-transcription.sh transcribe --audio song.mp3 --provider elevenlabs --format srt

# Custom output path
./scripts/acestep-lyrics-transcription.sh transcribe --audio song.mp3 --output ./my_lyrics.lrc