强制对齐
把已知文本对齐到音频
POST /v1/audio/alignments
传入 file 与对应的 text,用于定位已知文本在音频中的时间戳,而非识别未知语音。示例中关闭了文本归一化以保留原始拼写;省略该配置时默认启用文本归一化。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/audio/alignments" \
-F model=EdgeSpeak/Lattice-2 \
-F file=@hello.wav -F text="Hello world." -F language=en \
-F 'text_normalization={"enabled":false}'输出示例:
{
"task": "align",
"duration": 2.5,
"text": "Hello world.",
"segments": [
{
"id": 0,
"start": 0.2,
"end": 1.4,
"text": "Hello world.",
"words": [
{
"word": "Hello",
"start": 0.2,
"end": 0.6,
"score": 0.98
},
{
"word": "world.",
"start": 0.7,
"end": 1.4,
"score": 0.96
}
]
}
],
"usage": {
"type": "duration",
"seconds": 2.5
}
}可选参数 start 与 end 必须成对提供(单位为秒)。返回的时间戳仍相对于完整音频起始点,duration 为源文件总时长,usage.seconds 为实际处理的窗口时长。桌面网关额外支持传入 text_path,Headless 服务仅接受 text。高级配置见归一化、词典、保护词及轨道/声道选项。
参数 model 指定对齐模型,模型决定支持的语言范围。省略时默认使用 EdgeSpeak/Lattice-2,它覆盖语言目录里的全部语言、混合语言文本以及 und。EdgeSpeak/Lattice-1 仅覆盖中文、英文与德文,只在显式传 model=EdgeSpeak/Lattice-1 时使用;在它上面传其他 language 或 und 会被拒绝。这两个模型均可在 GET /v1/models 中查询,其 supported_endpoints 均包含 /v1/audio/alignments,default_for 标出当前缺省档。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/audio/alignments" \
-F model=EdgeSpeak/Lattice-2 \
-F file=@weather.wav -F text="今日はいい天気ですね。" \
-F language=ja输出示例:
{
"task": "align",
"duration": 2.1,
"language": "ja",
"text": "今日はいい天気ですね。",
"segments": [
{
"id": 0,
"start": 0.3,
"end": 1.9,
"text": "今日はいい天気ですね。",
"words": [
{ "word": "今日は", "start": 0.3, "end": 0.7, "score": 0.97 },
{ "word": "いい", "start": 0.7, "end": 0.9, "score": 0.95 },
{ "word": "天気", "start": 0.9, "end": 1.4, "score": 0.98 },
{ "word": "ですね。", "start": 1.4, "end": 1.9, "score": 0.94 }
]
}
],
"usage": { "type": "duration", "seconds": 2.1 }
}显式指定 model=EdgeSpeak/Lattice-1 再传 language=ja,接口会返回 HTTP 422 language_unsupported。遇到此错误时应更换模型,而非修改语言代码。
language 是传给 Tokenizer 的语言提示,而非硬性门槛。传入 zh、yue、ja 等代码表示显式指定语言;省略表示由运行时根据参考文本判定语言,判定不出时按不带语言对齐,不会报错;只看文本可能混淆书写系统相同的语言(如都用汉字书写的粤语和普通话),所以已知语言时请显式传入;传入 und 表示不判定语言,也不预设是哪门语言,适用于混合语言、音译文本以及没有对应语言代码的录音。und 也并非全部回退到 G2P:分词器会在所有语言的词典中逐词匹配(例如中英混排中的英文单词仍会命中英文词条,所有词典均未收录的词才会回退到通用音素集),文本归一化则按文本证据逐段选择读法,例如 我想要$100, I want $100. 会分别处理为 我想要一百美元, I want one hundred dollars.。语言目录之外的代码(如 nan、hak、wuu 等)在带 G2P 兜底的模型上同样支持,会保留文字与地区子标签(如 nan-Hant),但缺乏词典读法支持。词典里查不到的代码,效果弱于 und。
文本归一化的规则集只覆盖语言目录的一部分。对于目录外的代码,以及像粤语 yue 这样在表内但缺乏规则的语种,默认请求会自动跳过文本归一化,避免整次对齐失败;但若显式指定了 top_k、classes、pins、apply_dictionary 或 dictionary_ids,接口会返回 HTTP 400,不会静默丢弃你的配置。缺省的 EdgeSpeak/Lattice-2 支持上述全部输入;显式选择的 EdgeSpeak/Lattice-1 没有 G2P 兜底,会以 HTTP 400 bad_request 拒绝 und 与目录外代码,以 HTTP 422 language_unsupported 拒绝未覆盖的语言。
读取对齐进度
在请求中添加请求头 progress: 1。响应格式为 NDJSON,每行需独立解析为 JSON,非 SSE 格式。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/audio/alignments" \
-N -H "progress: 1" \
-F model=EdgeSpeak/Lattice-2 \
-F file=@hello.wav -F text="Hello world." \
-F 'text_normalization={"enabled":false}'输出示例:
{ "progress": 0.5}
{ "progress": 1.0}
{"task":"align","duration":2.5,"text":"Hello world.","segments":[{"id":0,"start":0.2,"end":1.4,"text":"Hello world.","words":[{"word":"Hello","start":0.2,"end":0.6,"score":0.98},{"word":"world.","start":0.7,"end":1.4,"score":0.96}]}],"usage":{"type":"duration","seconds":2.5}}包含 "task": "align" 的最终文稿行才是有效结果。仅收到进度 1.0 并不代表对齐成功。数据流有三种结束方式:
"task": "align"行:对齐成功;{"error": {...}}行:对齐失败,形状与 422 响应体相同,但数据流的 HTTP 状态仍是 200;- 数据流关闭时两者都没有:按失败处理。
使用 search_effort=auto 时,{"stage":"extended_search"} 这一行表示开始扩大搜索范围,之后进度从 0 重新计。
并发请求与等待
Headless 服务允许并发提交对齐请求,上传槽或执行槽占满时自动等待调度,不再仅因槽满而立即失败。槽位参数、默认值与作用范围见 CLI 并发参数。
请求与响应格式同上。建议根据音频时长与排队情况调大客户端超时,例如预留 30 分钟:
curl --fail-with-body --max-time 1800 "$EDGESPEAK_BASE_URL/audio/alignments" \
-F model=EdgeSpeak/Lattice-2 \
-F file=@hello.wav -F text="Hello world."任务完成后返回包含 task: "align"、segments 与 usage 的对齐结果。设置客户端超时时,需将排队、模型加载与推理三段时间一并计入;在等待执行槽期间,进度模式不会输出进度行。
处理对齐失败
本地引擎没能把文本对齐到音频时,请求返回 HTTP 422 和 error.alignment 对象,不返回结果,也不计入 usage。请按 error.code 和 error.alignment 分支;message 是英文诊断文本,可能变化。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/audio/alignments" \
-F model=EdgeSpeak/Lattice-2 \
-F file=@song.mp3 -F text="$(cat lyrics.txt)"输出示例(HTTP 422;数值仅作示意):
{
"error": {
"message": "Alignment could not be completed; the search stopped before the end of the text.",
"type": "invalid_request_error",
"code": "alignment_failed",
"alignment": {
"reason": "search_incomplete",
"search_effort_used": "standard",
"search_path": "whole_audio",
"search_limit": "none",
"retry_recommended": true,
"estimated_extra_bytes": 3221225472
}
}
}| 错误码 | 含义 |
|---|---|
alignment_failed | 对齐跑了但没能完成,细节见 reason。 |
alignment_search_budget_exceeded | 扩大搜索范围所需的内存超出本机可用范围,因此没有运行。可以截短音频后再试,例如用 start / end。 |
| 字段 | 说明 |
|---|---|
reason | no_path 或 no_words:音频里没有找到与文本对应的内容;collapsed:词被挤进了不合理的极短时长;search_incomplete:搜索在文本结尾之前停下,可能是伴奏或长静音所致。 |
search_effort_used | 本次运行的搜索档位:standard 或 extended。 |
search_path | whole_audio 表示整段一次搜索;streaming 表示长音频分段对齐。 |
search_limit | none,或搜索碰到的限制:budget(内存预算)、graph_size(搜索空间过大,无法扩大搜索)、estimate_overflow(无法算出内存估算)、streaming(分段对齐没有扩大搜索的版本)。 |
retry_recommended | 始终出现。只有码是 alignment_failed、reason 是 search_incomplete、本次跑的是 standard、没有碰到 none 以外的限制,且扩大搜索的估算落在本机内存预算内时才为 true。 |
estimated_extra_bytes | 扩大搜索预计额外占用的内存。只覆盖搜索本身,是估算,不是上限。 |
除 retry_recommended 外,服务不知道的字段会省略。reason 不是 search_incomplete 时,请确认音频与文本对应同一段内容;扩大搜索范围帮不上忙。
对齐成功但没有对上任何词(例如文本里没有可对齐的内容)时,返回 HTTP 200 且不带 segments;segments 缺失时按空列表读取。
扩大搜索范围重试
multipart 字段 search_effort 决定搜索范围:
| 取值 | 行为 |
|---|---|
standard | 默认值,传空值也按它处理。按标准范围搜索一次。 |
extended | 按更大的范围搜索一次。更慢,更耗内存;失败那次的 estimated_extra_bytes 给出大约多用多少。 |
auto | 先跑 standard;仅当它失败且 retry_recommended: true 时,再跑一次 extended。其他失败原样返回。 |
其他取值返回 400 bad_request,param 为 "search_effort"。error.alignment.retry_recommended 为 true 时,用 search_effort=extended 重发同一请求:
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/audio/alignments" \
-F model=EdgeSpeak/Lattice-2 \
-F file=@song.mp3 -F text="$(cat lyrics.txt)" \
-F search_effort=extended输出示例(响应节选):
{
"task": "align",
"duration": 214.6,
"text": "...",
"segments": [{ "id": 0, "start": 12.1, "end": 16.8, "text": "...", "words": [{ "word": "...", "start": 12.1, "end": 12.5, "score": 0.93 }] }],
"search_effort_used": "extended",
"usage": { "type": "duration", "seconds": 214.6 }
}服务报告了实际档位时,成功响应带 search_effort_used。使用 search_effort=auto 时,只有第二遍确实跑了才出现 search_retried: true,否则省略。extended 仍然失败时,retry_recommended 为 false。
参考格式
桌面端 / CLI 0.6.8 起接受 multipart text 与 text_format=txt|json|srt|ass|ssa。省略格式保留原有纯文本行为。JSON 提取 segments[].text,回退到顶层 text;SRT 和 ASS/SSA 提供原文,原有时间被忽略。ASS 样式、注释和绘图不进入对齐文本。见 Python SDK 文件示例。此项为兼容性新增。
歌词按实际演唱顺序展开
需要桌面端或 CLI 0.7.6。参考文本是歌词时(至少两行只有 [Verse 1]、[Chorus] 这类 [段落] 标记),服务会先转录音频,把重复演唱的行补齐、删掉没唱的行,再对齐展开后的文本。只对整段音频生效;带 start / end 时按原文对齐。这次额外转录计入用量。传 follow_audio=false 可按原文对齐;没有段落标记的文本不会被改动。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/audio/alignments" \
-F model=EdgeSpeak/Lattice-2 \
-F file=@song.mp3 -F text="$(cat lyrics.txt)"发生展开时(上面的请求省略了 follow_audio,沿用默认值),响应的 text 是实际对齐的文本,follow_audio 对象记录改动(响应节选,数值仅作示意):
{
"task": "align",
"text": "[Chorus]\nla la la\n[Verse]\nfirst line\nla la la",
"follow_audio": {
"applied": true,
"lines": [
{ "source_line": 0 },
{ "source_line": 1 },
{ "source_line": 2 },
{ "source_line": 3 },
{ "source_line": 1, "repeat": true }
],
"uncertain": [{ "kind": "extra", "line": 3, "start": 41.2, "end": 44.0 }]
}
}| 字段 | 说明 |
|---|---|
applied | true 表示已展开;false 表示没能识别演唱顺序,已按原文对齐。 |
lines[] | 每个对齐行一项。source_line 是原文行号(从 0 开始,段落标记也算一行);repeat: true 表示重复演唱的一遍。 |
missing | 因没唱而删掉的原文行号。 |
uncertain[] | 未采用的可能重复(extra)或可能漏唱(missing),带原文 line 和可选的 start / end(秒),供试听确认。 |
lines、missing、uncertain 为空时省略。不是歌词的请求,或设置了 follow_audio=false,响应中没有 follow_audio 键。
中文、日文按词输出
需要 0.7.6 之后的桌面端或 CLI,此时 GET /v1/health 的 capabilities 含 alignment_word_boundaries。默认(word_boundaries=auto)时,中文的 words 逐字返回,日文按词典里的词返回。做字幕或语言学习时,如果想按自己的词拿时间,就在参考文本里用空格把词分开,再传 word_boundaries=input。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/audio/alignments" \
-F file=@lesson.wav \
-F language=zh \
-F text="我们 今天 去 北京大学,参观 图书馆。" \
-F word_boundaries=input响应中的 words(节选,数值仅为示例):
[
{ "word": "我们", "start": 0.01, "end": 0.23, "score": 0.98 },
{ "word": "今天", "start": 0.23, "end": 0.75, "score": 0.97 },
{ "word": "去", "start": 0.75, "end": 1.01, "score": 0.99 },
{ "word": "北京大学,", "start": 1.01, "end": 1.93, "score": 0.95 },
{ "word": "参观", "start": 1.93, "end": 2.41, "score": 0.96 },
{ "word": "图书馆。", "start": 2.41, "end": 3.15, "score": 0.97 }
]- 每个词的开始时间取第一个字,结束时间取最后一个字;
score取词内最低值。 - 标点附在前一个词上。
,、。这类句读符号本身也算词的结尾,后面不用再加空格。 - 没有空格的文本会整段算一个词,所以要计时的每个词都要用空格隔开。日文同理,例如
私は 東京大学で 日本語を。 - 开启语义分句时,被句子边界切到的词会在边界处分成两段。
- 不支持这项能力的旧网关会忽略该字段,照旧逐字返回;CLI、MCP 和 Python SDK 会先检查能力,不支持时直接报错。
普通话与粤语混合音频
需要桌面端或 CLI 0.6.8。桌面端、CLI、HTTP 与 MCP 共用默认策略:Lattice-2 在指定或检测为中文、粤语时自动比较普通话与粤语读法。其他语言、und 和 Lattice-1 保持原有行为,无需新增语言选项;仍可用 pronunciation_mode=mandarin_cantonese 显式请求。
当前数字等文本改写沿用普通话规则,尚无粤语数字改写候选;这类改写按普通话读法对齐。未改写的文字可在普通话和粤语发音之间选择。
curl --fail-with-body "$EDGESPEAK_BASE_URL/audio/alignments" \
-F model=EdgeSpeak/Lattice-2 -F file=@mixed.wav \
-F 'text=你好,香港呢有兩大嘅文化特徵。' \
-F pronunciation_mode=mandarin_cantonese此模式接受省略 language,或指定 zh / yue;不兼容的模型或语言会报错。启用文本归一化时,数字、日期等读法保持各自语言的一致性。混合候选不保证每个字界都更准确,仍应检查切换处及不清晰语音。
双输入声学对齐
POST /v1/audio/diff-alignments
需要 0.6.8 网关宣告 diff_alignment 能力。音频和两份文本数组必须同时提交,音频含 padding 最多 300 秒。支持可选 model、language 和非负 offset;返回时间已含偏移。original_index 指向本次参考数组下标,或为 -1;说话人标签来自输入文本,不代表声纹身份验证。不支持的选项会被拒绝。长录音需要成对分窗,不会退回单输入。
请求示例:
curl --fail-with-body "$EDGESPEAK_BASE_URL/audio/diff-alignments" \
-F file=@hello.wav \
-F 'reference_segments=[{"text":"Hello world","speaker":"A"}]' \
-F 'transcript_segments=[{"text":"Hello new world"}]' \
-F offset=60输出示例(节选):
{"segments":[{"text":"Hello new world","start":60.2,"end":61.4,"original_index":0,"speaker":"A","words":[{"word":"Hello","start":60.2,"end":60.5,"score":0.98}]}],"speaker_source":"input_text"}