WebAudioKit 音频分析平台产品需求文档（PRD）

文档状态：Draft / 已确认 MVP 范围
产品阶段：从零开发
目标形态：桌面浏览器 Web 应用
文档版本：v0.3 更新日期：2026-07-10

1. 产品概述

1.1 产品定位

WebAudioKit 是一个基于 Web Audio API 的本地优先音频分析工作台。用户无需安装桌面软件或上传音频到服务器，即可在浏览器中完成音频导入、播放、波形浏览、实时频谱观察、二维声谱分析、FFT 三维预览，以及音频、图像和分析数据导出。

产品以“非破坏式分析”为基本原则：导入的源文件不被修改，选区、播放位置、FFT 参数和视图状态作为独立项目状态保存。

1.2 产品目标

MVP 需要达成以下目标：

建立“导入 → 播放 → 选区 → 分析 → 导出”的完整闭环。
使用统一 FFT/STFT 参数驱动实时频谱、二维声谱图和三维视图，避免不同视图对同一信号给出互相矛盾的结果。
对常见长度音频保持流畅交互，耗时分析不阻塞主线程，并可观察进度、取消任务。
让非专业用户能够使用合理默认值立即查看结果，同时让专业用户可以精确调整 FFT、窗函数、重叠率、频率轴和 dB 范围。
在浏览器能力不足时明确提示并降级，保证基础导入、播放和波形能力尽可能可用。

1.3 成功指标

新用户无需阅读帮助即可在 3 分钟内完成一次音频导入、播放和声谱图查看。
可成功完成导入的音频中，进入可播放状态的成功率不低于 99%（排除文件损坏和浏览器不支持的编码）。
参考设备上，10 分钟、48 kHz、双声道音频的播放和分析过程不出现持续主线程卡死。
通过基准信号测试的频率、幅度、同步和导出精度验收，详见第 14 节。
所有耗时分析任务均具有加载反馈；预计超过 1 秒的任务可取消。

1.4 目标用户

用户类型	核心需求	典型任务
音频工程、声学与算法人员	快速核对频率、谐波、噪声和瞬态	调整 FFT 参数，查看声谱与三维瀑布图，导出分析数据
音乐制作人与播客创作者	检查录音结构和异常片段	查看波形、定位片段、循环试听、导出选区
开发与测试人员	验证音频资产或设备输出	对照测试音，检查峰值频率、声道和持续时间
教师、学生与音频爱好者	直观理解时域和频域	同步观察播放头、波形、频谱和 FFT 三维结构

1.5 非目标

以下内容不属于 MVP：

多轨编辑、混音、剪辑拼接、淡入淡出、DAW 级效果器链和自动化工作流；仅保留本地、非破坏式的基础滤波试听链。
源音频的破坏式修改和覆盖保存。
服务端转码、云端项目同步、账号、团队协作和在线分享。
麦克风或系统音频实时录制。
音高修正、降噪、源分离、转写等智能音频处理。
承诺支持所有压缩编码；MVP 不提供 MP3、AAC、Opus 等压缩格式编码导出。
移动端完整编辑体验和后台播放保证。
音频法证、医疗诊断或计量认证用途。

2. 产品原则

本地优先：默认不上传源音频或分析数据，所有处理在用户设备上完成。
结果可信：展示采样率、FFT Size、窗函数、Hop Size、频率分辨率和幅度单位，使分析结果可解释、可复现。
视图联动：播放头、选区、时间范围和分析参数在各视图中保持一致。
渐进增强：基础能力优先；WebGL2 不可用时降级为二维分析，而不是阻止整个产品使用。
长任务可控：任务有进度、可取消，不让过期结果覆盖新参数产生的结果。
非破坏式：所有分析和选择操作不修改源音频；导出总是生成新文件。

3. 名词与分析口径

名词	定义
实时频谱	以当前播放位置附近的一帧或短时窗口计算的“频率 × 幅度”曲线
二维声谱图	使用 STFT 计算的“时间 × 频率”图，颜色表示幅度（dBFS）
FFT 三维视图	将连续 STFT 帧映射为“时间 × 频率 × 幅度”的曲面、线框或瀑布视图
FFT Size	每个分析窗口包含的采样点数；影响频率和时间分辨率
Hop Size	相邻分析窗口起点的采样间隔
重叠率	`1 - Hop Size / FFT Size`
dBFS	以数字满量程为 0 dB 的幅度标度；正常信号不高于 0 dBFS
选区	由起止时间定义、用于循环试听、局部分析或导出的音频范围
活动资源	当前在主工作区中播放和分析的音频资源；MVP 同一时刻仅允许一个活动资源

MVP 默认分析参数：

FFT Size：2048。
窗函数：Hann。
Hop Size：FFT Size / 4，即 75% 重叠。
幅度单位：dBFS。
默认显示范围：-100 dBFS 至 0 dBFS。
默认频率范围：0 Hz 至当前音频采样率的一半。
默认频率轴：对数轴；允许切换为线性轴。
频谱采用实值信号的单边频谱。

4. 核心用户流程

4.1 首次分析

用户通过拖拽或文件选择器导入一个或多个音频文件。
系统校验文件、读取元数据并解码活动音频；界面显示进度和预计 PCM 内存占用。
系统生成波形峰值缓存，并尽快展示可交互的概览波形。
用户播放、暂停、跳转或在波形中框选片段。
用户查看实时频谱，并按需调整 FFT 参数。
用户启动全文件或当前选区的离线 STFT 分析。
系统分批生成二维声谱图和三维预览；各视图与播放头、选区联动。
用户导出全文件或选区 WAV，或导出 PNG、CSV、JSON 分析结果。

4.2 继续上次工作

