更新记录

1.0.0（2026-07-19）

首发：自研高性能原生音频波形核心(内置多格式解码 mp3/aac/flac/wav/ogg)：解码 → 降采样为幅度桶(RMS 归一)生成 SoundCloud 式波

平台兼容性

uni-app x(5.14)

Chrome	Safari	Android	iOS	鸿蒙	微信小程序
×	×	5.0	12	×	×

nex-waveform —— 高性能音频波形

自研高性能原生音频波形核心（内置多格式解码：mp3 / aac / flac / wav / ogg）：解码 → 降采样为幅度桶生成 SoundCloud 式波形条（RMS 归一）+ min/max 包络 + 读 时长 / 采样率 / 声道 / 编码 元信息，提供 uni-app 可调的 JS API。 仅支持 App 端（Android / iOS），H5 / 小程序加载不了原生库。

同一份 utssdk 插件同时支持 uni-app x（uvue） 与 经典 uni-app（vue3），无需分叉。全部 路径进 / JSON 字符串出：传音频文件路径，原生侧流式解码 → 降采样 → 返回 JSON，调用方 JSON.parse 消费。 流式解码不驻留整文件 PCM（分桶状态恒为 O(buckets)），无额外系统依赖。

API

JS API	签名	说明
`waveformFromFile`	`waveformFromFile(path, buckets): string`	解码 → 降采样到 `buckets` 个幅度值（每桶 RMS，归一 0..1），返回 JSON 数字数组（SoundCloud 式波形条）
`audioInfo`	`audioInfo(path): string`	读音频元信息，返回 JSON `{durationMs, sampleRate, channels, codec}`
`waveformPeaks`	`waveformPeaks(path, buckets): string`	每桶 min/max 包络对，返回 JSON `[{min,max},...]`（min/max ∈ [-1,1]，更精细）
`waveformCoreVersion`	`waveformCoreVersion(): string`	核心库版本号

返回 JSON 结构

waveformFromFile → number[]，长度 = buckets，每项 ∈ [0,1]（最响的桶 = 1.0）。
audioInfo → { durationMs:number, sampleRate:number, channels:number, codec:string }。
waveformPeaks → { min:number, max:number }[]，长度 = buckets，min/max ∈ [-1,1]，min ≤ max。

用法示例

import { waveformFromFile, audioInfo, waveformPeaks } from '@/uni_modules/nex-waveform';

// 1) 画 120 条波形
const json = waveformFromFile('/sdcard/Music/song.mp3', 120);
const bars: number[] = JSON.parse(json); // 每项 0..1，乘以控件高度即可绘制

// 2) 读元信息
const info = JSON.parse(audioInfo('/sdcard/Music/song.mp3'));
console.log(info.durationMs, info.sampleRate, info.channels, info.codec);

// 3) 双向包络波形
const peaks = JSON.parse(waveformPeaks('/sdcard/Music/song.mp3', 200)) as Array<{min:number,max:number}>;
// 每个 {min,max} 绕中线绘制上下半幅

出错处理

原生层抛 WaveformException(Android) / WaveformError(iOS)，UTS 侧透传为 JS 异常，用 try/catch 捕获：

参数错误（buckets=0 / 超 100000 / 帧数超上限）→ InvalidParam。
文件打不开（不存在/无权限）→ Io。
非音频/坏文件、无音频轨、不支持的编码 → Unsupported / Decode。
跨语言边界绝不闪退：内部解码异常统一兜成可捕获错误。

支持格式

wav(PCM) / mp3 / flac / aac(ISO-MP4/.m4a) / ogg(Vorbis)。全部内置自研解码器，无额外系统依赖。

平台

仅 App-Android / App-iOS。H5、各家小程序、快应用均不支持（依赖原生库）。