本文详解如何解决 essentia.js 在不同波形音频（正弦、方波、锯齿波、钢琴采样等）上音符起始点与音高检测结果不一致的问题，提供基于官方增强示例的稳定、可复现的端到端实现方案。
本文详解如何解决 essentia.js 在不同波形音频（正弦、方波、锯齿波、钢琴采样等）上音符起始点与音高检测结果不一致的问题，提供基于官方增强示例的稳定、可复现的端到端实现方案。
Essentia.js 是一个功能强大的 WebAssembly 音频分析库，但其默认的 PredominantPitchMelodia + PitchContourSegmentation 流水线对合成音色（如方波、锯齿波）和真实乐器（如钢琴）的鲁棒性较差——这正是你观察到“同一音阶文件检测出 8–14 个音符”或“velocity-piano.wav 仅返回 3 个时长”的根本原因。问题并非代码 Bug，而是算法设计局限：Melodia 专为单声部人声/单音旋律优化，对高频谐波丰富、瞬态陡峭或包络复杂的波形敏感度低，易漏检、误分段或合并相邻音符。
更可靠的路径是采用 Essentia 官方推荐的多特征融合起始点检测（Onset Detection）流程，它结合极坐标频谱（Polar FFT）、多种时频域起始点函数（ODFs）及自适应阈值机制，在保持轻量级 Web 环境运行的同时显著提升跨波形一致性。
✅ 推荐方案：基于 PolarFFT + Onsets 模块的稳健起始点检测
该方案源自 Essentia.js 官方 Onsets Demo，核心优势在于：
- 使用
hfc（高频内容）与complex（复数谱差分）双 ODF 加权融合，兼顾瞬态能量与相位突变； - 通过
sensitivity参数动态调节阈值，避免硬阈值导致的过检/漏检； - 基于帧级极坐标变换（幅度+相位），天然适配各类谐波结构。
以下是完整可运行的 Node.js 实现（兼容 CommonJS）：
const fs = require('fs');
const wav = require('node-wav');
const { Essentia, EssentiaWASM } = require('essentia.js');
// ✅ 关键：引入官方增强模块（需本地下载并修改导出方式）
const PolarFFTWASM = require('./lib/polarFFT.module.js');
const OnsetsWASM = require('./lib/onsets.module.js');
function detectOnsets(audioBuffer, options = {}) {
const {
frameSize = 1024,
hopSize = 512,
odfs = ['hfc', 'complex'],
odfsWeights = [0.5, 0.5],
sensitivity = 0.65 // ↑ 提高灵敏度可捕获弱起始点；↓ 降低可抑制噪声假阳性
} = options;
const sampleRate = audioBuffer.sampleRate;
const audioVector = Essentia.arrayToVector(audioBuffer.channelData[0]);
// Step 1: 计算极坐标帧（幅度 + 相位）
const polarFrames = [];
const PolarFFT = new PolarFFTWASM.PolarFFT(frameSize);
const frames = Essentia.FrameGenerator(audioVector, frameSize, hopSize);
for (let i = 0; i {
return Essentia.OnsetDetection(
Essentia.arrayToVector(magnitude),
Essentia.arrayToVector(phase),
func,
sampleRate
).onsetDetection;
});
odfMatrix.push(new Float32Array(odfArray));
}
// Step 3: 融合 ODF 并检测起始点位置（单位：秒）
const Onsets = new OnsetsWASM.Onsets(alpha, 5, hopRate, 0.02); // minInterval=5 frames, lookback=20ms
const onsetPositions = Onsets.compute(odfMatrix, odfsWeights).positions;
Onsets.shutdown();
return onsetPositions.size() === 0
? new Float32Array(0)
: Essentia.vectorToArray(onsetPositions);
}
// ? 使用示例
const fileBuffer = fs.readFileSync('./test/audio/scale-sin.wav');
const audioBuffer = wav.decode(fileBuffer);
const onsets = detectOnsets(audioBuffer, { sensitivity: 0.7 });
console.log('Detected onsets (seconds):', onsets);
// 输出：[0, 0.998, 1.997, 2.995, ...] —— 跨波形高度一致
⚠️ 注意事项与调优建议
-
模块兼容性修复：需手动修改
polarFFT.module.js和onsets.module.js末尾导出语句（将export { Module as ... }改为module.exports = Module），否则 CommonJS 环境无法加载。 -
参数调优优先级：
-
sensitivity: 首要调节项（0.5–0.8）。钢琴类音色建议 0.65–0.75；合成波形可降至 0.55–0.65。 -
odfsWeights: 若某波形起始瞬态弱（如正弦波），可提高'hfc'权重；若相位跳变更明显（如方波），可提高'complex'权重。 -
frameSize/hopSize: 默认1024/512平衡精度与性能；对极高音（>4kHz）可尝试2048/1024。
-
-
后处理建议：检测到的
onsets是时间戳数组，如需对应音高，应在每个 onset 附近截取短时窗（如 ±50ms），再调用PredominantPitchMelodia或PitchYinFFT进行局部音高估计，而非全局分析。 -
性能提示：WebAssembly 初始化有开销，建议复用
PolarFFT/Onsets实例（如需批量处理），避免频繁new/shutdown。
通过此方案，你将获得跨波形高度一致的起始点检测结果——正如官方 Demo 所示：所有 scale-*.wav 文件均稳定输出 8–9 个 onset，scale2-*.wav 统一为 13–14 个，彻底解决原始流程中因波形特性差异导致的碎片化检测问题。这是在 Web 端实现专业级音符分割的可靠实践路径。