用户再次打开应用。
系统从本地项目状态中恢复面板布局、活动资源元数据、FFT 参数、视图参数、选区和上次播放位置。
若源音频仍存在于本地缓存且浏览器存储有效，则恢复资源；否则提示用户重新关联原文件。
重新关联时以文件名、大小、最后修改时间及可用的内容指纹进行校验，避免把状态应用到错误文件。

4.3 选区导出

用户在波形或二维声谱图中创建选区。
用户可输入精确的开始时间和结束时间，并试听循环。
用户打开导出面板，选择 WAV 位深及是否归一化。
系统显示导出范围、时长、采样率、声道和预计文件大小。
用户确认后，系统在后台编码并提供新文件；源文件保持不变。

5. 信息架构与界面布局

5.1 一级结构

应用
├── 顶部操作栏
│   ├── 导入
│   ├── 导出
│   ├── 项目状态
│   ├── 亮色 / 暗色 / 跟随系统主题
│   ├── 音频知识图谱
│   └── 帮助 / 快捷键
├── 左侧资源栏
│   ├── 音频资源列表
│   └── 活动资源元数据
├── 中央分析工作区
│   ├── 波形
│   ├── 实时频谱
│   ├── 二维声谱图
│   └── FFT 三维视图
├── 右侧参数栏
│   ├── FFT 参数
│   ├── 显示参数
│   ├── 选区参数
│   └── 导出参数
└── 底部播放控制栏
    ├── 播放 / 暂停 / 停止
    ├── 时间与跳转
    ├── 循环与倍速
    └── 音量与静音

5.2 布局规则

桌面端以中央工作区为主，左、右侧栏可折叠和调整宽度。
波形始终可见，作为全局时间导航器；其他分析视图可使用标签页或上下分屏。
二维与三维视图共享同一分析数据时，应提供并排比较布局。
底部播放控制栏固定显示，不因视图切换而消失。
窗口宽度不足时优先折叠侧栏；不以缩小坐标文字到不可读作为适配手段。
顶部操作栏提供亮色、暗色和跟随系统三种主题偏好；选择保存在本机，自动模式应响应操作系统主题变化。主题切换不得改变音频、分析、项目或导出状态。

6. MVP 功能需求

需求优先级采用：P0 为上线必需，P1 为 MVP 完整体验所需，P2 为后续增强。

6.1 音频导入与资源管理

PRD-IMP-001 文件导入（P0）

支持点击选择文件和拖拽文件到工作区。
支持一次选择多个文件，并在资源栏中排队处理；同一时刻仅一个活动资源参与播放和主视图分析。
导入阶段显示文件级状态：等待、校验、读取、解码、生成波形、可用、失败、已取消。
对大文件显示已读取/解码进度；无法获得精确进度时显示不确定进度并说明当前阶段。
用户可取消尚未完成的导入或分析任务。
重复导入同一文件时提示用户复用已有资源或保留副本。

PRD-IMP-002 格式与能力检测（P0）

WAV 为 MVP 强保证输入格式，至少支持常见 PCM 整数和 IEEE Float WAV。
MP3、Ogg、AAC/M4A、FLAC 等格式按浏览器实际解码能力运行时检测，不因扩展名宣称必然支持。
同时检查扩展名、MIME、容器头和解码结果；信息冲突时以可验证的文件内容及解码结果为准。
不支持、文件损坏、DRM/加密、零时长或超出资源限制时，给出可操作的错误提示。

PRD-IMP-003 元数据（P0）

展示文件名、容器/格式、文件大小、时长、采样率和声道数。
位深仅在容器能够可靠提供时展示；无法确认时显示“未知”，不得根据文件大小猜测为精确值。
展示解码后 PCM 预计内存和已生成缓存大小。
多声道文件保留原声道数量和顺序；波形显隐和分析声道选择不改写播放路由。实际扬声器输出能力仍由浏览器、操作系统和输出设备决定。

PRD-IMP-004 资源生命周期（P1）

用户可切换活动资源、关闭资源或清空当前项目。
关闭资源时停止关联播放和分析任务，并释放 AudioNode、Worker 任务、PCM 引用和 GPU 资源。
存在未完成导出时，关闭资源前需二次确认。

6.2 播放控制

PRD-PLY-001 基础传输控制（P0）

支持播放、暂停、停止、从指定位置继续和跳转。
暂停保留当前位置；停止后回到选区起点，若无选区则回到 0 秒。
显示当前时间、总时长和播放进度，时间至少精确到毫秒显示。
音频播放结束后进入“已结束”状态；再次播放默认从选区起点或 0 秒开始。

PRD-PLY-002 选区循环（P0）

用户可创建、调整、清除选区，并开启/关闭循环播放。
播放头到达选区终点时回到选区起点；循环关闭时在终点继续或停止取决于是否到达资源末尾。
起止点输入应对齐到有效采样点；界面仍以时间单位展示。

PRD-PLY-003 音量与倍速（P1）

提供音量、静音和恢复静音前音量。
播放速度支持 0.5×–2.0×；默认 1.0×。
MVP 不承诺倍速播放时保持音高，界面需注明浏览器的实际行为。
切换资源或暂停不应重置音量和倍速设置。

PRD-PLY-004 AudioContext 状态（P0）

因浏览器自动播放策略导致 AudioContext 未启动时，在首次用户手势后恢复。
页面失焦、设备切换或系统挂起导致上下文暂停时，提供明显的恢复提示。
播放失败不得让播放按钮永久停留在“播放中”状态。

PRD-PLY-005 多声道监听（P1）

