更新记录

1.0.0（2026-07-19）

首发：自研高性能原生音高检测（McLeod MPM，±0.1Hz）与 FFT 频谱核心，提供 uni-app 可调的 JS API：detectPitch / com

平台兼容性

uni-app x(5.14)

nex-tuner —— 音高检测 / 频谱分析（调音器核心）

自研高性能原生调音器核心（McLeod MPM 音高检测 ±0.1Hz + FFT 频谱），提供 uni-app 可调的 JS API。 支持 App 端（Android / iOS）+ H5 端（全部 3 API 可用）；小程序不支持。

录音采集在 JS/UTS 侧（如 uni 录音 API 取 PCM16 帧），本插件负责「一窗 PCM 进 → 基频/音名/音分出」的纯计算。

API（3 个）

类型

type PitchResult = {
  frequency: number;  // 基频 Hz（抛物线插值）
  midiNote: number;   // 最近 MIDI 音符号（A4 = 69）
  noteName: string;   // 音名 "A" / "C#"（升号制）
  octave: number;     // 八度（A4 → 4）
  cents: number;      // 相对最近音的音分偏差 ≈ -50..+50（负=偏低，正=偏高）
  clarity: number;    // 清晰度/置信 0..1
};

type SpectrumResult = {
  magnitudes: number[]; // 幅度谱，长度 fftSize/2 + 1（0Hz..Nyquist）
  binHz: number;        // 每 bin 频宽 = sampleRate / fftSize
  fftSize: number;      // 实际 FFT 点数
};

用法

import { detectPitch, computeSpectrum, freqToNote } from "@/uni_modules/nex-tuner";

// 推荐 4096 样本 @44.1k/48k（约 85~93ms 一窗），兼顾精度与刷新率
const r = detectPitch(pcmFrame, 44100, 440);
if (r != null) {
  console.log(`${r.noteName}${r.octave} ${r.cents > 0 ? '+' : ''}${r.cents.toFixed(1)} 音分`);
}

const spec = computeSpectrum(pcmFrame, 44100, 4096);
// spec.magnitudes 画频谱条，spec.binHz 换算频率轴

const n = freqToNote(392.0, 440); // → G4

精度与建议（诚实标注）

• ±0.1Hz 需足够长窗：低音 E2≈82Hz 至少 2048 样本；推荐 4096 样本窗。
• UI 侧可对连续帧 frequency 做中值/指数平滑去抖（v1 平滑在 JS 侧）。
• a4 默认 440，古乐/管弦可传 415/442 等。
• 输入守卫：样本数 ≤ 2²⁰、sampleRate ∈ [4000, 192000]、fftSize 2 的幂 ∈ [64, 65536]，超限抛 InvalidParam；内部异常统一兜成可捕获错误、绝不闪退。

使用前提（购买前请读）

• App 端（app-android / app-ios）+ H5 端可用；小程序不支持。
• App 端必须自定义基座或云打包（含原生库，标准基座跑不了；Android 真机调试需自定义调试基座，HBuilderX ≥ 4.26）。
• 验证状态：核心 19 项自动化测试全量通过（黄金向量：合成正弦波频率/音名/音分断言）。

完整契约见仓库 docs/tuner-plugin-contract.md。