# @audio/pitch 中文文档规范地址：https://npmcn.com/package/%40audio/pitch/ 版本：2\.2\.0 npm 元数据更新时间：2026-10-17T21:59:12.732Z 中文译文更新时间：2026-11-09T21:00:54.154Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。原始 npm 页面：https://www.npmjs.com/package/%40audio/pitch 原文对照：https://npmcn.com/package/%40audio/pitch/?lang=original 项目主页：https://github.com/audiojs/pitch#readme 源码仓库：https://github.com/audiojs/pitch ## 关键信息（来自 npm 元数据） - 包体积（解压后）：21.7 kB，23 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=18 - 运行依赖：8 个 - 首次发布：2026-07-08T19:45:45.841Z - 最新版本发布：2026-10-17T21:59:12.474Z - 近 30 天下载量：1731（2026-10-07 至 2026-11-05，npm 官方下载统计） - 已发布版本数：7（近 12 个月 7 个） ## 中文简介 Pitch 检测 — @ audio/ pitch- \* 原子的雨伞( YIN, pYIN, McLeod, HPS, cepstrum, SWIPE, 自动脉冲, AMDF) ## 安装 ```sh npm install @audio/pitch ``` 也可以使用：`pnpm add @audio/pitch`、`yarn add @audio/pitch`、`bun add @audio/pitch` ## README # @ audio/ pitch (英语) [![test](https://github.com/audiojs/pitch/actions/workflows/test.yml/badge.svg)](https://github.com/audiojs/pitch/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/@audio/pitch)](https://www.npmjs.com/package/@audio/pitch) [![MIT](https://img.shields.io/badge/MIT-%E0%A5%90-white)](https://github.com/krishnized/license) 皮奇检测(F0估计). YIN,McLeod,pYIN,自通,AMDF,HPS,cepstrum,SWIPE.

时间域

阳 ——累计平均归正差
麦克莱德 ——平方平方差(MPM)
pYIN (英语) – 概率YIN 与 Beta 先行
自动连接 ——实现自动化
AMDF (法语) ——平均相差幅度

光谱

HPS 软件 口琴产品谱
积分 - 真正的接力峰顶
系统锯齿波形启发了估计器