每个源声道提供独立 Mute 与 Solo；Mute 始终优先于 Solo，存在任意 Solo 时仅播放未静音的 Solo 声道。
输出节点附近提供悬浮控制，可调整监听总音量、前两个输出声道的独立启用状态及线性左右平衡，并提供 L/C/R 快捷按钮切换全左、居中复位和全右；面板需在空间不足时翻转并钳位于节点工作区。单声道时禁用右声道与平衡控制，多声道的其余声道保持原增益。
切换 Mute/Solo 使用短增益斜坡，避免播放中产生明显点击声；切换资源后恢复该资源最近的监听状态。
1、2、4、6、8 声道分别提供 Mono、Stereo、Quad、5.1、7.1 语义标签，并允许切换回不作假设的离散 CH 1…N。
5.1 使用 FL, FR, FC, LFE, BL, BR 源顺序；7.1 在此基础上追加 SL, SR。当前只做身份顺序标识与路由，不提供任意声道重排或指定硬件输出端口。
Mute/Solo 只影响监听图，不改变源 PCM、波形、FFT/STFT 或 WAV 导出；WAV 始终保留导出范围内的全部源声道。
输出节点的音量、启用和平衡同样只影响监听图，不改变 Mute/Solo 状态、源 PCM、分析数据或导出声道。

6.3 波形视图

PRD-WAV-001 波形渲染（P0）

每个源声道均可作为独立轨道显示；默认显示前两个声道，用户可任意显隐、独显或显示全部声道。
多于当前可视高度的轨道区域纵向滚动；每条轨道保留稳定的源索引，声道控制列表在已选语义布局下补充 FL/FR/LFE… 别名。
使用分层峰值缓存，在不同缩放级别显示每个像素范围内的最小值和最大值，避免逐采样重绘。
显示时间轴、播放头、选区、当前可视范围和声道标签。
解码完成但峰值缓存未完成时，优先展示低分辨率概览，并渐进替换为完整缓存。

PRD-WAV-002 导航与选择（P0）

单击波形跳转，拖拽创建选区，拖动选区边界调整范围。
支持滚轮/触控板缩放、水平平移、适应全长、缩放到选区。
缩放应围绕指针位置或播放头，避免用户丢失上下文。
选区、播放头和可视时间范围变化需同步到二维声谱图和三维视图。

PRD-WAV-003 精确读数（P1）

悬停显示时间、声道和归一化采样幅度/峰值摘要。
选区面板支持精确输入开始、结束和持续时间；修改任一字段时保持约束有效。
无效输入（负值、超出时长、结束早于开始）不得应用，并给出就地说明。

6.4 统一 FFT/STFT 参数

PRD-FFT-001 参数控制（P0）

FFT Size 提供 512、1024、2048、4096、8192、16384、32768，默认 2048。
窗函数提供 Hann、Hamming、Blackman，默认 Hann。
重叠率至少提供 0%、50%、75%、87.5%；默认 75%。
频率轴支持线性、对数；对数轴的最小频率必须大于 0 Hz。
用户可设置显示频率上下限和 dB 上下限；默认 -100 至 0 dBFS。
参数面板实时显示由采样率与 FFT Size 计算得到的 bin 宽度和时间窗长度。

PRD-FFT-002 参数一致性（P0）

离线二维、三维结果必须记录完整参数快照，包括采样率、声道混合方式、FFT Size、窗函数、Hop Size、幅度标定和版本。
参数改变后，旧结果标记为“参数已过期”；需要重算的视图显示重算动作，不得继续冒充当前参数结果。
快速连续改参时取消或丢弃旧任务结果，只有最新参数对应的任务可更新视图。

PRD-FFT-003 声道策略（P1）

实时频谱和离线分析可选择通道平均混合或任意 Channel 1…N；可选项按当前活动资源的实际声道数生成。
混合计算必须采用固定、可记录的规则，并避免简单求和导致超过满量程；默认使用通道平均。
切换分析声道会使依赖该数据的离线结果失效。
分析声道与波形可见声道相互独立，二者都不改变播放及 WAV 导出的源声道集合。
播放 Mute/Solo 不进入分析配置；分析始终读取未修改的源 PCM。

6.5 实时频谱

PRD-RSP-001 频谱曲线（P0）

在播放过程中，以当前播放位置附近数据持续更新“频率 × dBFS”曲线。
暂停时保留最后一帧；跳转后更新到目标位置附近的频谱。
坐标轴展示单位、刻度和当前频率范围；悬停显示频率、bin 和 dBFS。
更新频率与视觉刷新率解耦；目标为视觉流畅且不影响音频播放。
用户可切换为多声道对比，以当前波形可见声道集合叠加同步频谱曲线；图例使用语义声道标签，悬停同时列出各声道在同一频率的 dBFS。
对比模式在一个 Worker 任务中批量分析选中声道，共享同一播放位置与 FFT 参数；空可见集合显示明确空状态。

PRD-RSP-002 冻结与峰值保持（P1）

支持冻结当前曲线以便观察和对照。
支持峰值保持，并可一键清除峰值轨迹。
冻结仅影响视图更新，不暂停音频；界面必须明确显示“已冻结”。

PRD-RSP-003 无播放状态（P1）

未播放时，用户在波形上移动播放头后可查看该位置的静态频谱。
未导入音频时显示空状态和导入入口，不展示伪造示例数据。

6.6 二维声谱图

PRD-SPG-001 离线分析范围（P0）

支持分析全文件或当前选区；默认优先分析当前选区，无选区时分析全文件。
开始前展示范围、预计帧数和质量提示；耗时任务显示进度并允许取消。
计算和渲染应按分块/切片进行，先提供可用预览，再补齐高分辨率数据。

PRD-SPG-002 显示与导航（P0）

横轴为时间，纵轴为频率，颜色表示 dBFS。
支持至少一种感知均匀的默认色板，并提供颜色图例；可切换其他色板。
支持时间与频率缩放、平移、适应分析范围和缩放到选区。
播放头、选区和可视时间范围与波形同步。
悬停显示时间、频率/bin 和 dBFS；读数对应实际数据，不从颜色近似反推。

