短时傅里叶分析与基频追踪在鸿蒙PC上的实现:Praat 语谱图绘制、TextGrid 区间标注及测量结果导出
在语音分析里,“看一眼波形”“读出一段基频”“标出一段区间”是三件需要分别落地的事。本项目围绕这三件事,使用 Electron 壳与纯 JavaScript 实现 WAV 二进制解析、短时傅里叶语谱、归一化自相关基频追踪、强度与停顿测量、TextGrid 区间标注与测量表导出,并以三列工作区把结果落到同一条时间轴上。本文依据实际业务源码、当前鸿蒙工程配置和三张应用截图,梳理音频如何从磁盘进入画布、基频与测量结果如何计算,以及标注、导出与路径授权上需要提前说清的边界。
这是一套独立编写的 JavaScript 壳应用,不是把上游 Praat 及其脚本语言、语音合成与完整分析算法族移植到鸿蒙。本文执行了 JavaScript 语法检查、三份内置样例的引擎级读取与计算、TextGrid 往返与重叠插入的纯函数验证;没有运行 Electron 界面,没有构建 HAP,没有安装到设备,也没有使用真实录音或用户目录做测试。
欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
AtomGit 仓库地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_Praat
说明:文中代码包含源码节选;未展示完整函数、对象或条件分支的片段需要结合原始上下文阅读,不能独立运行。
一、技术架构分析
1.1 整体架构
项目由鸿蒙工程、Electron 主进程、渲染层与五个业务引擎组成:
- 鸿蒙工程:electron 是 entry 模块,依赖 web_engine HAR;业务资源位于 web_engine 的 resources/app 目录。
- 主进程:负责窗口、文件对话框、音频与文本读写、路径授权、剪贴板、偏好与会话持久化。
- 渲染层:维护音频对象、视图窗口、选区、光标、语谱、基频、强度、标注网格与七个工作面板。
- 纯函数引擎:PPWav 处理 RIFF/WAVE 编解码,PPFft 处理窗函数与短时谱,PPPitch 处理基频,PPMeasure 处理强度与统计,PPTextGrid 处理区间层。
主要数据链路如下:
WAV 文件
↓ files:choose / samples:list → fs:readBinary(返回 base64)
PPWav.parse → { 采样率, 声道, 位深, 帧数, data[], mono }
↓
PPFft.spectrogram → 帧 × 频点 dB 矩阵 → ImageData → canvas
PPPitch.track → 时间 / F0 / 自相关强度 → 折线轨迹
PPMeasure.intensity + silences → 强度包络与停顿区间
↓ 选区(画布拖拽 / 数值输入 / 停顿定位 / 标注行点击)
PPMeasure.summarize → 测量表 CSV / TextGrid / WAV 片段
↓ file:saveText / fs:writeText / fs:writeBinary
用户目录:PraatPrefs.json(偏好与授权根)、PraatSession.json(会话快照)
页面里没有语音识别、共振峰提取或脚本自动化。画布上呈现的是本机采样数据的幅度、频谱与自相关结果,不包含上游软件的 Praat Script 执行环境,也不包含 TextGrid 的二进制或数据库格式。
1.2 技术方案
| 需求 | 当前实现 | 能力边界 |
|---|---|---|
| 音频读取 | RIFF/WAVE 分块解析,PCM 8/16/24/32 位与 IEEE 浮点 32/64 | 只接受 .wav/.wave,不解析 MP3、FLAC、Ogg |
| 频谱展示 | 基 2 FFT + Hann 窗,默认 25 ms 窗 / 10 ms 步 | 是显示与分析用短时谱,不是听觉滤波器组模型 |
| 基频估计 | 归一化自相关 + 两步取峰 + 抛物线插值 + 相邻帧倍频修正 | 单声部基频,不含共振峰或性别自适应判据 |
| 声学测量 | RMS、峰值、dBFS、过零率、停顿合并、强度直方图 | 强度由均方根折算,不是等响度或 A 计权 |
| 标注 | 区间层 TextGrid 长格式读写,空档自动补齐 | 不支持 PointTier,也没有多区间层并行编辑 |
| 导出 | 测量表 CSV、TextGrid、选区 WAV 片段 | 不生成其它分析软件的工程或数据库格式 |
| 桌面交互 | HTML、CSS Grid、Canvas 2D 与自定义浮层 | Electron 与鸿蒙壳仍是必需运行环境 |
| 分发形态 | electron entry + web_engine HAR 工程 | 当前配置存在模板标识,不能等同已满足发布条件 |
这条路线把可移植的信号处理集中到 engines 目录,使算法的每一帧都能在 Node 中独立复算;窗口、文件授权、设备音频输出这些部分,则保留给对应运行环境验收。
1.3 核心功能清单
| 模块 | 已接入的功能 |
|---|---|
| 文件与信息 | 三个内置样例、打开 WAV、按目录扫描首个音频、采样率/声道/位深/帧数/时长/编码/峰值与 RMS |
| 波形与语谱 | 波形列渲染、0–5000 Hz 语谱、基频轨迹、播放与播放选区、缩放平移、选区快照 |
| 基频分析 | 五参数、整段轨迹、浊音率与均值中位范围、前 40 帧采样表、轨迹 CSV |
| 声学测量 | 停顿检测(阈值与最短时长)、区间与全文测量、强度直方图、停顿表与定位 |
| 区间标注 | 用选区新建区间、改名、删除、清空、导入导出 TextGrid、空档补齐 |
| 导出 | 全文/选区/标注三种范围 × CSV、TextGrid、WAV 三种格式,复制到剪贴板、定位文件 |
| 配置与诊断 | 运行环境、读取上限、授权目录撤销、偏好持久化、会话保存与恢复 |
二、环境准备
2.1 开发环境要求
本文的实际验证环境是 Windows 22H2 与 Node.js v22.20.0。工程侧的要求来自当前配置文件:
- 构建入口为 ohos_hap 目录,使用 DevEco Studio 打开。
- build-profile.json5 中 compatibleSdkVersion 为 5.0.5(17),compatibleSdkVersionStage 为 release,runtimeOS 为 HarmonyOS。
- 原生库收集方式为 collectAllLibs,即把 electron 模块目录下的原生库一并打进产物。
- electron/src/main/module.json5 的 deviceTypes 为 2in1 与 tablet,入口 Ability 为 EntryAbility,launchType 为 specified。
- 渲染层通过 nodeIntegration 获取 Node 能力,因此业务代码可以直接 require electron,不需要预加载脚本转发。
在主进程一侧,业务只依赖 Electron 与 Node 内置模块,没有额外 npm 运行时依赖。
2.2 项目结构
业务资源平铺在 HAR 的资源目录下,结构如下:
ohos_Praat_electron-main/
├── lib.unstripped/ # 未裁剪的原生库(libadapter.so、libelectron.so)
└── ohos_hap/
├── AppScope/ # bundleName、版本、图标与标签
├── electron/ # entry 模块,依赖 web_engine
└── web_engine/ # HAR 模块,声明权限并提供资源目录
└── src/main/resources/resfile/resources/app/
├── main.js # 主进程:窗口 + 17 条 IPC + 路径授权
├── index.html # 七面板、三列布局、脚本装载顺序
├── renderer.js # 状态、绘制、交互、导出与会话
├── package.json # 业务入口声明
├── engines/
│ ├── pp-wav.js # RIFF/WAVE 解析与编码
│ ├── pp-fft.js # 窗函数、基 2 FFT、语谱、峰值频率
│ ├── pp-pitch.js # 自相关基频与倍频修正
│ ├── pp-measure.js # 强度、停顿、汇总、直方图、CSV
│ └── pp-textgrid.js # 区间层 TextGrid 读写
├── styles/praat.css # Catppuccin Mocha 主题与三列栅格
└── samples/
├── glide-100-200hz.wav
├── noise-tone-440hz.wav
└── vowel-a-120hz.wav
三份样例都是合成信号,参数已知,可以直接用于核对分析结果,这一点在界面提示中也写明。它们同时是应用目录下的固定资源,因此可以被读取,但按现有逻辑不能被“存到音频同目录”覆盖。
2.3 依赖说明
业务 package.json 只有入口与元信息,没有 scripts,也没有 dependencies:
{
"name": "praat",
"version": "1.0.0",
"description": "Praat 语音分析工作台(鸿蒙 PC Electron 壳):WAV 解析、语谱图、基频轨迹、声学测量与 TextGrid 标注",
"main": "main.js",
"author": "ohos_hap",
"license": "GPL-3.0"
}
因为它没有 start 与 test 脚本,不能把“执行 npm start 即可运行”写进步骤。鸿蒙模块一侧的依赖关系在 electron/oh-package.json5 中:
"dependencies": {
"web_engine": 'file:../web_engine',
}
oh-package.json5 只有 @ohos/hypium 1.0.6 这一条测试框架 devDependency,没有业务运行时依赖。也就是说,音频解析、频谱、基频、测量和 TextGrid 全部由前面列出的五个引擎在 JavaScript 层完成,没有借用第三方 DSP 库或原生音频库。
三、核心适配流程
3.1 主进程实现:窗口、17 条 IPC 与路径授权
主进程保存全部体积上限与扩展名白名单,界面上的“读取上限”卡片直接展示这些常量:
/* ---------- 上限常量(配置与诊断面板原样展示) ---------- */
var MAX_AUDIO_BYTES = 64 * 1024 * 1024; /* 单个音频读取上限 64MB */
var MAX_TEXT_BYTES = 8 * 1024 * 1024; /* 文本(TextGrid/CSV)上限 8MB */
var MAX_SCAN_ENTRIES = 4000; /* 目录扫描最多 4000 条 */
var READ_DEFAULT_BYTES = 8 * 1024 * 1024; /* 未指定上限时默认 8MB */
var WINDOW_TITLE = 'Praat 语音分析工作台';
var PREFS_FILE = 'PraatPrefs.json';
var SESSION_FILE = 'PraatSession.json';
var PREFS_DENY = { allowedRoots: 1, lastDir: 1 };
var AUDIO_EXTS = ['.wav', '.wave'];
var TEXT_EXTS = ['.textgrid', '.csv', '.tsv', '.txt', '.json'];
17 条 IPC 全部注册在一个同步包装器里,成功与失败都由该包装器统一成结构化对象,避免渲染层处理裸异常:
function handle(channel, fn) {
ipcMain.handle(channel, function (event, req) {
try {
return fn(req || {});
} catch (e) {
return { success: false, error: errText(e), code: e && e.code };
}
});
}
通道清单如下,序号与源码注释一致:
| 序号 | 通道 | 作用 | 是否过 guard |
|---|---|---|---|
| 1 | app:info | 版本、运行时、目录、上限、授权根 | 否 |
| 2 | dir:choose | 目录对话框,成功后授权该目录 | 否(授权入口) |
| 3 | dir:forget | 撤销授权,内置目录不可撤销 | 否 |
| 4 | fs:scan | 按扩展名与深度扫描目录 | 是 |
| 5 | fs:readText | 读 TextGrid/CSV,带编码识别 | 是 |
| 6 | fs:writeText | 写文本,可选 UTF-8 BOM | 是 |
| 7 | fs:readBinary | 读音频并返回 base64 | 是 |
| 8 | fs:writeBinary | 写 base64 二进制 | 是 |
| 9 | files:choose | 多选文件对话框,授权所在目录 | 否(授权入口) |
| 10 | file:saveText | 另存为,支持文本与 base64 | 否(保存后授权目录) |
| 11 | clip:write | 写剪贴板并返回字符数 | 否 |
| 12 | shell:reveal | 在文件管理器中定位 | 是 |
| 13 | prefs:get | 读偏好文件 | 否 |
| 14 | prefs:set | 写偏好,剔除独占键 | 否 |
| 15 | session:save | 写会话快照 | 否 |
| 16 | session:load | 读会话快照 | 否 |
| 17 | samples:list | 列出内置样例 | 否 |
路径授权采用“前缀包含”判定,Windows 下大小写归一,去掉一个尾部斜杠后再比较:
function isInside(child, parent) {
var c = normForCompare(child), p = normForCompare(parent);
if (!c || !p) return false;
return c === p || c.indexOf(p + '/') === 0;
}
function isAllowed(p) {
var full = fwd(path.resolve(String(p || '')));
for (var i = 0; i < allowedRoots.length; i++) {
if (isInside(full, allowedRoots[i])) return true;
}
return false;
}
授权根与偏好同处 PraatPrefs.json,但写入方向是单向的:主进程通过 saveRoots 维护 allowedRoots,渲染层通过 prefs:set 写入时会被 PREFS_DENY 拦下。启动恢复时只接受仍然存在的目录,且不做向上放宽:
/* 只恢复仍然存在的目录;不放宽到上一级,避免把整盘授权出去 */
function restoreRoots() {
var saved = readJson(prefsPath(), {}).allowedRoots;
if (!Array.isArray(saved)) return;
saved.forEach(function (r) {
var full = fwd(r || '');
if (!full) return;
try { if (!fs.statSync(full).isDirectory()) return; } catch (e) { return; }
rememberRoot(full, true);
});
}
读音频是本项目最关键的一条通道,它把文件字节整体转成 base64 交给渲染层解析:
/* 7. 读音频二进制(返回 base64,渲染层自行解析 WAV) */
handle('fs:readBinary', function (req) {
var file = fwd(req.path || '');
if (!file) return { success: false, error: '缺少 path 参数' };
guard(file);
var st;
try { st = fs.statSync(file); } catch (e) { return { success: false, error: '文件不存在:' + file }; }
if (!st.isFile()) return { success: false, error: '不是文件:' + file };
var cap = clampInt(req.maxBytes, 1024, MAX_AUDIO_BYTES, MAX_AUDIO_BYTES);
if (st.size > cap) {
return {
success: false,
error: '音频 ' + (st.size / 1048576).toFixed(2) + 'MB 超过单次读取上限 ' + (cap / 1048576).toFixed(0) + 'MB'
};
}
var buf = fs.readFileSync(file);
return {
success: true,
path: file,
name: path.basename(file),
bytes: buf.length,
base64: buf.toString('base64')
};
});
之所以选择 base64 而不是直接传 Buffer,是因为渲染层与主进程之间只能传结构化可序列化对象。代价也要写清楚:一段 64 MB 的上限音频在传递过程中会同时存在原始 Buffer、约 85 MB 的 base64 字符串,以及渲染层再解码出的 Uint8Array,之后还要生成 Float32Array 声道数组。内存峰值明显高于文件本身,这是大文件读取慢或失败时需要优先检查的地方。
窗口创建集中在 createWindow 中,尺寸按主显示器工作区比例计算:
function createWindow() {
try {
var display = screen.getPrimaryDisplay();
var width = display.workAreaSize.width;
var height = display.workAreaSize.height;
mainWindow = new BrowserWindow({
width: Math.floor(width * 0.92),
height: Math.floor(height * 0.86),
minWidth: 1024,
minHeight: 660,
frame: true,
transparent: false,
resizable: true,
backgroundColor: '#1e1e2e',
title: WINDOW_TITLE,
webPreferences: {
nodeIntegration: true,
contextIsolation: false
}
});
mainWindow.loadFile('index.html');
mainWindow.on('closed', function () { mainWindow = null; });
} catch (e) {
console.warn('[Praat] 创建窗口失败:', String(e && e.message));
}
}
启动链在注册 IPC 之前先写入两个内置授权根,再恢复历史授权:
app.whenReady().then(function () {
rememberRoot(fwd(app.getPath('userData')), true);
rememberRoot(fwd(__dirname), true);
restoreRoots();
registerIpc();
createWindow();
app.on('activate', function () {
if (BrowserWindow.getAllWindows().length === 0) createWindow();
});
});
两个内置根分别是用户数据目录与应用目录。前者用于偏好与会话,后者用于内置样例;dir:forget 会对这两个目录直接返回“内置目录不能撤销授权”。
3.2 七面板布局与选区状态
渲染层的全部运行时状态集中在一个对象里,包括音频、视窗、选区、光标、四类分析结果、标注网格与导出选项:
var S = {
audio: null, /* { name, path, sampleRate, channels, bits, frames, duration, mono, warnings } */
view: { start: 0, end: 1 },
sel: { start: 0, end: 0, active: false },
cursor: 0,
spec: null,
pitch: null,
intensity: null,
hist: null,
grid: null,
tierRow: -1,
samples: [],
env: null,
prefs: {},
lastExport: '',
exp: { scope: 'all', fmt: 'csv' },
audioCtx: null,
source: null,
playing: false,
drag: null,
panel: 'file'
};
三个画布共用同一套坐标换算,视图窗口以秒为单位保存,滚轮缩放以鼠标位置为锚点:
function viewSpan() { return Math.max(0.0005, S.view.end - S.view.start); }
function timeToX(t, w) { return (t - S.view.start) / viewSpan() * w; }
function xToTime(x, w) { return S.view.start + (x / Math.max(1, w)) * viewSpan(); }
面板切换用一个映射表延迟渲染,避免在隐藏状态下测量画布宽度:
var PANEL_RENDER = {
file: function () { renderInfo(); },
editor: function () { redrawAll(); },
pitch: function () { renderPitchStats(); },
measure: function () { renderMeasure(); drawHist(); },
tier: function () { renderTier(); },
export: function () { refreshExport(); },
config: function () { renderConfig(); }
};
function showPanel(name) {
S.panel = name;
document.querySelectorAll('.nav-item').forEach(function (b) {
b.classList.toggle('active', b.getAttribute('data-panel') === name);
});
document.querySelectorAll('.panel').forEach(function (p) {
p.classList.toggle('active', p.id === 'panel-' + name);
});
$('content').scrollTop = 0;
var fn = PANEL_RENDER[name];
if (fn) setTimeout(fn, 0);
}
画布适配同时处理了高 DPI:每次重绘都按 devicePixelRatio 重设位图尺寸并缩放绘图上下文,然后在清晰坐标系里全量重画。波形按像素列取列内极值,因此缩到全览时也不会丢失尖峰:
function fitCanvas(cv, cssH) {
var dpr = window.devicePixelRatio || 1;
var w = Math.max(1, cv.clientWidth || 600);
cv.width = Math.round(w * dpr);
cv.height = Math.round(cssH * dpr);
cv.style.height = cssH + 'px';
var ctx = cv.getContext('2d');
ctx.scale(dpr, dpr);
ctx.clearRect(0, 0, w, cssH);
return { ctx: ctx, w: w, h: cssH };
}
ctx.fillStyle = cssVar('--wave');
var per = Math.max(1, (i1 - i0) / w);
for (var x = 0; x < w; x++) {
var s0 = Math.floor(i0 + x * per);
var s1 = Math.min(i1, Math.floor(i0 + (x + 1) * per) + 1);
var min = 1, max = -1;
for (var i = s0; i < s1; i += 1) {
var v = mono[i];
if (v < min) min = v;
if (v > max) max = v;
}
if (min > max) { min = 0; max = 0; }
var y1 = mid - max * amp;
var y2 = mid - min * amp;
ctx.fillRect(x, y1, 1, Math.max(1, y2 - y1));
}
选区交互区分“点击定位”和“拖拽选区”:指针位移超过 2 像素才进入选区状态,并且要求选区长度超过 0.0005 秒才算有效,避免把单击误判成零长度选区:
cv.addEventListener('pointermove', function (e) {
if (!S.drag || !S.audio) return;
var rect = S.drag.rect;
var t = xToTime(e.clientX - rect.left, rect.width);
t = Math.max(0, Math.min(S.audio.duration, t));
if (Math.abs(e.clientX - S.drag.x0) > 2) {
S.sel.start = Math.min(S.drag.t0, t);
S.sel.end = Math.max(S.drag.t0, t);
S.sel.active = S.sel.end - S.sel.start > 0.0005;
S.cursor = t;
}
if (S.panel === 'editor') { redrawAll(); updateDock(); }
});
选区确定后既会回填两个输入框,也会立刻触发一次 summarize,因此“选区快照”里的时长、均方根、平均强度与平均基频始终与当前选区同步。缩放范围下限是 0.005 秒,按住 Shift 滚轮改为平移 10% 视窗,全览按钮把视图重置为 0 到时长。
3.3 WAV 解析与语谱图绘制
WAV 解析走的是标准的 RIFF 分块遍历,先校验魔数,再逐块记录 fmt 与 data 的偏移和长度:
/* 解析 WAV:返回 { ok, sampleRate, channels, bits, format, frames, duration, data[], warnings[] } */
function parse(input) {
var u8 = input instanceof Uint8Array ? input : new Uint8Array(input);
if (!u8 || u8.length < 44) return fail('文件太小,不是有效的 WAV(至少 44 字节)');
var dv = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
if (tag(dv, 0, 4) !== 'RIFF' || tag(dv, 8, 4) !== 'WAVE') {
return fail('不是 RIFF/WAVE 文件,本应用只解析 .wav');
}
var pos = 12, fmtOff = -1, fmtSize = 0, dataOff = -1, dataLen = 0, warnings = [];
while (pos + 8 <= u8.length) {
var id = tag(dv, pos, 4);
var size = dv.getUint32(pos + 4, true);
var body = pos + 8;
if (id === 'fmt ') { fmtOff = body; fmtSize = size; }
else if (id === 'data') {
dataOff = body;
dataLen = Math.min(size, u8.length - body);
if (size === 0 || size > u8.length - body) {
if (size > u8.length - body) warnings.push('data 块声明长度超过文件实际长度,按实际长度读取');
dataLen = u8.length - body;
}
}
if (size === 0 && id !== 'fmt ') break;
pos = body + size + (size % 2);
}
这段遍历对两类常见异常做了处理:data 块声明长度超过文件实际长度时按实际长度读取并记录告警,块长度为 0 且不是 fmt 时直接结束循环,防止在畸形文件上死循环。WAVE_FORMAT_EXTENSIBLE 会读取子格式编号再按 1(PCM)或 3(浮点)继续判断,因此带扩展头的 24 位与 32 位浮点文件也能进入同一条解析路径。
采样读取按位深分派,8 位按无符号加 128 偏置还原,16 到 32 位按满量程归一,浮点直接读取:
function readerFor(fmt, bits) {
if (fmt === 3) {
return bits === 64
? function (dv, u8, o) { return dv.getFloat64(o, true); }
: function (dv, u8, o) { return dv.getFloat32(o, true); };
}
if (bits === 8) return function (dv, u8, o) { return (u8[o] - 128) / 128; };
if (bits === 16) return function (dv, u8, o) { return dv.getInt16(o, true) / 32768; };
位深白名单是 1、2、3、4、8 字节,浮点只接受 32 与 64 位,帧数超过 8 百万帧会截断并写告警。多声道由 toMono 取各声道同一帧的均值混成单声道,界面上也明确写了“多声道会自动混为单声道分析”。
语谱的计算在帧函数里完成去均值、加窗与幅度归一:
/* 单帧幅度谱:返回 0..n/2 的幅度(已按窗长归一) */
function frameMag(mono, start, win, winFn, out) {
var re = new Float32Array(win);
var im = new Float32Array(win);
var mean = 0, i;
var end = Math.min(mono.length, start + win);
for (i = start; i < end; i++) mean += mono[i];
mean = end > start ? mean / (end - start) : 0;
for (i = 0; i < win; i++) {
var v = start + i < mono.length ? mono[start + i] - mean : 0;
re[i] = v * winFn[i];
}
fft(re, im);
var half = win / 2;
var mag = out || new Float32Array(half + 1);
for (var k = 0; k <= half; k++) mag[k] = Math.sqrt(re[k] * re[k] + im[k] * im[k]) / (win / 2);
return mag;
}
窗长会被向上取到 2 的幂,这一步直接决定频率分辨率。默认 25 ms 窗在 22050 Hz 上对应 551 个样本,取到 1024 点后频率间隔为 21.53 Hz;如果直接使用 551 点就无法用基 2 FFT 计算,所以这里用补零换取算法简洁,代价是分辨率不再随窗长线性提高:
var win = nextPow2(Math.max(64, Math.round(sr * winMs / 1000)));
var hop = Math.max(1, Math.round(sr * hopMs / 1000));
var n = mono.length;
if (n < win) {
var pad = new Float32Array(win);
pad.set(mono);
mono = pad;
n = win;
}
var frameCount = Math.floor((n - win) / hop) + 1;
var MAX_FRAMES = 2400;
if (frameCount > MAX_FRAMES) {
hop = Math.ceil((n - win) / (MAX_FRAMES - 1));
frameCount = Math.floor((n - win) / hop) + 1;
}
帧数上限 2400 通过加大步长实现,而不是丢帧,所以长音频的语谱会变粗但不会缺尾。语谱着色使用三段线性混色,把 dB 值映射到 0 到 1 之后查表:
function specColor(t) {
var crust = cssVar('--crust');
var blue = cssVar('--blue');
var peach = cssVar('--peach');
var yellow = cssVar('--yellow');
function mix(a, b, k) {
var ar = parseInt(a.slice(1, 3), 16), ag = parseInt(a.slice(3, 5), 16), ab = parseInt(a.slice(5, 7), 16);
var br = parseInt(b.slice(1, 3), 16), bg = parseInt(b.slice(3, 5), 16), bb = parseInt(b.slice(5, 7), 16);
return [Math.round(ar + (br - ar) * k), Math.round(ag + (bg - ag) * k), Math.round(ab + (bb - ab) * k)];
}
if (t < 0.5) return mix(crust, blue, t * 2);
if (t < 0.8) return mix(blue, peach, (t - 0.5) / 0.3);
return mix(peach, yellow, (t - 0.8) / 0.2);
}
绘制时逐像素反查时间与频点,先按视窗换算帧号,再把纵坐标映射到频点,颜色由动态范围 70 dB 归一得到:
var img = ctx.createImageData(w, h);
var data = img.data;
var dyn = PPFft.clampNum($('specRange').getAttribute('data-dyn') || 70, 20, 120, 70);
var codeCache = [];
for (var ci = 0; ci <= 100; ci++) codeCache.push(specColor(ci / 100));
for (var x = 0; x < w; x++) {
var t = xToTime(x + 0.5, w);
var fr = Math.round((t * a.sampleRate - sp.win / 2) / sp.hop);
if (fr < 0) fr = 0;
if (fr >= sp.frameCount) fr = sp.frameCount - 1;
var row = sp.db[fr];
for (var y = 0; y < h; y++) {
var bin = Math.round((1 - (y + 0.5) / h) * (sp.binCount - 1));
var v = row[bin];
var t01 = PPFft.normDb(v, sp.maxDb, dyn);
var col = codeCache[Math.min(100, Math.max(0, Math.round(t01 * 100)))];
var o = (y * w + x) * 4;
data[o] = col[0];
data[o + 1] = col[1];
data[o + 2] = col[2];
data[o + 3] = 255;
}
}
ctx.putImageData(img, 0, 0);
这里有两个固定值需要说明。一是语谱上限在调用处写死为 5000 Hz,界面标签“语谱(0–5000 Hz)”由返回值填充:
function computeSpec() {
var a = S.audio;
if (!a) return;
S.spec = PPFft.spectrogram(a.mono, a.sampleRate, { winMs: 25, hopMs: 10, maxFreq: 5000 });
$('specRange').textContent = Math.round(S.spec.maxFreq);
$('specRange').setAttribute('data-dyn', '70');
}
因为频点只能落在整数位置上,实际可用上限是频点间隔乘以最大频点下标,取整后显示 5000,而频谱对象里的真实上限略低于该值。二是动态范围 70 dB 被写进 data-dyn 属性,界面目前没有对应控件,等于一个固定显示档位,不构成用户可调参数。
3.4 基频追踪:自相关与两步取峰
单帧基频检测是这套引擎里最需要解释的部分。先中心化并求零延迟能量,再在允许的延迟范围内求归一化自相关:
var lagMin = Math.max(2, Math.floor(sr / maxF));
var lagMax = Math.min(n - 2, Math.ceil(sr / minF));
if (lagMax <= lagMin) return { f0: 0, strength: 0 };
var c = new Float32Array(lagMax + 2);
for (var lag = lagMin; lag <= lagMax + 1 && lag < n; lag++) {
var s = 0, count = n - lag;
for (i = 0; i < count; i++) s += x[i] * x[i + lag];
c[lag] = (s / count) / (r0 / n);
}
归一化时对每个延迟都按实际参与相乘的样本数取均值,否则延迟越大自相关自然越小,会在低基频处产生系统性偏差。随后是两步取峰,源码注释把两类典型错误写得很清楚:
/* 两步取峰:先找最强峰的强度,再从最短 lag 起找第一个达到其 90% 的峰。
* 直接取全局最大会落到 2 倍周期上(60Hz 边界处被后续范围检查判成清音);
* 直接取第一个过阈值的峰又会命中高次谐波(强度通常只有 0.35 左右),
* 90% 回溯可以同时避开这两类错误。 */
var top = -1, k;
for (k = Math.max(lagMin, 1); k <= lagMax; k++) {
if (c[k] >= c[k - 1] && c[k] >= c[k + 1] && c[k] > top) top = c[k];
}
if (top < 0) return { f0: 0, strength: 0 };
if (top < threshold) return { f0: 0, strength: top };
var best = -1;
for (k = Math.max(lagMin, 1); k <= lagMax; k++) {
if (c[k] >= c[k - 1] && c[k] >= c[k + 1] && c[k] >= top * 0.9) { best = k; break; }
}
if (best < 0) return { f0: 0, strength: top };
var strength = c[best];
var a = c[best - 1], b = c[best], d = c[best + 1];
var denom = a - 2 * b + d;
var delta = denom !== 0 ? 0.5 * (a - d) / denom : 0;
if (!isFinite(delta) || Math.abs(delta) > 1) delta = 0;
var f0 = sr / (best + delta);
if (f0 < minF || f0 > maxF) return { f0: 0, strength: strength };
return { f0: f0, strength: strength };
抛物线插值让基频不必落在整数延迟对应的频率上,这对 60 Hz 这类低基频尤其重要,因为相邻延迟之间的频率差会达到数赫兹。最后还有一层跨帧修正,用来处理整数周期选择错误的倍频跳变:
/* 相邻帧修正:跳跃接近一倍频程时,取半/倍中更接近上一有效帧的值 */
function octaveFix(f0) {
var prev = 0;
for (var i = 0; i < f0.length; i++) {
if (f0[i] <= 0) continue;
if (prev > 0) {
var ratio = f0[i] / prev;
if (ratio > 1.85 && ratio < 2.15) f0[i] = f0[i] / 2;
else if (ratio > 0.46 && ratio < 0.55) f0[i] = f0[i] * 2;
}
prev = f0[i];
}
}
整段追踪在采样率不低于 16000 Hz 时先做 2:1 抽取,把自相关的乘法量减半,代价是可用带宽减半,因此只适合 500 Hz 上下的基频范围:
var winMs = clampNum(opts.winMs, 20, 100, DEFAULTS.winMs);
var hopMs = clampNum(opts.hopMs, 5, 40, DEFAULTS.hopMs);
var maxFrames = 1200;
var sig = mono, rate = sr;
if (sr >= 16000) { sig = decimate2(mono); rate = sr / 2; }
抽取采用相邻两点平均,属于最简单的两点平均低通,不是抗混叠滤波器。对基频检测而言,只要基频远低于新的奈奎斯特频率就不影响结论,但如果把这段代码用于宽带频谱分析就会失真,两者不能混用。
运行时参数经过钳位后再传入引擎,上限小于下限时自动抬高上限并回写输入框,避免出现静默的空结果:
function pitchParams() {
var a = S.audio;
var win = clampNum($('inPitchWin').value, 20, 100, 40);
var hop = clampNum($('inPitchHop').value, 5, 40, 10);
var minF = clampNum($('inPitchMin').value, 40, 500, 60);
var maxF = clampNum($('inPitchMax').value, 80, 1000, 500);
var thr = clampNum($('inPitchThr').value, 0.05, 0.95, 0.3);
if (maxF <= minF) { maxF = minF + 40; $('inPitchMax').value = maxF; }
return { winMs: win, hopMs: hop, minF: minF, maxF: maxF, threshold: thr };
}
需要注意界面控件的取值范围比引擎的钳位区间更窄:输入框上基频下限只允许 40 到 500、上限只允许 80 到 1000,而引擎内部对 minF 的钳位区间是 40 到 1000、对 maxF 是 60 到 2000。也就是说界面已经先行限制了可选范围,引擎的兜底只在被其它调用方直接传入参数时才生效。实际使用时以“上限必须大于下限”为准,改完参数后要重新运行一次分析才会生效。
3.5 声学测量、停顿检测与直方图
强度包络按帧计算均方根并折算 dBFS,帧数超过 4000 时同样通过加大步长压缩:
/* 强度包络:dBFS,0 表示满刻度 */
function intensity(mono, sr, opts) {
opts = opts || {};
var winMs = clampNum(opts.winMs, 10, 100, 25);
var hopMs = clampNum(opts.hopMs, 2, 40, 10);
var win = Math.max(16, Math.round(sr * winMs / 1000));
var hop = Math.max(1, Math.round(sr * hopMs / 1000));
var n = mono.length;
var count = n <= win ? 1 : Math.floor((n - win) / hop) + 1;
var MAX = 4000;
if (count > MAX) {
hop = Math.ceil((n - win) / (MAX - 1));
count = Math.floor((n - win) / hop) + 1;
}
var times = new Float32Array(count);
var db = new Float32Array(count);
var maxDb = -200;
for (var i = 0; i < count; i++) {
var start = i * hop;
var seg = mono.subarray(start, Math.min(n, start + win));
var v = toDb(rms(seg));
db[i] = v;
if (v > maxDb) maxDb = v;
times[i] = (start + seg.length / 2) / sr;
}
return { times: times, db: db, maxDb: maxDb, winMs: win / sr * 1000, hopMs: hop / sr * 1000 };
}
停顿检测把连续低于阈值的帧合并成区间,并按时间中心扩展半个步长来还原边界。循环条件写成小于等于数组长度,是为了让音频结尾的停顿也能被收尾:
/* 连续低于阈值的帧合并成停顿;最短时长过滤 */
function silences(times, db, thresholdDb, minDurSec) {
var out = [];
if (!times || !times.length) return out;
var th = clampNum(thresholdDb, -120, 0, -40);
var minDur = clampNum(minDurSec, 0.01, 5, 0.1);
var hop = times.length > 1 ? times[1] - times[0] : 0.01;
var start = -1;
for (var i = 0; i <= db.length; i++) {
var quiet = i < db.length && db[i] < th;
if (quiet && start < 0) start = i;
if (!quiet && start >= 0) {
var a = Math.max(0, times[start] - hop / 2);
var b = Math.min(times[db.length - 1] + hop / 2, times[i - 1] + hop / 2);
if (b - a >= minDur) out.push({ start: a, end: b, dur: b - a });
start = -1;
}
}
return out;
}
测量主流程把区间汇总、停顿检测与界面刷新串在一起,并且支持“没有选区时自动改为全文”的降级:
function measure(scope) {
var a = S.audio;
if (!a) { notify('先载入音频', 'err'); return; }
var range = scope === 'sel' && S.sel.active ? { from: S.sel.start, to: S.sel.end } : { from: 0, to: a.duration };
if (scope === 'sel' && !S.sel.active) { notify('还没有选区,已改为测量全文', 'warn'); }
var m = PPMeasure.summarize({ mono: a.mono, sr: a.sampleRate, from: range.from, to: range.to, pitch: S.pitch });
S.measure = m;
var env = ensureIntensity();
var thr = clampNum($('inSilThr').value, -100, -10, -40);
var minDur = clampNum($('inSilDur').value, 20, 2000, 100) / 1000;
var sil = PPMeasure.silences(env.times, env.db, thr, minDur).filter(function (s) {
return s.end > range.from && s.start < range.to;
});
S.silences = sil;
停顿列表的过滤条件是“与当前范围有交集”,因此按选区测量时,跨越选区边界的停顿会被完整保留并整段显示,边界值并不裁到选区之内。这里的取舍是保留真实停顿的完整时长,代价是列表里的起止时间可能超出输入框中的选区范围。
直方图复用同一份强度包络,只取当前范围内的帧,分组数限制在 2 到 40:
var range = currentRange();
var vals = [];
for (var i = 0; i < env.db.length; i++) {
if (env.times[i] >= range.from && env.times[i] <= range.to) vals.push(env.db[i]);
}
var bins = clampNum($('inHistBins').value, 2, 40, 12);
var hist = PPMeasure.hist(vals, bins);
S.hist = hist;
3.6 TextGrid 标注层与导出编码
标注网格的规范化负责三件事:按时间排序、裁剪到 [xmin, xmax]、用空文本补齐空档。这也是 Praat 长格式要求区间必须首尾相连的原因:
/* 排序、裁剪、补齐空档 */
function normalize(g) {
if (!g || !Array.isArray(g.tiers)) return g;
var lo = num(g.xmin, 0), hi = num(g.xmax, 1);
if (hi <= lo) hi = lo + 0.001;
g.xmin = lo; g.xmax = hi;
g.tiers.forEach(function (tier) {
var list = (tier.intervals || []).map(function (it) {
return {
xmin: Math.max(lo, Math.min(hi, num(it.xmin, lo))),
xmax: Math.max(lo, Math.min(hi, num(it.xmax, lo))),
text: it.text == null ? '' : String(it.text)
};
}).filter(function (it) { return it.xmax - it.xmin > EPS; });
list.sort(function (a, b) { return a.xmin - b.xmin || a.xmax - b.xmax; });
var out = [], cursor = lo;
for (var i = 0; i < list.length; i++) {
var it = list[i];
if (it.xmin > cursor + EPS) out.push({ xmin: cursor, xmax: it.xmin, text: '' });
var a = Math.max(cursor, it.xmin);
var b = Math.max(a, it.xmax);
if (b - a > EPS) out.push({ xmin: a, xmax: b, text: it.text });
cursor = Math.max(cursor, b);
}
if (cursor < hi - EPS) out.push({ xmin: cursor, xmax: hi, text: '' });
tier.intervals = out;
tier.xmin = lo;
tier.xmax = hi;
});
return g;
}
插入区间时先切掉与新区间重叠的旧区间,再插入新段并整体规范化。这样后插入的标注不会把先前标注整段吞掉,而是把被覆盖的部分截断:
/* 插入区间:先切掉与新区间重叠的旧区间,再合并,避免后插入者被整段吞掉 */
function addInterval(g, tierIdx, a, b, text) {
var tier = g.tiers[tierIdx] || g.tiers[0];
if (!tier) return null;
var lo = Math.max(g.xmin, Math.min(g.xmax, num(a, g.xmin)));
var hi = Math.max(lo + EPS, Math.min(g.xmax, num(b, g.xmax)));
var kept = [];
tier.intervals.forEach(function (it) {
if (it.xmax <= lo + EPS || it.xmin >= hi - EPS) { kept.push(it); return; }
if (it.xmin < lo - EPS) kept.push({ xmin: it.xmin, xmax: lo, text: it.text });
if (it.xmax > hi + EPS) kept.push({ xmin: hi, xmax: it.xmax, text: it.text });
});
kept.push({ xmin: lo, xmax: hi, text: text == null ? '' : String(text) });
tier.intervals = kept;
normalize(g);
return tier.intervals[0] ? { xmin: lo, xmax: hi, text: text } : null;
}
被完整覆盖的旧标注不会保留残段,其文本直接消失。这是“覆盖写”的语义,不是“叠加”的语义;如果同一时间段需要两种描述,应该使用多个区间层,而当前实现只支持单层。
导出按 Praat 长格式输出,数字统一保留 6 位小数并去掉尾零,文本做双引号转义:
function toText(g) {
normalize(g);
var L = [];
L.push('File type = "ooTextFile"');
L.push('Object class = "TextGrid"');
L.push('');
L.push('xmin = ' + fmtNum(g.xmin) + ' ');
L.push('xmax = ' + fmtNum(g.xmax) + ' ');
L.push('tiers? <exists> ');
L.push('size = ' + g.tiers.length + ' ');
L.push('item []: ');
g.tiers.forEach(function (tier, ti) {
L.push(' item [' + (ti + 1) + ']:');
L.push(' class = "IntervalTier" ');
L.push(' name = ' + quote(tier.name) + ' ');
L.push(' xmin = ' + fmtNum(g.xmin) + ' ');
L.push(' xmax = ' + fmtNum(g.xmax) + ' ');
L.push(' intervals: size = ' + tier.intervals.length + ' ');
tier.intervals.forEach(function (it, ii) {
L.push(' intervals [' + (ii + 1) + ']:');
L.push(' xmin = ' + fmtNum(it.xmin) + ' ');
L.push(' xmax = ' + fmtNum(it.xmax) + ' ');
L.push(' text = ' + quote(it.text) + ' ');
});
});
return L.join('\n') + '\n';
}
导入端是一个逐行状态机。它按当前所在层级判断 xmin/xmax 该写到哪里,遇到无法识别的行直接跳过,因此缺字段的文件不会抛异常,而是用默认值补齐:
if (/^item\s*\[\s*\d+\s*\]\s*:/.test(s)) {
tier = { name: '', type: 'interval', xmin: g.xmin, xmax: g.xmax, intervals: [] };
g.tiers.push(tier);
phase = 'tier';
it = null;
continue;
}
if (/^intervals\s*\[\s*\d+\s*\]\s*:/.test(s)) {
if (!tier) continue;
it = { xmin: g.xmin, xmax: g.xmin, text: '' };
tier.intervals.push(it);
phase = 'interval';
continue;
}
需要特别注意:状态机只识别 intervals 段,不区分类名。遇到 class 为 PointTier 的文件时,points 段无法被识别,结果是一个没有内容的区间层,最终由 normalize 补成覆盖全程的空区间。本文实测的结果是类型字段仍记为 PointTier、区间内容全部丢失,而界面提示依然显示导入成功。
导入成功后渲染层还会强制对齐当前音频的时长,这一步会改变原始标注的时间轴:
function importTextGrid() {
invoke('files:choose', { title: '选择 TextGrid 文件' }).then(function (r) {
if (!r.success) { if (!r.canceled) notify(r.error, 'err'); return; }
var p = r.paths[0];
return invoke('fs:readText', { path: p }).then(function (t) {
if (!t.success) { notify(t.error, 'err'); return; }
var g = PPTextGrid.parse(t.text);
if (!g) { notify('这不是可识别的 TextGrid 长格式文件', 'err'); return; }
if (S.audio) {
g.xmin = 0;
g.xmax = S.audio.duration;
PPTextGrid.normalize(g);
}
如果标注文件的时长与当前音频不同,超出音频时长的区间会被裁掉,不足部分补成空档,整个过程没有二次确认。这一点适合“标注本就属于这段音频”的场景,但不适合把一段标注迁移到另一段录音上。
导出侧共三种格式。测量表 CSV 有 14 列,包含区间边界、强度、RMS、峰值、过零率与基频统计;WAV 分支按选区裁剪后固定用 16 位编码:
if (fmt === 'wav') {
var from = scope === 'sel' && S.sel.active ? S.sel.start : 0;
var to = scope === 'sel' && S.sel.active ? S.sel.end : a.duration;
var i0 = Math.max(0, Math.floor(from * a.sampleRate));
var i1 = Math.min(a.mono.length, Math.ceil(to * a.sampleRate));
if (i1 - i0 < 16) return { kind: 'error', error: '选区太短,无法导出音频' };
var wav = PPWav.encode([a.mono.subarray(i0, i1)], a.sampleRate, 16);
var buf = Buffer.from(wav);
return {
kind: 'binary',
base64: buf.toString('base64'),
ext: 'wav',
name: 'praat-' + from.toFixed(3).replace('.', '_') + '-' + to.toFixed(3).replace('.', '_') + '.wav',
preview: 'RIFF/WAVE · 16 位 PCM · ' + a.sampleRate + ' Hz · 单声道 · ' + ((i1 - i0) / a.sampleRate).toFixed(3) + ' 秒 · ' + fmtBytes(wav.length),
bytes: wav.length
};
}
这里固定传 16,而 pp-wav 的 encode 实际接受 8、16、24、32 四种位深,文件开头注释“导出统一写 16 位 PCM”描述的是调用方的选择,不是编码器的能力上限。这个差异本文已用纯函数直接验证,见第五章。
“存到音频同目录”是不弹保存对话框的另一条写盘路径,它同时限制了两个场景:音频必须来自文件路径,且不能位于内置样例目录。
var a = S.audio;
var slash = a.path ? Math.max(a.path.lastIndexOf('/'), a.path.lastIndexOf('\\')) : -1;
if (slash < 0) { notify('当前音频没有文件路径,请用「导出…」另存', 'err'); return; }
var dir = a.path.slice(0, slash);
if (/[\\/]samples$/i.test(dir)) {
notify('内置样例目录随应用一起打包,不能写入;请用「导出…」另存', 'err');
return;
}
var base = a.path.slice(slash + 1).replace(/\.[^.]+$/, '');
var target = dir + '/' + base + '-praat.' + out.ext;
命名规则是“音频名-praat.扩展名”,覆盖前会弹出自定义确认框,写盘走的是 fs:writeText 或 fs:writeBinary,因此目标路径必须在已授权目录内。由于打开音频时授权的是音频所在目录,正常情况下这条路径是通的;一旦用户撤销了该目录授权,写盘就会返回 guard 错误。
四、鸿蒙稳定性适配
4.1 禁用默认菜单栏
问题现象: 自定义顶栏与 Electron 默认菜单并存时,可能出现重复入口。这里讨论的是现有设计针对的问题,不是本文复现出的设备故障。
根因分析: 主界面已经提供打开音频、导入 TextGrid、保存会话等操作,默认的 File/Edit/View/Window/Help 菜单并不是该业务界面的组成部分,而且在平板形态下还会占用纵向空间。
解决方案: 当前 main.js 在模块加载阶段直接移除应用菜单,没有额外使用 autoHideMenuBar:
// 去掉顶部 File/Edit/View/Window/Help 默认菜单栏
Menu.setApplicationMenu(null);
快捷操作全部由渲染层的键盘事件提供:空格切换播放与停止,Escape 停止播放,Ctrl/Cmd 加 O 打开音频,并且在输入框获得焦点时跳过,避免影响文本输入。文件与目录选择仍使用 Electron 原生对话框,不能据此说项目已经移除了所有原生交互窗口。
4.2 自定义对话框、自定义下拉与关于弹层
问题现象: 删除区间、清空标注、覆盖写盘、改名与关于说明需要不同交互形式,窗口尺寸收紧时还要保证浮层不跑出工作区。
根因分析: 当前项目有两套 DOM 浮层实现。普通对话框宿主 dlgHost 位于 appFrame 内部,采用绝对定位;关于弹层位于 appFrame 之外,采用 fixed 定位覆盖视口。样式文件开头的注释声称不使用固定定位,这条约束对后续追加的关于规则并不成立。
解决方案: 对话框通过 Promise 返回用户选择,内容全部用 createElement 与 textContent 构建,没有 innerHTML 拼接:
function dialog(opts) {
return new Promise(function (resolve) {
var host = $('dlgHost');
while (host.firstChild) host.removeChild(host.firstChild);
var card = document.createElement('div');
card.className = 'dlg';
宿主与卡片的定位规则如下:
.dlg-host {
display: none;
position: absolute;
left: 0;
right: 0;
top: 0;
bottom: 0;
background: var(--mask);
grid-template-columns: 1fr;
place-items: center;
padding: 24px;
z-index: 50;
}
.dlg-host.open { display: grid; }
关于弹层则使用固定定位与固定的 480 像素宽度,并以 max-width 限制在视口内:
#aboutDialogLayer.about-layer {
position: fixed;
top: 0; left: 0; right: 0; bottom: 0;
background: rgba(17, 17, 27, 0.72);
display: flex;
align-items: center;
justify-content: center;
z-index: 9999;
}
两套实现各自都能工作,但维护时要清楚差异:对话框宿主被严格限制在 appFrame 内,主区域溢出设为 hidden,它就是安全边界;关于弹层不在该容器内,直接用 fixed 定位覆盖视口,层级 9999 高于宿主。关于层的半透明底色用的是写死的 rgba 值,而不是主题变量 --mask,换主题时需要单独调整。键盘方面,普通对话框支持 Enter 确认与 Escape 取消,关于弹层只有关闭按钮,没有接入 Escape;焦点管理、键盘可达性与不同缩放比例下的命中区域仍需设备验证。
主题方面,样式文件用 Catppuccin Mocha 变量统一了底色、面板、文本、波形与选区遮罩色,并在 1280、1120、760 三个断点收敛布局:
@media (max-width: 1280px) {
:root { --dock-w: 232px; --side-w: 168px; }
}
@media (max-width: 1120px) {
:root { --dock-w: 0px; }
#dock { display: none; }
.cols2 { grid-template-columns: 1fr; }
}
@media (max-width: 760px) {
:root { --side-w: 132px; }
.tb-sub { display: none; }
.tb-file { display: none; }
}
三列栅格在 1120 像素以下先隐藏右侧信息坞,双栏卡片再降为单栏;顶栏副标题与文件名在 760 像素以下隐藏。由于窗口最小宽度被限制在 1024,实际触发 760 断点需要在更高缩放比或分屏下才可能发生,这部分需要设备验证。
4.3 窗口配置与运行边界
窗口参数应按当前源码解释,不套用其它壳项目的“三防配置”结论。
| 配置项 | 当前源码 | 本文结论 |
|---|---|---|
| width / height | workAreaSize 的 92% / 86% | 按主显示器工作区比例计算 |
| minWidth / minHeight | 1024 / 660 | 限制最小尺寸 |
| frame / transparent / resizable | true / false / true | 三项均显式设置 |
| backgroundColor | #1e1e2e | 与业务主题底色一致,减少启动白闪 |
| title | Praat 语音分析工作台 | 与页面标题、顶栏品牌一致 |
| nodeIntegration | true | 本地渲染层可直接 require |
| contextIsolation | false | 不是隔离的 preload API 模型 |
| 窗口创建 try/catch | 已包裹 | 创建失败时只写控制台警告,不阻断进程 |
| autoHideMenuBar | 未设置 | 依靠移除应用菜单实现无菜单栏 |
| spellcheck | 未设置 | 未关闭输入拼写检查 |
| disableHardwareAcceleration | 没有调用 | 未实施禁用硬件加速 |
当前安全模型适用于受信任的本地页面。它不应直接承载不可信远程内容,也不应把授权根当作阻止已获得 Node 权限代码访问文件的安全边界。若以后增加外部网页、在线配置或插件来源,应重新设计渲染隔离、输入校验与最小权限接口。
4.4 IPC 错误反馈与异步异常边界
问题现象: 文件不存在、体积超限、路径越权、会话缺失这些失败会同时出现在多个面板,用户需要的是可读原因,而不是错误码原文。
根因分析: 主进程的错误来源分两类。一类是 fs 抛出的系统错误码,另一类是业务主动拒绝,比如缺少参数或超出上限。前者若不翻译,状态栏会出现 EACCES、ENOENT 这类原文;后者若无统一结构,渲染层就要各自判断。
解决方案: 主进程维护一张错误码到中文的映射表,并在包装器里统一调用:
/* 常见系统错误码转中文:状态栏不出现 EACCES / ENOENT 这类原文 */
var ERR_TEXT = {
EACCES: '没有访问权限,请换一个目录,或先关闭占用该文件的应用',
EPERM: '系统拒绝了这个操作,请换一个目录再试',
ENOENT: '文件或目录不存在',
EISDIR: '这是一个目录,不是文件',
ENOTDIR: '路径里有部分不是目录',
ENOSPC: '磁盘空间不足',
EBUSY: '文件正被其他程序占用',
EMFILE: '同时打开的文件太多,请稍后再试'
};
渲染层则把所有调用收敛到一个出口,通道抛异常时也返回结构化结果,避免未处理的拒绝:
/* 所有 IPC 的单一出口:通道抛异常时也返回结构化结果,避免 unhandled rejection */
function invoke(channel, payload) {
return ipcRenderer.invoke(channel, payload || {}).catch(function (e) {
return { success: false, error: '通道 ' + channel + ' 调用失败:' + ((e && e.message) || e) };
});
}
这里存在一个需要指出的边界:主进程的 handle 包装器是同步 try/catch,只能捕获同步抛出的异常。dir:choose、files:choose、file:saveText 三条通道声明为 async,await 对话框之后的代码若抛出错误,拒绝不会被这个包装器接住,会以 rejected promise 的形式抵达渲染层。渲染层的 invoke 仍有兜底,用户看到的会是“通道 xxx 调用失败”而不是中文业务提示。要彻底统一,包装器应改成 await 形式或对返回的 Promise 追加 catch。
另外,渲染层的失败提示统一复用状态栏同一个位置,后发生的消息会覆盖前一条。载入音频、运行基频、测量、导出这些操作并不会并发执行,实际使用中这个覆盖风险并不高,但它不能充当操作历史。
五、构建与部署
以下三张图片来自项目对应的上架素材目录,原图保留,副本归档到本文同级 assets。它们是既有界面素材,不是本文重新构建或操作设备产生的测试截图。

图 1:文件与信息面板展示三份内置样例,glide-100-200hz.wav 为 86.2 KB,noise-tone-440hz.wav 与 vowel-a-120hz.wav 均为 68.9 KB。音频信息卡与载入提示都是空态,右侧信息坞同时显示“未载入”;状态栏给出样例目录位于应用资源路径下的 samples 目录,版本为 v1.0.0。截图支持“样例清单与七面板结构已呈现”,不支持“音频已解析成功”的结论。

图 2:基频分析面板依次给出窗长 40 ms、步长 10 ms、基频下限 60 Hz、基频上限 500 Hz、清音阈值 0.3,与 PPPitch 的默认参数一致。统计区、浊音率、均值与中位均为空态,轨迹采样明确写着“还没有分析结果”。这些数值是默认输入,不是在当前音频上得到的分析结果。

图 3:关于弹层覆盖基频面板,文字说明这是运行于鸿蒙 PC 的 Electron 壳应用,列出 WAV 读写、FFT 频谱、基频与共振峰提取、TextGrid 转写、常用声学测量五项能力,并声明遵循 Apache-2.0。其中“共振峰提取”在 engines 目录中没有对应实现,许可证声明与 package.json 的 GPL-3.0 也不一致,需在发布前核实。
5.1 本地调试与本文验证结果
业务 package.json 没有 start 或 test 脚本,不能直接写成执行 npm start 即可运行。若本机已经准备好匹配的 Electron 可执行程序,可在业务 app 目录手动执行以下调试命令;本文未执行该启动操作:
electron .
本次实际使用 Node.js v22.20.0,对 main.js、renderer.js 与五个引擎执行 node --check,七个文件全部通过语法检查。随后直接 require 引擎,读取工程自带三份样例并构造内存输入,没有创建 DOM 仿真、临时测试脚本或测试包。
| 实际检查 | 输入 | 观察结果 |
|---|---|---|
| 语法检查 | 7 个 JavaScript 文件 | 全部通过 node --check |
| WAV 解析 | glide-100-200hz.wav | 22050 Hz、1 声道、16 位 PCM、44100 帧、2.000 s、0 条告警 |
| WAV 解析 | noise-tone-440hz.wav | 35280 帧、1.600 s、0 条告警 |
| WAV 解析 | vowel-a-120hz.wav | 35280 帧、1.600 s、0 条告警 |
| 基频轨迹 | glide 样例 | 197 帧全部浊音,均值 149.90 Hz、中位 149.74 Hz,范围 101.1–199.0 Hz |
| 基频轨迹 | noise-tone 样例 | 157 帧中 60 帧浊音(38.2%),中位 440.08 Hz |
| 基频轨迹 | vowel 样例 | 157 帧中 112 帧浊音(71.3%),中位 119.98 Hz,最小与最大均为 120.0 Hz |
| 语谱参数 | 三份样例,25 ms 窗 / 10 ms 步 / 5000 Hz | 帧数 195 / 156 / 156,频点 233,间隔 21.53 Hz,可用上限 4995.70 Hz |
| 语谱峰值 | 同上 | 最大 dB 分别为 -12.5 / -10.1 / -20.8 |
| 峰值频率 | 三份样例 | 150.01 Hz / 440.11 Hz / 720.01 Hz |
| 强度与停顿 | 阈值 -40 dBFS、最短 0.1 s | glide 0 段;noise-tone 1 段 0.609–0.990 s;vowel 2 段,首段 0.509–0.789 s |
| 区间测量 | 三份样例 | zcr 分别为 0.0246 / 0.1993 / 0.0450,均值 dB 为 -7.6 / -8.7 / -14.8 |
| TextGrid 重叠插入 | 0.2–0.6 元音,再插 0.4–0.9 辅音 | 得到 4 段:0–0.2 空档、0.2–0.4 元音、0.4–0.9 辅音、0.9–2.0 空档 |
| TextGrid 往返 | 上述 4 段生成后再解析再生成 | 文本完全一致,区间数与名称不变 |
| PointTier 输入 | 含 points 段的 TextGrid | 类型仍记为 PointTier,点内容全部丢失,只剩 1 个空区间 |
| 数字格式化 | 0.1 加 0.2、负零 | 输出 0.3 与 0 |
| WAV 编码 | 四点样本、8/16/24/32 位 | 字节数 48/52/56/60,回读位深一致;8 位量化到 0.992 |
这些结果包括正常行为与已观察到的边界,不能合并成“全部功能通过”。本次没有执行 fs:readBinary、fs:writeText、fs:writeBinary 等主进程通道,没有访问用户真实音频目录,也没有验证播放、剪贴板、文件对话框、会话恢复或任何设备侧行为。
5.2 业务资源与鸿蒙模块的衔接
页面按固定顺序载入引擎,最后一个才是渲染层,因此 renderer.js 执行时五个全局对象都已就绪:
<script src="engines/pp-wav.js"></script>
<script src="engines/pp-fft.js"></script>
<script src="engines/pp-pitch.js"></script>
<script src="engines/pp-measure.js"></script>
<script src="engines/pp-textgrid.js"></script>
业务入口是 package.json 中声明的 main.js,再由主进程加载 index.html。资源已经平铺在 app 目录,不要为了套用其他项目的部署步骤而清空该目录,也不要从一个不存在的开发副本覆盖进去。后续若维护者修改业务,应确认进入构建的资源就是上述目录,并在构建后核对产物中的业务文件版本。
偏好与会话写入运行环境的 userData,而不是回写安装资源。主要文件是 PraatPrefs.json 与 PraatSession.json,前者同时保存分析参数与授权根,后者保存音频路径、光标、选区、视图、基频参数、层名与整个标注网格。文章归档与图片复制不会触碰这些运行时用户数据。
5.3 HAP 构建与部署检查点
在 DevEco Studio 中打开 ohos_hap,确认 SDK、产品、签名和模块依赖后,再使用 IDE 对应的 HAP 构建入口。本文没有执行构建命令,因此不提供虚构的成功日志、产物路径或安装结论。
发布前建议分层检查:
- 工程身份:当前 bundleName 仍为 com.huawei.ohos_electron,vendor 为 example,AppScope 的 app_name 为 Electron;需核对应用名、Ability 标签与各语言资源是否一致。
- 权限与模板项:web_engine 声明网络、剪贴板、目录访问等权限,同时还存在位置、相机、麦克风、陀螺仪等模板能力;electron 保留快捷方式 metadata 与三个进程分离的 Ability。应结合实际业务与平台规则逐项核对,不因本文建议直接批量删除。
- 许可证:确认代码来源与授权关系后,统一 package.json 的 GPL-3.0、关于弹层的 Apache-2.0 与对外材料。
- 音频覆盖:用真实录音验证 8/16/24/32 位、32/64 位浮点、多声道与 WAVE_FORMAT_EXTENSIBLE 文件,并确认超过 8 百万帧时的截断提示能被用户看到。
- 标注兼容:用带 PointTier、多个区间层与超长文本的 TextGrid 验证导入,确认与目标软件互相打开时区间数与文本一致。
- 性能:用接近 64 MB 上限的音频观察读取耗时、内存峰值与语谱绘制帧率,区分限制上限与降级措施。
- 设备交互:检查标题栏、最小窗口、表格滚动、自定义下拉遮挡、文件对话框、播放音频路径与重启后的会话恢复。
只有完成对应验证,才能把“源码具备某条调用路径”升级为“在指定设备和条件下通过验收”。三张界面素材不能替代这些步骤。
六、常见问题与解决方案
以下问题来自源码核对和本次有限引擎验证。标为建议的措施尚未实施,不是已经完成的修复或上架排障记录。
Q1:为什么“打开音频”后只想分析 WAV,其他格式为什么不行?
问题现象: 界面按钮写着“打开音频…”,但选择器只列出 wav,选中其他文件时会被忽略或报错。
根因分析: 主进程的 AUDIO_EXTS 只有 .wav 与 .wave,解析器也写的是 RIFF/WAVE;files:choose 虽然有“全部文件”选项,但渲染层会优先挑第一个 .wav,没找到就取第一个路径交给解析,最终在 parse 阶段被“不是 RIFF/WAVE 文件”拒绝。
解决: 先把音频转成 PCM WAV 再导入;如果是浮点录音,确认位深是 32 或 64。本应用不内置解码器,若后续需要支持压缩格式,应引入解码库并把解码结果统一成 Float32 单声道再进入现有引擎,而不是在解析器里加分支。
教训: 按钮文案里的“音频”与实际的格式白名单必须同时说清,否则用户会把不支持当成文件损坏。
Q2:基频轨迹里出现 0 和突然的倍频跳变,是算错了吗?
问题现象: 同一段录音里,轨迹时断时续,偶尔出现翻倍或减半的跳变。
根因分析: f0 等于 0 表示该帧被判为清音,判定依据是自相关峰值低于阈值或结果落在 minF 到 maxF 之外。倍频跳变来自整数周期选择错误,octaveFix 只在相邻有效帧的比值落在 1.85 到 2.15 或 0.46 到 0.55 这两个窄区间内才修正,既是保守策略也是能力边界。尖锐噪声、强共振峰与急剧滑音都可能超出这个区间。
解决: 先确认一次真实滑音的表现:本次用 glide 样例验证,轨迹从首帧 101.1 Hz 单调升到末帧 199.0 Hz,197 帧全部浊音,没有出现误判。若真实录音仍有跳变,可以缩小基频上下限以排除倍频候选,或加大窗长提高低基频的周期可辨性。阈值调低会提高浊音率,但也会把噪声帧算成浊音。
教训: 基频是估计值而不是测量值,把清音判定和倍频修正当成两个独立机制分别验证,比看一条平滑曲线更有说服力。
Q3:语谱为什么只到 5000 Hz,颜色与动态范围能不能调?
问题现象: 界面标签固定显示 0–5000 Hz,直方图与语谱的色阶看起来永远一样。
根因分析: computeSpec 把 maxFreq 写死为 5000,动态范围 70 dB 被写进 data-dyn 属性,界面没有暴露任何控件。另外因为窗长被向上取到 2 的幂,真实可用上限是频点间隔与频点下标之积,取整后与 5000 存在差异。
解决: 当前只能把语谱当作可视参考,需要精确读数时改用测量表与轨迹 CSV。后续建议把 maxFreq 与动态范围开放为参数,并把实际分辨率一并标注在画布上,避免把 5000 当成硬指标。
教训: 显示上限、算法上限与实际分辨率是三个数,界面只展示一个时容易误导。
Q4:导入 TextGrid 为什么改了我的时间轴,PointTier 为什么变成空的?
问题现象: 导入一个时长与当前音频不同的标注文件后,区间边界发生变化;带点层的文件导入后只剩空白。
根因分析: 渲染层在已载入音频时会把 g.xmin 设为 0、g.xmax 设为音频时长再规范化,超出部分被裁、不足部分补空档,这个过程没有二次确认。解析器只识别 intervals 段,不区分类名,所以 PointTier 的 points 段完全不被读取。
解决: 导入前先确认标注与音频时长一致;需要保留点层时,先在原软件中将其转换为区间层,或把点位置另存为表格。后续建议增加“保留原时间轴”选项并在导入时提示将被裁切的区间数。
教训: 用同一个宽松解析器验证自己的输出容易掩盖格式问题;导入前的“时长一致性校验”比导入后的静默修正更有价值。
Q5:“存到音频同目录”和“导出”有什么区别,为什么样例目录写不进去?
问题现象: 同一个按钮组合下,有的音频能直接写回目录,内置样例却提示不能写入。
根因分析: 导出走 file:saveText 弹保存框,选完后授权目标目录;“存到音频同目录”走 fs:writeText 或 fs:writeBinary,目标路径必须在已有授权根内,并且额外用正则拦住了目录名以 samples 结尾的情况,因为样例随应用一起打包。
解决: 分析内置样例时用导出另存;分析自己的音频时两种都可以。写盘前会弹自定义确认框提示将覆盖同名文件,但覆盖后旧文件不回退,重要结果应另存为不同名称。
教训: “另存为”与“就地回写”是两条不同的授权与错误路径,不能用一个提示笼统描述。
Q6:为什么大文件读取慢,甚至直接报超限?
问题现象: 几十兆的 WAV 载入耗时明显,再大一些就提示超过单次读取上限。
根因分析: 主进程的 fs:readBinary 默认上限 64 MB,超限直接返回错误;在限内也需要把完整 Buffer 转成 base64 跨进程传递,渲染层再解码为 Uint8Array、Float32Array 声道数组与单声道混合结果。多个副本同时存在,峰值内存明显高于文件本身。
解决: 长录音先做分段或降采样再导入。后续若要支持更长音频,建议改用流式读取或内存映射,并把解码后的样本存储换成可释放的缓冲池,而不是继续抬高上限。
教训: 体积上限只是第一道门槛,序列化方式与多份副本才是内存峰值的真正来源。
Q7:关于弹层里的能力描述与许可证,为何需要发布前核实?
问题现象: 弹层列出“基频/共振峰提取”,并声明遵循 Apache-2.0。
根因分析: engines 目录只有 wav、fft、pitch、measure、textgrid 五个模块,没有共振峰(formant)估计实现;pp-fft 的 peakFreq 返回的是整段信号的单一峰值频率,用于展示与核对,不构成随时间变化的共振峰轨。package.json 写的是 GPL-3.0,与弹层的 Apache-2.0 不一致。
解决: 发布前要么补齐共振峰模块并在界面上给出入口,要么把描述改成已实现的范围;许可证需要与仓库授权文件统一后再对外。本文没有修改 about 文本、包信息或任何许可证声明。
教训: 关于弹层是面向用户的能力声明,列举的每一项都应当在源码里有对应调用链;许可证同理,不一致会把风险留给后续发布环节。
七、总结
Praat 壳应用把音频解析、时频展示、基频估计、声学测量与区间标注组合为一个语音分析工作台。值得复用的是职责分层:纯 JavaScript 引擎负责可复算的信号处理,主进程提供系统能力并统一授权与上限,渲染层组织画布、选区与结果展示。
| 特性 | 当前实现与需要保留的边界 |
|---|---|
| 音频解析 | RIFF/WAVE 分块解析,PCM 8/16/24/32 与浮点 32/64,超 8 百万帧截断 |
| 语谱展示 | 基 2 FFT + Hann 窗,25 ms / 10 ms,上限 5000 Hz,动态范围 70 dB 固定 |
| 基频估计 | 自相关 + 两步取峰 + 抛物线插值 + 窄区间倍频修正;0 表示清音 |
| 声学测量 | 强度、RMS、峰值、过零率、停顿、直方图与区间汇总 |
| 标注 | 区间层 TextGrid 读写、空档补齐、重叠插入裁剪;点层与多层未支持 |
| 导出 | CSV、TextGrid、WAV 三种格式与三种范围组合 |
| 安全模型 | 路径前缀授权 + 体积上限 + 渲染层 Node 能力,不是系统沙箱 |
| 持久化 | 参数、授权根与会话快照分别落盘,授权根由主进程独占 |
本次最关键的三个经验:
- 把算法参数分成“可调”与“写死”两类看待。 窗长、步长、频段与阈值里,一部分在界面可改,一部分写在调用处;只看控件会误以为全部可调,只在代码里找又会漏掉界面的默认值。
- 用已知答案的样例反推算法边界。 三份合成信号的基频、停顿位置与采样参数都是预先写定的,因此可以把“轨迹是否正确”从主观观察变成可核对的数值。
- 格式兼容问题要拿外部样例验证。 TextGrid 往返在自己的读写器之间一致,并不代表能完整处理其他软件的点层与多层;这类差异只能用外部样例暴露。
本文完成的是当前实现的技术梳理、有限引擎验证与素材归档。源码中尚存的边界均如实保留,未据此宣称完整移植、全功能验收或已完成鸿蒙上架。
更多推荐




所有评论(0)