fix: 真机 16k mp3 服务端解码为 PCM,修复 ASR 实时回显失败

DashScope 无法解码微信真机录制的 16k MPEG-2 Layer III mp3(报 DecodePost resample audio from 0 to 16000 failed)。按文件头识别容器后,实时与整段两条链路统一先解码为 16bit 单声道 PCM 再推供应商。
This commit is contained in:
lik
2026-10-31 19:54:37 +08:00
parent 02d57f82dc
commit 13981c047b
7 changed files with 186 additions and 63 deletions
+8 -6
View File
@@ -155,9 +155,11 @@ test/media.test.js 元信息白名单、base64 解码、会话生命周期
- 小程序录音使用 `wx.getRecorderManager()`,`format: 'mp3'`、`sampleRate: 16000`、`numberOfChannels: 1`,
并带 `frameSize`(单位 KB)以触发 `onFrameRecorded`:每帧转 base64 后按 `asr_chunk` 实时上传,
点麦克风结束(或满 60 秒)时发 `asr_stop`。
- **两种录音格式都能实时回填**:真机录的是 mp3 分片,服务端按首帧魔数确认为 mp3 后直接透传给供应商;
开发者工具录的是 WebM(Matroska)/Opus(文件名仍是 `.mp3`),服务端用流式解码器同步转成
16bit 单声道 PCM(48k 抽取到 16k)后再推给供应商,因此工具里也能逐字出中间结果。
- **两种录音格式都能实时回填**:真机录的是 16k 单声道 MP3(MPEG-2 Layer III),
开发者工具录的是 WebM(Matroska)/Opus(文件名仍是 `.mp3`)。供应商自带的解码器对这两种容器
都不可靠(真机 mp3 实测直接报 `DecodePost resample audio from 0 to 16000 failed`),
因此服务端按首帧魔数识别容器后,统一用流式解码器(WebM/Opus、mp3/mpg123)转成
16bit 单声道 PCM(48k 抽取到 16k、16k 原样)再推给供应商,两种环境都能逐字出中间结果。
客户端不再判断容器,分片一律上传;只有服务端明确回 `asr_error`(认不出容器 / 供应商失败)时
才降级为「结束后整段转写」。首帧认不出容器时服务端先缓存至多 16KB 再判,避免误杀只有 cluster 的平台。
- 整段识别遇到供应商偶发断流(`asr socket closed` / 建连超时)会自动重试一次(间隔 600ms),
@@ -166,9 +168,9 @@ test/media.test.js 元信息白名单、base64 解码、会话生命周期
一次性把几秒 PCM 塞进 socket 会让供应商来不及消费而直接断流。
- 实时链路在说话途中失败时客户端不弹错、不中断录音,标记为降级并继续采集;结束时用完整录音文件
(而不是失败瞬间的半截分片)整段提交 `/health/ai/asr`,只有整段也失败才提示用户。
- 微信开发者工具的录音实际是 WebM(Matroska)/Opus(文件名仍是 `.mp3`,控制台会提示格式与移动端不同)。
服务端按文件头识别容器,WebM 会先解码成 16bit 单声道 PCM(48k 抽取到 16k)再交给供应商,
因此工具里也能正常转写;真机录制的 mp3 直接透传。
- 微信开发者工具的录音实际是 WebM(Matroska)/Opus(文件名仍是 `.mp3`,控制台会提示格式与移动端不同);
真机才是真正的 16k mp3。服务端按文件头识别容器后都先解码成 16bit 单声道 PCM 再交给供应商,
整段兜底的 `/health/ai/asr` 走同一个识别入口,因此两条链路都能正常转写。
- 拍照 / 选图使用 `wx.chooseMedia`,上传前压缩到 1~2MB。图片不走确认面板:选中后立即作为一条用户消息上屏,
`/health/ai/ocr` 返回的文本直接落成 AI 回复;图片临时路径不落 storage,重启后历史里只保留 `[图片]` 占位。
- 语音识别结果实时回填输入框;**再次点麦克风结束识别后直接发送**(`asr_final` 定稿或整段兜底成功后
+73 -14
View File
@@ -1,14 +1,16 @@
/**
* 音频容器识别与 WebM 解码
* 音频容器识别与解码
*
* 小程序在真机上按 `format: 'mp3'` 落盘,但开发者工具用浏览器的 MediaRecorder,
* 产物是 WebM(Matroska)/Opus,文件名却仍是 `.mp3`。若直接按声明格式转给供应商,
* DashScope 会报「DecodePost resample audio from 0 to 16000 failed」。
* 小程序真机按 `format: 'mp3'` 录音,产物是 16k 单声道的 MPEG-2 Layer III;
* 开发者工具用浏览器的 MediaRecorder,产物是 WebM(Matroska)/Opus,文件名却仍是 `.mp3`。
* DashScope 自带的解码器对这两种容器都不可靠(mp3 实测报
* 「DecodePost resample audio from 0 to 16000 failed」),直接透传会整轮失败。
*
* 因此这里按文件头识别真实容器:WebM 先解码成 16bit 单声道 PCM 再走识别,
* 其余格式保持原有链路(供应商直接支持 mp3/aac/wav/pcm)。
* 因此这里按文件头识别真实容器:WebM 与 mp3 都先在服务端解码成 16bit 单声道 PCM
* 再推给供应商,其余格式保持原有链路(供应商直接支持 aac/wav/pcm)。
*/
import decodeWebm, { decoder as createWebmDecoder } from '@audio/decode-webm';
import decodeMp3, { decoder as createMp3Decoder } from '@audio/decode-mp3';
/** WebM / Matroska 的 EBML 魔数:1A 45 DF A3 */
const EBML_MAGIC = 0x1a45dfa3;
@@ -113,6 +115,25 @@ export async function webmToPcm(audio, decodeImpl = decodeWebm) {
return { pcm, rate: Number(result.sampleRate) || 48000, samples: pcm.length / 2 };
}
/**
* MP3 解码为 16bit 单声道 PCM
*
* 真机录音是 16k 单声道 MPEG-2 Layer III,mpg123 能正常解出音频;
* 解码后再按实际采样率(16k 时无需抽取)推给供应商,避开供应商侧的解码失败。
*
* @param {Buffer|Uint8Array} audio - MP3 原始字节
* @param {Function} [decodeImpl] - 测试注入的解码实现
* @returns {Promise<{pcm: Buffer, rate: number, samples: number}>}
*/
export async function mp3ToPcm(audio, decodeImpl = decodeMp3) {
const result = await decodeImpl(audio);
const channelData = Array.isArray(result?.channelData) ? result.channelData : [];
const pcm = channelsToPcm16(channelData);
if (!pcm.length) throw new Error('mp3 decoded audio is empty');
return { pcm, rate: Number(result.sampleRate) || 16000, samples: pcm.length / 2 };
}
/**
* 16bit 单声道 PCM 降采样(整数倍抽取)
*
@@ -143,18 +164,20 @@ export function downsamplePcm16(pcm, fromRate, toRate = 16000) {
}
/**
* 创建 WebM 流式解码器:边收分片边出 16bit 单声道 PCM
* 把容器解码器包成统一的「边收分片边出 16bit 单声道 PCM」接口
*
* 开发者工具的录音是 WebM/Opus,供应商无法直接识别这种容器;
* 整段路径可以等录完再解码,实时链路必须边收边解,才能逐字回填。
* 解码器按 Matroska 结构增量解析,分片边界不必对齐 cluster。
* WebM(Opus) 与 MP3 的增量解码接口一致(decode 返回 channelData/sampleRate),
* 区别只在 WebM 需要 flush 冲尾部、MP3 帧间独立且没有 flush。
*
* @param {Function} [factory] - 测试注入的解码器工厂
* @param {Function} factory - 解码器工厂
* @param {Object} [options]
* @param {number} [options.defaultRate] - 首帧前使用的默认采样率
* @param {boolean} [options.hasFlush] - 是否支持 flush
* @returns {Promise<{rate: number, push: Function, flush: Function, free: Function}>}
*/
export async function createStreamingWebmDecoder(factory = createWebmDecoder) {
async function wrapStreamingDecoder(factory, { defaultRate = 48000, hasFlush = true } = {}) {
const decoder = await factory();
let rate = 48000;
let rate = defaultRate;
const toPcm = (audioData) => {
const sampleRate = Number(audioData?.sampleRate);
@@ -167,13 +190,14 @@ export async function createStreamingWebmDecoder(factory = createWebmDecoder) {
get rate() {
return rate;
},
/** 推入一个 WebM 分片,返回该分片解出的 PCM(可能为空) */
/** 推入一个容器分片,返回该分片解出的 PCM(可能为空) */
async push(chunk) {
// Opus/Vorbis 同步返回,Matroska-only 编码首次加载编码器时是 Promise
return toPcm(await decoder.decode(chunk));
},
/** 收尾,返回剩余 PCM(可能为空) */
async flush() {
if (!hasFlush || typeof decoder.flush !== 'function') return Buffer.alloc(0);
return toPcm(await decoder.flush());
},
free() {
@@ -185,3 +209,38 @@ export async function createStreamingWebmDecoder(factory = createWebmDecoder) {
}
};
}
/**
* 创建 WebM 流式解码器
* @param {Function} [factory] - 测试注入的解码器工厂
* @returns {Promise<{rate: number, push: Function, flush: Function, free: Function}>}
*/
export async function createStreamingWebmDecoder(factory = createWebmDecoder) {
return wrapStreamingDecoder(factory, { defaultRate: 48000, hasFlush: true });
}
/**
* 创建 MP3 流式解码器
* @param {Function} [factory] - 测试注入的解码器工厂
* @returns {Promise<{rate: number, push: Function, flush: Function, free: Function}>}
*/
export async function createStreamingMp3Decoder(factory = createMp3Decoder) {
return wrapStreamingDecoder(factory, { defaultRate: 16000, hasFlush: false });
}
/** 需要服务端解码的容器(其余格式仍直接交给供应商) */
const STREAMING_DECODERS = {
webm: createStreamingWebmDecoder,
mp3: createStreamingMp3Decoder
};
/**
* 按容器创建流式解码器
* @param {'webm'|'mp3'} format - sniffAudioFormat 的结果
* @returns {Promise<{rate: number, push: Function, flush: Function, free: Function}>}
*/
export async function createStreamingAudioDecoder(format) {
const factory = STREAMING_DECODERS[format];
if (!factory) throw new Error(`unsupported streaming audio format: ${format}`);
return factory();
}
+8 -6
View File
@@ -13,7 +13,7 @@
import config from '../../../config.js';
import logger from '../../../utils/logger.js';
import { createRecognizer, DEFAULT_AUDIO_FORMAT } from './asr.js';
import { sniffAudioFormat, webmToPcm, downsamplePcm16 } from './audio.js';
import { sniffAudioFormat, webmToPcm, mp3ToPcm, downsamplePcm16 } from './audio.js';
import { createOcrSession, DEFAULT_IMAGE_FORMAT } from './ocr.js';
/** conf.json 的 agent.media 段(缺失时用内置默认值) */
@@ -232,13 +232,14 @@ async function pushChunks(session, chunks) {
export async function recognizeAudio(audio, meta = {}) {
const cfg = MEDIA_CONFIG.asr ?? {};
// 开发者工具的录音实际是 WebM/Opus(扩展名仍是 .mp3,见 audio.js)。
// 供应商按声明格式解析会直接报解码失败,这里按文件头识别后先转成 PCM。
// 两条录音链路的容器供应商都解不了(开发者工具是 WebM/Opus,真机是 16k MP3,
// 实测都会报 DecodePost 解码失败,见 audio.js),这里按文件头识别后统一转成 PCM。
let input = audio;
let inputMeta = meta;
if (sniffAudioFormat(audio) === 'webm') {
const container = sniffAudioFormat(audio);
if (container === 'webm' || container === 'mp3') {
try {
const decoded = await webmToPcm(audio);
const decoded = container === 'webm' ? await webmToPcm(audio) : await mp3ToPcm(audio);
// 实时协议对裸 PCM 只稳定支持 16k:48k 先整数倍抽取,与实时链路保持一致
const rate = Number.isInteger(decoded.rate / 16000) && decoded.rate > 16000 ? 16000 : decoded.rate;
input = rate === decoded.rate ? decoded.pcm : downsamplePcm16(decoded.pcm, decoded.rate, rate);
@@ -250,8 +251,9 @@ export async function recognizeAudio(audio, meta = {}) {
rate,
channels: 1
};
logger.info('webm audio decoded for asr', {
logger.info('audio container decoded for asr', {
requestId: meta.requestId || '',
container,
bytes: audio.length,
sourceRate: decoded.rate,
pcmBytes: input.length,
+1
View File
@@ -8,6 +8,7 @@
"name": "attendant-api",
"version": "1.0.0",
"dependencies": {
"@audio/decode-mp3": "^1.3.1",
"@audio/decode-webm": "^1.6.1",
"@langchain/anthropic": "^1.5.9",
"@langchain/core": "^1.2.9",
+1
View File
@@ -10,6 +10,7 @@
"test": "node --test test/*.test.js"
},
"dependencies": {
"@audio/decode-mp3": "^1.3.1",
"@audio/decode-webm": "^1.6.1",
"@langchain/anthropic": "^1.5.9",
"@langchain/core": "^1.2.9",
+60
View File
@@ -16,9 +16,12 @@ import {
MediaInputError,
} from "../agent/infra/media/index.js";
import {
createStreamingAudioDecoder,
createStreamingMp3Decoder,
createStreamingWebmDecoder,
downsamplePcm16,
findEbmlHeader,
mp3ToPcm,
sniffAudioFormat,
webmToPcm,
} from "../agent/infra/media/audio.js";
@@ -120,6 +123,63 @@ test("WebM 流式解码器按分片连续产出 PCM", async () => {
decoder.free();
});
test("MP3 解码结果下混为 16bit 单声道 PCM", async () => {
// mpg123 对单声道也输出左右两路相同的通道数据,下混后仍是原样本
const { pcm, rate, samples } = await mp3ToPcm(Buffer.from("mp3"), async () => ({
channelData: [
new Float32Array([0.5, -0.5]),
new Float32Array([0.5, -0.5]),
],
sampleRate: 16000,
}));
assert.equal(rate, 16000);
assert.equal(samples, 2);
assert.equal(pcm.length, 4);
assert.equal(pcm.readInt16LE(0), Math.round(0.5 * 32767));
assert.equal(pcm.readInt16LE(2), Math.round(-0.5 * 32767));
await assert.rejects(
() => mp3ToPcm(Buffer.from("mp3"), async () => ({ channelData: [] })),
/decoded audio is empty/
);
});
test("MP3 流式解码器按分片产出 PCM,并以解码器实际采样率为准", async () => {
const fakeDecoder = {
decode(chunk) {
// 不足一帧时 mpg123 返回空通道数据和 0 采样率,不能把 rate 写成 0
if (chunk.length < 4) return { channelData: [], sampleRate: 0 };
return {
channelData: [new Float32Array([0.5]), new Float32Array([0.5])],
sampleRate: 16000,
};
},
free() {},
};
const decoder = await createStreamingMp3Decoder(async () => fakeDecoder);
assert.equal(decoder.rate, 16000);
assert.equal((await decoder.push(Buffer.from([1, 2, 3]))).length, 0);
assert.equal(decoder.rate, 16000);
const pcm = await decoder.push(Buffer.from([4, 5, 6, 7]));
assert.equal(pcm.length, 2);
assert.equal(pcm.readInt16LE(0), Math.round(0.5 * 32767));
// mp3 没有尾部缓冲,flush 必须是空结果而不是抛错
assert.equal((await decoder.flush()).length, 0);
decoder.free();
});
test("流式解码器按容器分发,未知容器直接报错", async () => {
// 只验证分发入口的契约,避免在单测里加载 WASM 解码器
await assert.rejects(
() => createStreamingAudioDecoder("aac"),
/unsupported streaming audio format/
);
});
test("48k PCM 按整数倍抽取到 16k,非整数倍保持原样", () => {
const pcm = Buffer.alloc(48 * 2);
for (let i = 0; i < 48; i += 1) {
+35 -37
View File
@@ -16,7 +16,7 @@ import {
import {
sniffAudioFormat,
findEbmlHeader,
createStreamingWebmDecoder,
createStreamingAudioDecoder,
downsamplePcm16
} from "./agent/infra/media/audio.js";
@@ -352,8 +352,9 @@ export default class WebSocketServerManager {
return;
}
// 供应商会话按首帧确认真实容器后再建:真机是真 mp3,浏览器(开发者工具)是 WebM,
// 后者要先流式解码成 PCM 才能推给供应商,两种编码不能共用一份 run-task 参数
// 供应商会话按首帧确认真实容器后再建:真机是 16k mp3,浏览器(开发者工具)是 WebM。
// 两种容器供应商都解不了(实测报 DecodePost 解码失败),都要先在服务端流式解成 PCM,
// 因此不能把原始分片直接透传,也不能按声明格式共用一份 run-task 参数
const state = {
id: msg.id || `asr_${Date.now()}`,
userId: String(userInfo._id),
@@ -365,7 +366,7 @@ export default class WebSocketServerManager {
decoder: null,
// 帧头诊断只打一次:确认客户端分片是否带完整容器头
headLogged: false,
// 推给供应商的 PCM 采样率(WebM 解码后归一,mp3 链路不用)
// 推给供应商的 PCM 采样率(解码后按实际输出归一)
rate: 0,
// 是否已收到过中间结果(仅用于诊断日志)
partialSeen: false,
@@ -427,10 +428,10 @@ export default class WebSocketServerManager {
}
/**
* 处理一帧音频:首帧先判真实容器,再决定直接推 mp3 还是先流式解码 WebM
* 处理一帧音频:首帧先判真实容器,再决定解码方式
*
* 真机录的是 mp3 分片,容器直接交给供应商;
* 开发者工具录的是 WebM/Opus,供应商不认这个容器,必须边收边解码成 PCM。
* 真机录的是 16k mp3,开发者工具录的是 WebM/Opus,
* 两种容器供应商都解不了,统一在服务端边收边解码成 PCM 再推。
*/
async _consumeAsrChunk(ws, state, buffer) {
if (ws.asrSession !== state || state.failed) return;
@@ -477,27 +478,27 @@ export default class WebSocketServerManager {
state.format = sniffed;
state.pending = [];
// 排查实时链路时先看这一行:确认服务端认出的真实容器
// 排查实时链路时先看这一行:确认服务端认出的真实容器与帧头
logger.info('asr stream format detected', {
requestId: state.id,
format: sniffed,
headBytes: head.length
headBytes: head.length,
firstBytes: head.subarray(0, Math.min(head.length, 16)).toString('hex')
});
if (sniffed === 'webm') {
try {
state.decoder = await createStreamingWebmDecoder();
} catch (err) {
console.warn('[ASR] webm decoder init failed:', err?.message ?? err, { requestId: state.id });
this._failAsrStream(ws, state, '语音识别失败,请稍后重试');
return;
}
// 供应商会话等第一段 PCM 解出来再建:采样率以解码器实际输出为准
await this._pushAsrAudio(ws, state, head);
// webm(开发者工具)与 mp3(真机)都先流式解码成 PCM:
// 供应商对这两种容器的解码都不可靠,透传会整轮失败
try {
state.decoder = await createStreamingAudioDecoder(sniffed);
} catch (err) {
console.warn('[ASR] audio decoder init failed:', err?.message ?? err, {
requestId: state.id,
format: sniffed
});
this._failAsrStream(ws, state, '语音识别失败,请稍后重试');
return;
}
this._createAsrSession(ws, state, { codec: state.meta.codec, rate: state.meta.rate });
// 供应商会话等第一段 PCM 解出来再建:采样率以解码器实际输出为准
await this._pushAsrAudio(ws, state, head);
return;
}
@@ -505,25 +506,22 @@ export default class WebSocketServerManager {
await this._pushAsrAudio(ws, state, buffer);
}
/** 把一帧音频推给供应商:WebM 先解码成 PCM,mp3 原样推 */
/** 把一帧音频推给供应商:容器分片先解码成 PCM,再按 16k 归一推流 */
async _pushAsrAudio(ws, state, buffer) {
if (ws.asrSession !== state || state.failed) return;
if (ws.asrSession !== state || state.failed || !state.decoder) return;
try {
if (state.decoder) {
const pcm = await state.decoder.push(buffer);
// 首帧往往只有 WebM 头,解不出音频:等第一段 PCM 出来再建供应商会话
if (!pcm.length) return;
if (!state.session) {
// 采样率以首帧解码结果为准:Opus 是 48k,整数倍抽取到 16k
state.rate = resolveAsrRate(state.decoder.rate);
this._createAsrSession(ws, state, { codec: 'pcm16', rate: state.rate });
}
const out = downsamplePcm16(pcm, state.decoder.rate, state.rate);
if (out.length) state.session.push(out);
return;
const pcm = await state.decoder.push(buffer);
// 首帧往往只有容器头(WebM 的 EBML / mp3 的元信息),解不出音频:
// 等第一段 PCM 出来再建供应商会话
if (!pcm.length) return;
if (!state.session) {
// 采样率以首帧解码结果为准:Opus 是 48k,真机 mp3 是 16k
state.rate = resolveAsrRate(state.decoder.rate);
this._createAsrSession(ws, state, { codec: 'pcm16', rate: state.rate });
}
if (state.session) state.session.push(buffer);
const out = downsamplePcm16(pcm, state.decoder.rate, state.rate);
if (out.length) state.session.push(out);
} catch (err) {
// 解码失败说明这一轮的分片无法拼成完整音频,交给客户端结束后的整段兜底
console.warn('[ASR] audio decode failed:', err?.message ?? err, { requestId: state.id });
@@ -562,7 +560,7 @@ export default class WebSocketServerManager {
});
}
// WebM 流式解码:把解码器里剩余的帧冲出来再收尾
// 流式解码收尾:把解码器里剩余的音频冲出来再收(mp3 无尾部缓冲,返回空)
if (state.decoder) {
const tail = await state.decoder.flush();
if (!state.session && tail.length) {