PRD-SPG-003 分辨率与缓存（P1）

分析数据与屏幕像素分辨率分离，缩放时使用合适的层级或重采样，避免每次平移都重算 STFT。
缓存键至少包含资源标识、范围、声道策略和完整参数快照。
内存不足时允许降低显示纹理分辨率，但不得静默改变底层 FFT 口径；降级情况需要提示。

6.7 FFT 三维视图

PRD-3D-001 三维模式（P0）

提供曲面、线框和瀑布三种显示模式。
三个坐标轴分别表达时间、频率和幅度；轴标题与单位始终可见或可通过图例查看。
颜色与高度都可表达幅度，颜色范围与二维声谱图的 dB 范围保持一致。
支持线性/对数频率映射，并清晰标注当前映射。

PRD-3D-002 相机与交互（P0）

支持旋转、平移、缩放和一键重置相机。
提供预设视角：透视、正视时间轴、正视频率轴和俯视。
播放时可显示当前时间切片；用户可关闭自动跟随，避免相机被强制移动。
鼠标或键盘操作不得造成页面整体滚动与画布交互冲突。

PRD-3D-003 质量与降级（P0）

提供低、中、高三档质量，默认中档；质量档仅控制三维采样密度和渲染复杂度，不改变原始分析口径。
根据 GPU 能力、分析帧数和频率 bin 数进行 LOD 降采样，限制几何体与纹理规模。
WebGL2 不可用、上下文创建失败或上下文丢失且无法恢复时，禁用三维标签并保留二维声谱图。
三维失败不应导致播放、波形或二维视图不可用。

6.8 导出

PRD-EXP-001 音频导出（P0）

支持导出全文件或当前选区为 WAV。
位深支持 PCM16、PCM24、Float32；默认 PCM16。
默认保留原采样率和声道数；MVP 不提供重采样。
可选峰值归一化；默认关闭。开启后需显示目标峰值，默认 -1 dBFS。
导出前展示范围、时长、格式、位深、采样率、声道、归一化状态和预计大小。
后台编码显示进度且可取消；取消后不得留下被误认为完整的文件。

PRD-EXP-002 分析数据导出（P1）

支持导出当前分析范围的 CSV 与 JSON。
导出内容包含参数快照、音频摘要、时间帧、频率 bin 与幅度值。
CSV 对大数据量需提前显示预计行列规模，并允许选择长表或矩阵形式；默认使用长表或实现方确认的可流式格式。
JSON 需包含 schemaVersion，以支持后续兼容。
数据导出值使用原始数值精度，不从屏幕截图或色彩反推。

PRD-EXP-003 图像导出（P1）

波形、实时频谱、二维声谱图和三维视图可导出 PNG。
图片包含标题、轴、单位、颜色图例和关键参数摘要；可选择是否包含播放头与选区。
导出分辨率至少支持当前画布和 2× 尺寸。

PRD-EXP-004 导出边界（P0）

MVP 不承诺压缩音频编码导出；界面不得展示不可用的 MP3/AAC 导出选项。
浏览器不支持文件系统直接写入时，使用标准下载方式。
文件名需经过跨平台安全处理，并默认包含源文件名、范围或分析类型。

6.9 项目状态与本地缓存

PRD-STA-001 自动保存（P0）

自动保存活动资源标识与元数据、FFT 参数、播放位置、选区、循环状态、分析声道、波形可见声道、声道布局、每声道 Mute/Solo、频谱对比开关、可视范围、色板、三维相机和面板布局。
状态修改后采用短延迟合并写入，避免高频拖动造成持续存储压力。
页面关闭或刷新后尽可能恢复最近状态；不将“播放中”状态恢复为自动播放。
状态数据包含 schemaVersion，并支持版本迁移或安全清空。

PRD-STA-002 音频与派生缓存（P1）

IndexedDB 可用于保存项目状态、波形峰值和频谱切片；在能力允许且用户确认时可缓存源文件或其副本。
未缓存源文件或浏览器已清理存储时，恢复流程提示重新关联，而不是显示不可操作的幽灵资源。
展示当前项目存储占用，并提供“清除派生缓存”和“清除全部本地数据”。
清理派生缓存不删除用户设备上的原始文件。

PRD-STA-003 隐私说明（P0）

导入区域明确说明“默认仅在本机浏览器处理，不上传服务器”。
若未来引入任何网络处理能力，必须单独征得用户同意；不属于本 PRD 的 MVP 范围。

6.10 滤波器试听选项

PRD-FLT-001 节点配置（P1）