> 色调、和弦和密钥探测器移到 [@audio/mir (英语)](https://github.com/audiojs/mir) (单位:千美元)`mir-chroma`, (中文(简体) ), `mir-chord`, (中文(简体) ), `mir-key`) (中文(简体) ). ## 安装 ``` npm install @audio/pitch ``` ## 使用量 ```js import { yin, mcleod } from '@audio/pitch' let fs = 44100 let frame = new Float32Array(2048) // fill from your audio source let result = yin(frame, { fs }) // → { freq: 440.1, clarity: 0.97 } or null ``` > 在Node.js和浏览器中工作. 不需要网络音频 API —— 运行于原始 `Float32Array` 样本. **滑动窗口** ——随着新样品的到来,反复打来: ```js let hop = 512 for (let i = 0; i + 2048 <= samples.length; i += hop) { let frame = samples.subarray(i, i + 2048) let result = yin(frame, { fs }) if (result) console.log(i / fs, result.freq.toFixed(1)) } ``` **和谐管道** 铬和弦关键生活 [@audio/mir (英语)](https://github.com/audiojs/mir)数字 : ```js import { chroma, chord, smoothChords, key } from '@audio/mir' let frames = [] for (let i = 0; i + 4096 <= samples.length; i += 2048) { frames.push(chroma(samples.subarray(i, i + 4096), { fs, method: 'nnls' })) } let chords = smoothChords(frames, { selfProb: 0.5 }) let k = key(frames) ``` ## API 密码所有投出算法返回 `{ freq, clarity } | null`数字 : - `freq` - Hz的基本频率 - `clarity` ——算法特定信心 `[0, 1]` - `null` ——未发现周期性结构(静态,噪声,多声) 时间域算法(YIN,McLeod,pYIN,自動相關,AMDF)接受任何缓冲长度. 光谱算法(HPS, cepstrum, SWIPE)需要2个长度的功率. 每个算法也是可安装的独立: `npm install @audio/pitch-yin` 包括:. * * * ## 阳 **《Cheveigné & Kawahara》,2002年.** 单声波投出估计的参考算法. 大部分被引用,大多数测试,最强健. ```js import yin from '@audio/pitch-yin' let result = yin(samples, { fs: 44100 }) ``` | 参数 | 默认 | | | --- | --- | --- | | `fs` | `44100` | 样本率(赫兹) | | `threshold` | `0.15` | CMND 阈值 — 较低 = 检测更严格,检测更少 | | `minFreq` | —— 说 | 最小频率( Hz); 也使用更多帧来进行低音调 | | `maxFreq` | —— 说 | 最大频率 (Hz) | 已知时通过预期范围 : `yin(samples, { fs, minFreq: 60, maxFreq: 520 })`除了拒绝外出的结果, `minFreq` 让YIN使用更长的比较窗口,并改进近发起地的低pitch检测. **使用时 :** 通用单音波音跟踪——语音,歌唱,独奏乐器. 最可靠的选择当怀疑. **不为:** 多声道音频(回归为主或为无效),实时有硬潜伏预算(需要全窗口). **参考:** 切维涅和川原, ["YIN,语言和音乐的基本频率估计器"](https://doi.org/10.1121/1.1458024)2002年日本航天局. **复杂性 :** $O(N^2/4)$-两个被窝过半个窗口. ## 麦克莱德 **McLeod & Wyvill, 2005 (英语).** 正常的平方差异与更聪明的峰取。处理更小的窗口——有利于紫外线和快投子变化. ```js import mcleod from '@audio/pitch-mcleod' let result = mcleod(samples, { fs: 44100 }) ``` | 参数 | 默认 | | | --- | --- | --- | | `fs` | `44100` | 样本率(赫兹) | | `threshold` | `0.9` | 峰值选择阈值为全球最大值的分数 | **使用时 :** Vibrato跟踪,小跳大小,唱出YIN偶尔会双打出的声音. **不为:** 高噪音信号(NSDF的阈值低于YIN的CMND). **参考:** (原始内容存档于2018-10-21). McLeod & Wyvill,, ["找到投球的更聪明的方法"](https://www.cs.otago.ac.nz/research/publications/oucs-2008-03.pdf), ICMC 2005 (中文(简体) ). **复杂性 :** $O(N^2/4) 美元——与YIN相同的不对称费用. ## pYIN (英语) **Mauch & Dixon, 2014 (英语).** 概率YIN——以比他(2,18)之前加权的多阈值运行YIN,产生对候选投子的分布,而不是单一硬取. 比YIN更强壮在模糊的框上. ```js import pyin from '@audio/pitch-pyin' let result = pyin(samples, { fs: 44100 }) // → { freq: 440.1, clarity: 0.92, candidates: [{ freq: 440.1, prob: 0.85 }, ...] } ``` | 参数 | 默认 | | | --- | --- | --- | | `fs` | `44100` | 样本率(赫兹) | | `minFreq` | `50` | 最小可探测频率(Hz) | | `maxFreq` | `2000` | 最大可探测频率 (Hz) | 在一系列框架上, `track` 运行 pYIN 的第二阶段和 `notes` 将结果分为: ```js import { track, notes } from '@audio/pitch-pyin' let { times, f0, voiced, prob } = track(samples, { fs: 44100 }) // frame i at i·hopSize/fs, f0 0 where unvoiced let events = notes(samples, { fs: 44100 }) // → [{ time, duration, freq, midi, clarity }, ...] let write = notes({ fs: 44100 }) // streaming, track too write(block) // → the notes finished so far write() // → the rest ``` | 参数 | 默认 | | | --- | --- | --- | | `frameSize` | `2048` 在44.1千赫时 | 框架(样本):2的最短功率,其YIN窗口有一段时期 `minFreq` | | `hopSize` | `256` 在44.1千赫时 | 跳(样本), 5.8毫秒 | | `lag` | `4096` | 决定每个框架的框架:流最多在输入后如此之多 | | `minDuration` | `0.1` | `notes`: 保存最短音符(s) | | `candidates` | 阳哥 | 第一阶段:HMM的另一个观测模型,例如: [`@audio/neural-pitch`](https://github.com/audiojs/neural/tree/main/packages/neural-pitch)是因为 | `track` Viterbi-decodes pYIN的发音为HMM. 国家是0.1-Semitone bines from `minFreq` 改为 `maxFreq`,发音或未发音;发音动能为每秒35.92八分之多,开出有0.01概率的开关(librosa.pyin的默认). 声音状态占用了候选人的一半概率(Vamp插件) `yinTrust`),它保持了未发声路径的开通,因此音符之间的跳跃不会被八分之一的去掉. 一旦每条维特比路径都同意, 或者,如果它们没有在其中达到 `lag` 框,沿着最佳路径(固定的lag解码,作为 pYIN Vamp 插件):内存在任意长度上保持被约束,并有短的流 `lag` 决定每个框架在其输入后有一个固定的间隔。反对librosa.pyin 1.0:差异函数为YIN自己的(librosa0-expends the frame,它拉出低音速尖锐),候选人在一个宾加分中,以及 `f0` 是解码的垃圾桶内的候选人,而不是垃圾桶中心. `notes` 是托尼的注解模型,带有pYIN Vamp插件的参数和输出:攻击,平稳和无声状态,每半音为3发. Vibrato和一勺入个音符留在里面; 同样的音符再次启动一个新的音符, 电平在两个框内上升了1/0.7倍; 一个快滑翔机在它的尾端与音符相接, 通过音符缓慢的一步. `freq` 是音符框的中位点, `clarity` 他们表示的概率. `candidates` 替换第1阶段,并保留HMM和音符模型。它已经 `candidates.js`签名 : `(frameSize, fs, minFreq, maxFreq) → run`时 `run(frame)` 填充后返回候选人数 `run.freq`, (中文(简体) ), `run.prob` (每个候选人的投出概率最多1个)和 `run.rms` (音符读取水平); `run.frameSize` 财务报告和审定财务报表 `run.lead` 设定一个框架有多少样本,其中有多少样本在时间之前。没有它,输出是相同的,bit for bit. **使用时 :** 模糊的内容——有气息的相声,有吵闹的录音,或者当你需要一个投出后音进行下游HMM跟踪时. 语音或独奏乐器的美乐德:用发音平滑的f0(`track`页:1`notes`) (中文(简体) ). **不为:** 多声音频:每帧一发. **参考:** 毛奇和狄克逊, ["pYIN:使用概率阈值分布的基本频率估计器"](https://doi.org/10.1109/ICASSP.2014.6853678), ICASSP 2014 (英语). 毛奇等编;, ["电脑辅助的Melody Note 使用托尼软件转录:准确性和效率"](https://www.tenor-conference.org/proceedings/2015/04-Mauch-Tony.pdf),TENOR 2015 (英语). ## 自动连接常态化自相通——最简单的投管估计器. 教育基线. ```js import autocorrelation from '@audio/pitch-autocorrelation' let result = autocorrelation(samples, { fs: 44100 }) ``` | 参数 | 默认 | | | --- | --- | --- | | `fs` | `44100` | 样本率(赫兹) | | `threshold` | `0.5` | 要接受的最小常态自动连接值 | **使用时 :** 学习,快原型,信号具有强烈的主导周期和低噪音. **不为:** 生产——八进制出错常见,没有额外的休克. **参考:** 拉比纳, ["使用自動相關分析来进行投出检测"](https://doi.org/10.1109/TASSP.1977.1162905)IEEE TASSP 1977 (英语). **复杂性 :** $O(N^2/4) $. ## AMDF (法语) **罗斯等,1974.** 平均磁差函数——YIN的经典前身. 衡量一个信号与其延迟复制之间的平均绝对差;微型表示周期. ```js import amdf from '@audio/pitch-amdf' let result = amdf(samples, { fs: 44100 }) ``` | 参数 | 默认 | | | --- | --- | --- | | `fs` | `44100` | 样本率(赫兹) | | `minFreq` | `50` | 最小可探测频率(Hz) | | `maxFreq` | `2000` | 最大可探测频率 (Hz) | | `threshold` | `0.3` | AMDF 调试阈值 | **使用时 :** 低复杂环境,嵌入式系统. 比YIN更简单,更便宜(没有僵硬,没有累积正常化). **不为:** 噪声信号——缺乏YIN累积正常化,抑制了八分之差. **参考:** 罗斯等人, [“平均星等差函数波段提取器”](https://doi.org/10.1109/TASSP.1974.1162598)IEEE TASSP 1974 (英语). **复杂性 :** $O(N^2/4) $. * * * ## HPS 软件 **施罗德,1968年.** 口琴产品相谱——以下取样的相谱相乘,使口琴峰与基本相接. 强取所失根本相. ```js import hps from '@audio/pitch-hps' let result = hps(samples, { fs: 44100 }) ``` | 参数 | 默认 | | | --- | --- | --- | | `fs` | `44100` | 样本率(赫兹) | | `harmonics` | `5` | 口琴产品数量 | | `minFreq` | `50` | 最小可探测频率(Hz) | | `maxFreq` | `4000` | 最大可探测频率 (Hz) | | `cents` | `10` | 候选人间距(百分数) | | `threshold` | `0.1` | 接受的最低限度明确性 | **使用时 :** 发音丰富的信号(吉他,钢琴,青铜). 自然会处理缺失的基本问题. **不为:** 纯鼻音(只有一发口音),信号非常响亮. **参考:** 施罗德, ["纯直方图和产品谱"](https://doi.org/10.1121/1.1910902)(原始内容存档于2013-10-12). JASA 1968. **要求:** 2号车窗长度. ## 积分 **Noll, 1967 (英语).** 真实 cepstrum - $c(\\tau) =\\text{IFFT}(\\log {text{FFT}(x)}\\$. 在 quefrency $\\tau$ 对应于时间域中的 $\\tau$ . ```js import cepstrum from '@audio/pitch-cepstrum' let result = cepstrum(samples, { fs: 44100 }) ``` | 参数 | 默认 | | | --- | --- | --- | | `fs` | `44100` | 样本率(赫兹) | | `minFreq` | `50` | 最小可探测频率(Hz) | | `maxFreq` | `2000` | 最大可探测频率 (Hz) | | `threshold` | `0.3` | 接受的最低限度明确性 | **使用时 :** 谐波信号,你想要一个干净的光谱域方法。良好的教学补充时间域算法. **不为:** 低投放信号(紧急分辨率受窗口长度的限制). **参考:** 诺尔, ["Cepstrum pitch definition" (Cepstrum pitch definition) (英语:Cepstrum pitch definition) (美国英语)](https://doi.org/10.1121/1.1911537)(原始内容存档于2014-10-12). JASA 1967. **要求:** 2号车窗长度. ## 系统 **Camacho & Harris, 2008 (英语).** SWIPE'(Sawtooth Waveform Inspirted Pitch Estimator,主口琴). 测量出窗口和锯齿模板之间的光谱相似性,其叶子坐落在正弦. 比HPS更准确处理干净的器件信号;强力防八进制出错,因为只有主口琴才有助. 简化单窗形式:使用一个FFT来代替原纸的多分辨率高音金字塔——足够固定窗. ```js import swipe from '@audio/pitch-swipe' let result = swipe(samples, { fs: 44100 }) ``` | 参数 | 默认 | | | --- | --- | --- | | `fs` | `44100` | 样本率(赫兹) | | `minFreq` | `60` | 最小可探测频率(Hz) | | `maxFreq` | `4000` | 最大可探测频率 (Hz) | | `cents` | `10` | 候选人间距(百分数) | | `threshold` | `0.15` | 接受的最低限度明确性 | **使用时 :** 干净的器械信号,录音室录音,其中子Hz精度很重要. **不为:** 非常吵闹或具有反响的信号(单一窗口形式缺乏全SWIPE'的多分辨率强性). **参考:** 卡马乔和哈里斯, ["锯齿波形启发了语音和音乐的投影估计器"](https://doi.org/10.1121/1.2951592)(原始内容存档于2008-10-12)., JASA 2008. **要求:** 2号车窗长度. * * * ## 比较 ### Pitch 算法 | | 阳 | 麦克莱德 | pYIN (英语) | AMDF (法语) | HPS 软件 | 积分 | 系统 | | --- | --- | --- | --- | --- | --- | --- | --- | | **域名** | 时间 | 时间 | 时间 | 时间 | 光谱 | 光谱 | 光谱 | | **准确性** | ★★★★★ | ★★★★ | ★★★★★ | ★★★ | ★★★★ | ★★★ | ★★★★★ | | **噪音强度** | ★★★★★ | ★★★★ | ★★★★★ | ★★★ | ★★★ | ★★★ | ★★★★ | | **八进制错误** | 罕见 | 罕见 | 罕见 | 常见 | 罕见 | 偶尔 | 罕见 | | **缺少基本内容** | 没有 | 没有 | 没有 | 没有 | 对 | 对 | 对 | | **最小窗口** | ~4个时期 | ~2个时期 | ~4个时期 | ~4个时期 | 2 功率 | 2 功率 | 2 功率 | | **最好还是** | 常规 | 紫外线 | 含糊不清 | 内嵌 | 口琴丰富 | 教学 | 工作室 | ## 另见 - [四进制](https://github.com/scijs/fourier-transform) ——光谱算法使用的FFT - [米尔](https://github.com/audiojs/mir) ——染色体,和弦,键,旋律,结构,指纹 - [节拍](https://github.com/audiojs/beat) 发作探测、节奏估计、节拍跟踪 - [数字过滤器](https://github.com/audiojs/digital-filter) ——过滤器设计和处理 - [缩放](https://github.com/audiojs/stretch) - 时间拉伸和投出变化 - [调动](https://github.com/audiojs/shift) ——投出相变算法 ## 常见问题 ### @audio/pitch 是什么？ Pitch 检测 — @ audio/ pitch- \* 原子的雨伞$ YIN, pYIN, McLeod, HPS, cepstrum, SWIPE, 自动脉冲, AMDF$ ### 如何安装 @audio/pitch？在项目目录运行 npm install @audio/pitch，或使用 pnpm add / yarn add / bun add。 ### @audio/pitch 支持 TypeScript 吗？支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @audio/pitch 支持 ESM 还是 CommonJS？以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require 不含顶层 await 的 ES Module，更早的版本需要改用动态 import。 ### @audio/pitch 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @audio/pitch 可以商用吗？ @audio/pitch 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @audio/pitch 的下载量有多少？根据 npm 官方下载统计，@audio/pitch 在 2026/10/07 – 2026/11/05 这 30 天内被下载 1,731 次，日均约 58 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @audio/pitch 还在维护吗？最新版本 2\.2\.0 发布于 2026/10/18（23 天前）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2026/07/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。