提供独立的滤波选项页面和串行节点编辑器，支持添加、删除、排序、选择和旁路滤波节点。
基础滤波使用浏览器原生 BiquadFilter，支持低通、高通、带通、陷波、峰值、低架、高架和全通滤波器。
左侧节点库下方提供“常用预设”，首版覆盖低频清理、高频柔化、50/60 Hz 嗡声抑制、人声清理、播客清晰和电话音效。应用预设时只向当前链路追加对应的普通可编辑节点，不覆盖已有节点，并遵守 16 节点上限。
支持可切换 7、10 与 15 段的 EQ 曲线节点，默认采用行业常用的 10 段倍频程预设；三档预设均提供固定中心频率与匹配带宽的 Q，各段可调 ±24 dB，最高中心频率为 16 kHz。切换段数时按对数频率插值已有增益曲线，并只重建当前 EQ 运行时分组，不重新开始播放；节点悬浮面板支持拖动曲线控制点、键盘微调、数值输入、频段切换和整条曲线归零。
支持采样器节点，以 3–192 kHz 配置模拟目标采样率；目标低于输出上下文时先执行有界一阶抗混叠，再选择默认的“复古保持”零阶保持、“线性平滑”因果线性插值、“三次平滑”四点 Catmull–Rom 或“带限重建”128 相位 16 抽头窗化 sinc。算法切换只重建当前监听路由，不重新开始播放。目标采样率不低于输出上下文时界面明确显示“透明直通”并禁用无效的算法选择，不得称为真实上采样或声称生成新的 PCM 帧和高频信息。
节点参数至少包含频率、Q 值和适用类型的增益；参数必须按当前采样率与安全范围校验。
左侧节点库的每一种处理节点在鼠标悬停或键盘聚焦时显示说明面板，包含节点用途、关键参数和明确标记为示意的处理前后图例；频率塑形与 EQ 节点使用二维频谱对比，全通使用波形表达相位变化，采样器使用波形表达采样率转换与高频细节变化。示意图不得冒充当前音频或当前节点参数的权威分析结果。
点击画布节点后使用邻近悬浮面板编辑参数；面板需避开画布边界，并支持关闭按钮、Esc 和点击画布空白处收起。
中间处理节点支持通过专用手柄拖拽排序；拖动期间使用限制在画布可视区域内的悬浮副本实时跟随指针，以缩放和倾斜反馈弹性手感，同时只预览顺序和插入位置。释放后一次性提交并重编译监听图，Esc 或指针取消需恢复原顺序。输入与输出节点不可参与排序，前移/后移按钮继续作为键盘降级路径。
点击输入节点后复用处理节点的邻近悬浮面板查看当前输入音频的文件名、格式、文件与 PCM 大小、时长、采样率、声道数和采样帧数；未导入音频时显示明确空状态。
节点变更在控制线程重建监听图；采样器的 AudioWorklet 渲染路径只执行固定上限、预分配、无阻塞的逐采样处理。旧节点必须断开并释放引用。

PRD-FLT-002 滤波前后试听（P1）

提供原始音频 A 与滤波结果 B 的即时切换，切换不得重启播放或移动播放头。
干声与湿声切换使用短增益斜坡，避免明显点击声；空滤波链时回退到原始音频。
滤波器只影响扬声器监听，不改写源 PCM，不改变波形、FFT/STFT 和 WAV/分析数据导出。
页面必须明确展示当前活动节点数、旁路节点数、试听模式和是否正在播放。
A/B 使用双声轨预览，默认高度为视口的 50%，支持拖拽上沿调节且整个预览不超过视口高度的 60%；预览可在时域波形、当前位置频谱和离线二维声谱间切换。波形模式下 A 轨显示源 PCM，B 轨对有效下采样采样器显示处理后时域近似；只计算当前可视时间范围，并以绘图区像素数和固定每列取样预算限制工作量。B 轨频谱/声谱叠加已编译滤波与抗混叠响应。两条声轨共享对应视图的坐标范围：波形显示时间与归一化幅度轴，频谱显示对数频率与 dBFS 轴，二维声谱显示时间与线性频率轴。波形与二维声谱共享 A/B 时间视口，支持以指针为锚点滚轮缩放、适应当前范围，以及点击绘图区切换对应试听并跳转到采样点；频谱横轴保持频率语义，不将点击位置误解释为时间。

6.11 音频知识图谱

PRD-WKI-001 节点知识浏览（P1）

顶部工作页面导航提供独立“音频知识图谱”页面，覆盖节点编辑器支持的全部基础滤波器、EQ 曲线、全通与采样器节点。
核心原理覆盖 IIR 滤波器、奈奎斯特采样定理、三次平滑、带限重建、振幅包络、Q 值与带宽、dBFS 数字电平，以及 FFT/STFT；每项提供定义、关键结论、确定性教学图例和关联主题。三次平滑需图解四点 Catmull–Rom 与线性连接的差异，带限重建需图解窗化 sinc 核、抽头数和分数相位。
按频段边界、音色塑形、相位与采样分类展示节点用途、处理类型、关键参数，以及处理前后的二维频谱或波形图例。
知识图谱与节点库悬浮说明共用同一份节点知识文案、图表数据与渲染内容，新增节点时必须同步纳入覆盖检查，避免两处说明漂移。
所有图例明确标记为确定性教学示意，不读取当前 PCM、不创建 AudioContext、不触发 FFT/STFT，也不把图例描述为当前音频或当前参数的权威结果。
知识正文、目录、参数提示与图例标注使用高于工作台辅助信息的可读字号；卡片必须为图例保留足够绘制宽度，在 1024 px 最小桌面宽度下自动切换为单列，不以压缩文字和坐标标注维持双列。
页面支持亮色、暗色与跟随系统主题；打开知识图谱时停止不可见工作台的实时频谱任务，播放控制和当前项目状态保持不变。

7. 交互规范与快捷键

7.1 通用交互

所有图表的播放头使用一致颜色，选区使用一致的半透明填充和边界样式。
参数修改分为即时显示参数和需要重算的数据参数；需要重算时明确显示“应用并重新分析”。
拖动播放头、选区边界和视图时，数值面板实时反馈；松手后提交高成本更新。
危险或不可逆操作仅限清空本地数据、关闭含未完成导出的资源等场景，并需确认。
Toast 用于结果通知，字段错误在字段附近显示；不得仅依赖 Toast 说明可修复输入错误。
用户触发的任务可从统一任务区查看状态和取消。

7.2 默认快捷键

快捷键仅在焦点不位于文本输入框、下拉框或可编辑区域时生效；Mac 使用 Cmd 替代 Ctrl。

操作	快捷键
播放 / 暂停	`Space`
停止	`Shift + Space`
向后 / 向前跳转 1 秒	`←` / `→`
向后 / 向前跳转 10 秒	`Shift + ←` / `Shift + →`
设置选区起点 / 终点	`I` / `O`
清除选区	`Esc`
切换循环	`L`
静音 / 取消静音	`M`
放大 / 缩小时间轴	`+` / `-`
适应全长	`0`
缩放到选区	`F`
导入文件	`Ctrl/Cmd + O`
导出	`Ctrl/Cmd + E`
打开快捷键帮助	`?`

快捷键必须可在帮助弹窗中查看；MVP 可不支持用户自定义，但需避免与浏览器关键快捷键产生高风险冲突。

8. 功能边界与业务规则

8.1 文件与资源边界

应用可维护多个已导入资源，但同一时刻仅播放和分析一个活动资源。
MVP 以可解码到内存的音频为主要对象，不承诺无限长度流式分析。
超大文件不得直接冒险解码；需先展示预计 PCM 内存并允许用户取消。
当前全量 Worker 协议会产生 PCM 任务副本，因此工作区常驻解码 PCM 默认总硬上限为 512 MiB；超过软预算时保留播放与波形，但不自动启动全文件 FFT。
源文件只读，任何导出均创建新文件。
文件扩展名不是能力依据，最终以浏览器解码和容器解析结果为准。

8.2 分析边界

实时频谱用于观察，不作为离线声谱数据的替代；导出分析数据使用可复现的离线 STFT 结果。
三维视图是同一 STFT 数据的可视化，不是新的分析算法。
屏幕上的 LOD、插值和纹理降采样不得改写导出的底层分析数据。
幅度结果需进行窗函数增益校准；所有对外数据注明单位与口径。
分析结果不构成计量、诊断或合规认证。

8.3 播放与选择边界

播放头和选区内部以采样位置记录，展示时转换为时间。
选区起点包含、终点不包含，导出样本数为 endSample - startSample。
循环、导出和离线分析使用同一选区定义。
修改活动资源时清除不属于新资源的播放头和选区，不跨文件套用绝对时间。

8.4 存储边界

本地状态恢复是便利功能，不等同于永久备份。
浏览器可能因配额或策略清理数据，应用需说明并可恢复到无缓存状态。
不在日志、错误上报或 URL 中写入音频内容及完整本地路径。

9. 非功能需求

9.1 性能

播放期间音频线程不得执行离线 STFT、图像编码或大块序列化。
FFT/STFT、峰值金字塔、WAV 编码和大数据导出在 Worker 中执行。
波形交互目标 50–60 FPS；参考设备上的三维中等质量目标不低于 30 FPS。
播放头与视图同步误差目标不超过 50 ms。
参数修改后 200 ms 内提供视觉反馈或进入明确的重算状态。
对频谱帧、纹理和几何体设定上限；按可视范围和质量档使用 LOD。
任务取消后应尽快停止后续计算，并释放中间缓冲区。

参考设备定义：近 4 年内的主流 4 核桌面 CPU、8 GB 内存、集成显卡、当前稳定版桌面浏览器。实现阶段需记录实际测试机型，不能只以开发机结果代替。

9.2 稳定性与资源释放

切换或关闭资源后断开关联 AudioNode，终止或复用 Worker，并释放 GPU 对象与大数组引用。
WebGL 上下文丢失、AudioContext 中断、Worker 崩溃和存储失败均应可恢复或安全降级。
同一资源反复打开、分析、关闭 20 次后，不应出现持续线性增长且无法回落的内存占用。
页面异常恢复后，不自动覆盖用户原文件或创建未明确请求的下载。

9.3 可访问性

关键操作可通过键盘完成，焦点顺序与视觉布局一致。
按钮具有可读名称、禁用原因和可见焦点样式。
颜色不是传递播放、选区、错误或幅度信息的唯一方式；图表提供轴、数值读数和图例。
文本和核心控件满足 WCAG 2.1 AA 对比度目标。
遵循 prefers-reduced-motion，减少非必要相机动画和面板过渡。
Canvas/WebGL 视图提供可访问摘要，例如当前范围、峰值频率和分析参数。

9.4 隐私与安全

默认所有音频处理均在本地完成，不调用外部音频处理服务。
对文件名和导出文件名做安全转义；不将文件内容渲染为 HTML。
不持久化用户完整本地路径。
本地错误日志仅记录必要技术信息，不包含 PCM 数据。
第三方依赖需锁定版本并纳入依赖安全扫描。

9.5 可维护性与可测试性

播放状态、项目状态、分析任务与渲染状态分离，避免图表组件成为业务状态唯一来源。
FFT 核心使用确定性基准信号建立单元测试；WAV 编解码覆盖不同位深、声道和边界选区。
Worker 协议和持久化数据均带版本号。
关键参数、导出结果和异常需有结构化日志，但生产环境默认不输出敏感或高频调试内容。

10. 浏览器兼容与降级策略

10.1 支持范围

平台	支持级别	MVP 预期
最新两个稳定大版本的桌面 Chrome	完整支持	播放、波形、实时频谱、二维、三维、Worker 分析和导出
最新两个稳定大版本的桌面 Edge	完整支持	与 Chrome 相同
最新两个稳定大版本的桌面 Firefox	核心支持	核心功能可用；格式解码与性能按能力检测
最新两个稳定大版本的桌面 Safari	核心支持	核心功能可用；文件、Web Audio、Worker、WebGL 差异按能力检测
iOS / Android 浏览器	尽力支持	可导入和基础播放时可用，不承诺完整布局、长文件与三维性能
Internet Explorer 与旧版浏览器	不支持	显示升级浏览器说明

10.2 启动能力检测

应用启动或首次使用相关功能时检测：

Web Audio API 与 AudioContext。
Web Worker 与可转移 ArrayBuffer。
Canvas 2D。
WebGL2、纹理上限和上下文创建结果。
IndexedDB 及可用存储估算能力。
文件读取、下载及可选文件系统 API。
待导入音频格式的实际解码能力。

10.3 降级层级

完整模式：播放、波形、实时频谱、二维和三维均可用。
二维模式：WebGL2 不可用时关闭三维，保留波形、播放、实时频谱和 Canvas 二维视图。
基础模式：高性能分析能力不足时保留导入、播放、波形和较低分辨率分析。
不可用：缺少 Web Audio 或无法解码文件时，阻止对应操作并说明原因和建议。

11. 空、加载、错误与异常状态

场景	用户可见状态	恢复动作
尚未导入	展示产品用途、支持格式说明和拖拽入口	导入文件
文件读取中	文件级进度、当前阶段、预计内存	取消
解码耗时	不确定或精确进度，其他资源仍可操作	取消、稍后重试
格式不支持	说明浏览器无法解码，不笼统归因于文件损坏	使用 WAV 或更换支持该格式的浏览器
文件损坏/截断	展示解析或解码失败，不进入半可用播放状态	重新选择文件
文件过大/内存风险	展示文件大小、预计 PCM 内存和风险	取消或确认继续；必要时拒绝
AudioContext 被暂停	播放栏显示需用户恢复	点击“恢复音频”
播放设备变化	暂停并说明输出中断	恢复播放或刷新设备
分析排队	任务区显示队列位置和参数摘要	取消排队任务
分析失败	保留播放和已有视图，展示失败阶段	重试、降低质量或缩小范围
参数已改变	旧图带“结果已过期”标识	应用并重新分析
Worker 无响应	任务失败且不阻塞 UI	重启任务；必要时刷新应用
WebGL2 不支持	三维标签禁用并解释	使用二维声谱图
WebGL 上下文丢失	尝试恢复，失败则降级	重试三维或继续二维
存储配额不足	自动保存/缓存状态提示失败	清除缓存、减少缓存或继续无持久化使用
源文件缓存丢失	恢复元数据和参数但资源不可播放	重新关联原文件
导出中	显示进度、范围和目标格式	取消
导出失败	说明编码、内存或下载权限问题	缩小范围、降低输出规模、重试
页面有未完成任务	离开前提示任务将取消	留在页面或确认离开

所有错误信息至少包含：发生了什么、哪些数据仍安全、用户现在可以做什么。开发错误码可折叠显示，不能替代用户可读说明。

12. 数据与状态模型概要

12.1 项目状态

schemaVersion
资源清单与活动资源 ID
每个资源的元数据、状态与缓存键
播放位置、音量、倍速、循环状态
选区起止采样点
FFT/STFT 参数与分析声道
波形可见声道集合、声道布局、每声道 Mute/Solo、频谱对比开关，以及波形、二维和三维的视口状态
色板、dB 范围、三维质量与相机参数
面板布局与折叠状态
最近一次成功保存时间

12.2 分析结果标识

分析缓存标识必须能区分：

源资源及内容版本。
起止采样点。
采样率和声道混合策略。
FFT Size、窗函数、Hop Size。
幅度校准与算法实现版本。

仅当标识完全匹配时才允许复用结果。

13. 分阶段路线图

阶段 0：技术验证

使用 1 kHz 正弦、扫频、脉冲和静音测试信号验证 FFT 频率与幅度标定。
验证 10 分钟、48 kHz、双声道文件的解码内存、波形生成和 Worker STFT。
完成基础 Web Audio 播放与 256 × 256 数据规模的三维曲面原型。
确认 Chrome、Edge、Firefox、Safari 的格式能力和降级路径。

退出条件：核心技术风险有可运行原型和记录，不存在阻断 MVP 的未知项。

阶段 1：播放与波形纵向闭环

完成项目骨架、导入、元数据、解码、播放控制和 AudioContext 恢复。
完成波形峰值金字塔、缩放、平移、播放头和选区。
建立 Worker 任务协议、统一状态管理和基础 IndexedDB 持久化。

退出条件：用户可以稳定完成“导入 → 播放 → 选区”，刷新后恢复主要状态。

阶段 2：频谱与二维分析

完成统一 FFT/STFT 核心和参数面板。
完成实时频谱、离线二维声谱图、进度、取消和缓存。
完成波形与声谱的播放头、选区和视口联动。

退出条件：参考信号通过频率和幅度测试，10 分钟参考文件分析不阻塞主线程。

阶段 3：三维与导出

完成曲面、线框、瀑布模式，相机预设和质量档位。
完成 WebGL2 能力检测、LOD、上下文恢复与二维降级。
完成 WAV、CSV、JSON 和 PNG 导出。

退出条件：导出精度、三维帧率和跨视图同步达到 MVP 验收标准。

阶段 4：稳定性与发布准备

完成资源释放、内存压力、异常恢复、浏览器矩阵和可访问性测试。
完成空状态、错误文案、快捷键帮助和隐私说明。
建立性能基线、回归用例和发布检查清单。

退出条件：P0 无阻断缺陷，所有第 14 节硬性指标通过或有书面批准的例外。

阶段 5：多声道监听与对比（当前）

完成播放级 Mute/Solo、5.1/7.1 语义声道标签与身份顺序路由。
完成可见声道的同步实时频谱叠加、图例与同频悬停读数。
项目状态升级到 schema v3，并迁移 v1/v2 的分析与波形声道设置。

退出条件：8 声道差异信号的监听隔离、频谱主峰、状态恢复和全声道 WAV 导出均通过验收。

后续版本候选

多文件 A/B 对比与频谱差异视图。
任意声道重排、可编辑扬声器矩阵与指定硬件输出端口。
标记、注释、区域标签和项目文件显式导入导出。
RMS、Peak、LUFS、动态范围等统计。
麦克风与设备实时输入。
超长音频流式解码与分块分析。
基于运行时能力检测的压缩音频导出。
可插拔分析器、脚本接口和批处理。

14. 可量化验收标准

14.1 正确性

编号	验收项	通过标准
AC-COR-001	频率准确度	对 1 kHz 正弦测试音，频谱主峰与理论频率误差不超过 1 个 FFT bin
AC-COR-002	幅度准确度	对避开频谱泄漏且幅度已知的正弦测试音，完成窗函数增益校准后主峰误差不超过 ±1 dB
AC-COR-003	Nyquist 范围	显示与导出的最高有效频率不超过 `sampleRate / 2`，bin 数与单边 FFT 定义一致
AC-COR-004	视图一致性	同一参数、声道和时间帧下，实时/离线频谱、二维及三维取样值在规定数值精度内一致
AC-COR-005	选区导出长度	WAV 选区导出样本数与 `endSample - startSample` 之差不超过 1 个采样点
AC-COR-006	WAV 数据	PCM16、PCM24、Float32 的头信息、采样率、声道数和数据长度可被至少两种独立播放器/解析器正确读取
AC-COR-007	多声道隔离	对各声道频率不同的 8 声道测试音，`Channel 1…8` 分析均命中对应主峰；波形显隐不改变播放与 WAV 导出的 8 个声道
AC-COR-008	多声道频谱对比	对 8 声道不同频率测试音显示全部声道时，图例与 8 条曲线一一对应，各主峰误差不超过 1 个 FFT bin

14.2 同步与交互性能

编号	验收项	通过标准
AC-PER-001	播放头同步	播放期间波形、二维和三维当前时间指示的相互误差不超过 50 ms
AC-PER-002	波形交互	参考设备上平移或缩放 10 分钟波形时目标 50–60 FPS，连续 5 秒测试的第 5 百分位不低于 45 FPS
AC-PER-003	三维性能	中等质量、256 × 256 显示网格下，参考设备连续交互帧率不低于 30 FPS
AC-PER-004	参数反馈	修改 FFT 或显示参数后 200 ms 内出现新视觉结果或明确的“正在重算/待应用”状态
AC-PER-005	主线程响应	10 分钟、48 kHz、双声道参考文件离线分析期间，主线程不存在超过 1 秒的单次长任务；播放与取消控件保持可响应
AC-PER-006	取消任务	用户取消分析后 500 ms 内停止进度增长并进入“已取消”状态；允许底层分块在安全点结束，但不得提交取消后的结果

14.3 资源与稳定性

编号	验收项	通过标准
AC-RES-001	内存预警	导入前或解码早期展示预计 PCM 内存；预计超过产品设定安全阈值时要求用户确认
AC-RES-002	资源释放	关闭资源后不再播放或更新其视图；关联 Worker 任务、AudioNode 和 GPU 对象均被释放或回收复用
AC-RES-003	重复生命周期	同一 10 分钟参考文件连续导入、分析、关闭 20 次后，不出现与次数近似线性增长且静置后不回落的内存趋势
AC-RES-004	任务陈旧保护	快速连续修改参数 10 次，最终视图只呈现最后一次参数结果，旧任务不得覆盖
AC-RES-005	WebGL 降级	模拟 WebGL2 不可用或上下文丢失时，三维不可用提示正确，播放、波形和二维视图仍可操作

14.4 功能闭环

编号	验收项	通过标准
AC-FUN-001	导入闭环	WAV 参考集可通过选择与拖拽导入，状态完整，失败文件不影响其他资源
AC-FUN-002	播放闭环	播放、暂停、停止、跳转、循环、音量、静音和 0.5×–2.0× 倍速均按定义工作
AC-FUN-003	分析闭环	全文件及选区均可生成二维与三维结果，进度可见且可取消
AC-FUN-004	导出闭环	全文件和选区可导出三种 WAV 位深；当前分析可导出 CSV/JSON；四类视图可导出 PNG
AC-FUN-005	状态恢复	刷新后恢复 FFT 参数、选区、播放位置、视口、面板和三维相机；不会自动开始播放
AC-FUN-006	缓存丢失	清除站点存储后再次打开，应用正常进入空状态或重新关联流程，不崩溃且不声称源文件仍可用
AC-FUN-007	多声道监听与恢复	5.1/7.1 标签顺序正确，Mute/Solo 规则生效；刷新并重新关联同一文件后恢复布局、监听状态与频谱对比开关

14.5 兼容性与可访问性

编号	验收项	通过标准
AC-COM-001	浏览器矩阵	第 10 节桌面支持范围内的浏览器均完成核心回归；差异符合声明的完整/核心支持等级
AC-COM-002	键盘流程	仅使用键盘可完成导入入口访问、播放控制、选区精调、视图切换和导出确认
AC-COM-003	焦点与名称	所有 P0 控件具有可见焦点、可读名称和合理顺序，图表具有文本摘要
AC-COM-004	颜色无依赖	关闭颜色辨识或使用灰度检查时，播放头、选区、错误状态和关键图例仍可通过形状、文本或位置识别

15. 发布范围判定

MVP 可发布需同时满足：

所有 P0 需求完成，P1 未完成项有明确延期记录且不破坏核心闭环。
第 14 节正确性硬指标全部通过。
不存在导致源数据被修改、错误导出、持续播放失控、主界面不可恢复或隐私承诺不成立的已知缺陷。
Chrome 与 Edge 达到完整支持；Firefox 与 Safari 达到已声明的核心支持或提供明确的能力限制说明。
技术设计、测试基线、异常码和用户隐私说明与实际实现一致。

FilesExpand file tree

PRD.md

Latest commit

History