真机交互鸿蒙 PC 实战:改系统音量被一句权限挡死,能跑通的是自己合成 440Hz PCM 的 AudioRenderer

想让订单提醒「响一下」,我一开始以为 setVolume() 把系统媒体音量调上去就行,结果真机上一调就回权限被拒。翻 PermissionDefinitions.json 才看清楚:setVolume 要的 ACCESS_NOTIFICATION_POLICY 是 provisionEnable: False,普通 normal 应用连申请资格都没有——这不是「弹个窗就能要」的权限,是一堵硬墙。而读音量那三个 getVolume/getMaxVolume/getMinVolume 又是 since 9 就废弃的 API,编译期一片 WARN。真正能在这台鸿蒙 PC 上跑通、还不用任何权限的,是 audio.createAudioRenderer() 自己造一条音频流:填 AudioRendererOptions、用 DataView 手写一段 440Hz 正弦波 PCM、加淡入淡出防爆音、setVolume(0~1) 调的是这条流的增益、start/write/stop/release 走完整生命周期。这篇文章用 tauri-hello「真机交互」页三个声音按钮从「改全局音量被拒」到「按音量真能听到一声」的完整记录,把音量两套 API 的边界、deprecated 警告该不该管、PCM 到底怎么算、renderer 为什么必须在 finally 里释放这几个问题一次讲透。

先交代这一篇在代码里的落点:

  • 声音能力实现:tauri-hello/entry/src/main/ets/bridge/SystemCapability.ets(1951 行,volume* 方法集中在 1665–1763 行)
  • 分发入口:SystemCapability.call() 的 516–518 行,interact.volume.* 共 3 个 case
  • 拿主窗口的辅助方法跟亮度共用,但声音不用窗口:mainWindow() 在 1766 行,声音三个方法一行都没调
  • 前端交互:www/js/app.js 的 capInteractVolume*(1709–1728 行,3 个函数)
  • 页面区块:www/index.html 1049–1064 行,3 个按钮 + 音量输入
  • SDK 依据:@ohos.multimedia.audio.d.ts、toolchains/lib/PermissionDefinitions.json(API 26)
  • 设备能力清单:ets/api/device-define/2in1.json
  • 构建日志:.hvigor/outputs/build-logs/build.log 里的 deprecated / 权限 WARN

这一系列四篇各讲一个真机交互能力,知识点不串台。这一篇只讲 audio:系统级音量读写为什么一半受限、应用级音频流为什么能跑通、PCM 合成和 renderer 生命周期。通知 notificationManager 放第一篇,日历 calendarManager 的 user_grant 授权时序放第二篇,亮度 window 的窗口级边界放第四篇。权限模型全貌(system_grant / user_grant / provisionEnable 的全表)在「系统能力」系列第二篇单独写过,这里只用到 ACCESS_NOTIFICATION_POLICY 这一项的结论,不重复铺开。


0. 环境与实测设备

项版本 / 型号
设备HarmonyOS PC(aarch64,API 26,2in1 形态)
DevEco Studio本机安装版,hvigor 7.26.11
鸿蒙 SDKAPI 26.0.0,compatibleSdkVersion 26.0.0,runtimeOS HarmonyOS
应用com.example.myapplication,versionCode 1000000
音频 Kit@kit.AudioKit 的 audio
系统音量 APIgetVolume/getMaxVolume/getMinVolume/setVolume(AudioVolumeType.MEDIA = 3)
改全局音量所需权限ohos.permission.ACCESS_NOTIFICATION_POLICY,system_grant / normal / provisionEnable=False
应用流 APIaudio.createAudioRenderer() → AudioRenderer.setVolume(0~1)
采样参数SAMPLE_RATE_44100(44100)、CHANNEL_1、SAMPLE_FORMAT_S16LE、ENCODING_TYPE_RAW
设备 syscapSystemCapability.Multimedia.Audio.Renderer(device-define/2in1.json 确认在列)
承载方式ArkWeb + javaScriptProxy,注入名 MallBridge
前端业务层原生 JS 无框架,www/js/app.js 104044 字节
页面规模www/index.html 82924 字节,104 个 onclick 入口
能力方法数SystemCapability.call() 分发 56 个 case,其中 interact.volume.* 3 个
构建产物entry-default-signed.hap,748020 字节
构建结果BUILD SUCCESSFUL in 11 s 783 ms(仅 WARN,无 ERROR)
编译 WARNgetVolume/getMaxVolume/getMinVolume/setVolume 四条 has been deprecated + 一条权限提示 + 一条 syscap 提示

这张表里最扎眼的是「编译 WARN」那一行。声音是四能力里唯一一个「能编过、能跑通,但编译期会被 SDK 连着刷一堆 deprecated 和 syscap 警告」的:音量那几个 AudioManager 方法从 API 9 就标了废弃,audio 这个 syscap 又被明确提示「不是所有设备都支持」。这些 WARN 不影响 BUILD SUCCESSFUL,但它们不是噪音——它们正好把「哪些路是旧路、哪些路有条件」提前告诉了我。这一篇有一半的篇幅,就是在处理这几行 WARN 背后的边界。


1. 问题是怎么找上我的:我把「控制声音」当成一个音量滑块

我一开始对「控制声音」的理解特别直白:读一下当前系统音量,设一下目标音量,播放时跟着变——一个 setVolume() 调用的事。项目最早那版 volumeSetSystem() 就是直奔系统音量去的:

// SystemCapability.ets - volumeSetSystem()(最早一版思路,节选)
const mgr: audio.AudioManager = audio.getAudioManager();
await mgr.setVolume(audio.AudioVolumeType.MEDIA, want);  // 直接改系统媒体音量

ArkTS 编译过了,还带出一行权限提示 WARN,我当时没当回事。结果装到真机上,点「尝试改全局音量」,回包是这么一句:

调用失败(1007):改全局音量被系统拒绝(需 ACCESS_NOTIFICATION_POLICY 受限权限,普通应用拿不到):{"code":201}

201。我的第一反应又是老一套:是不是 module.json5 忘了声明 ACCESS_NOTIFICATION_POLICY?翻 PermissionDefinitions.json 一看,这一项写得明明白白:

ohos.permission.ACCESS_NOTIFICATION_POLICY: grantMode=system_grant availableLevel=normal provisionEnable=False

provisionEnable=False。这四个字是分水岭——日历那两项 user_grant 的 provisionEnable=True,普通应用弹个窗就能拿到;这一项连「允许被 provision」都是 False,普通 normal 应用根本申请不到,声明了反而会在安装/审核阶段被拒。声明 ACCESS_NOTIFICATION_POLICY 不是解法,是新的坑。 编译期那行 To use this API, you need to apply for the permissions: ohos.permission.ACCESS_NOTIFICATION_POLICY 之所以只是 WARN 不是 ERROR,正因为系统知道大多数应用压根不该走这条路。

所以这个题目的边界很清楚:「控制声音」在鸿蒙上不是一根滑块,而是两条完全分开的路——AudioManager.setVolume() 改的是系统全局音量,被 provisionEnable: False 的受限权限挡死,普通应用只能如实回错;AudioRenderer.setVolume() 改的是本应用自己那条音频流的增益(0~1),无需任何权限,但前提是你得自己造一条流、自己喂 PCM 数据。 一条路走不通就换另一条,而不是硬声明权限、也不是「演示态降级」假装调成功了。

拆开之后要干的事就三件:

  • 把「读系统音量」和「改系统音量」分开:前者是公开 API(虽然废弃)能读,后者如实回错;
  • 把「能跑通的控制」落在 AudioRenderer 应用流上,从 AudioRendererOptions 到 PCM 到生命周期全走一遍;
  • 把 deprecated / syscap 那些 WARN 当成边界证据,而不是当编译噪音忽略掉。

下面是干完之后的完整记录,包括我踩的每一个坑。第 6 节会把开头这个 201 和那几行 WARN 一起收回来。


2. 效果展示

按老规矩,先给效果再讲原理。「真机交互」页的声音区块是 3 个按钮加一个音量输入:

请添加图片描述

这三个按钮分别对应三条不同的路径,UI 上的回包能把边界显示得清清楚楚:

  • 读真实系统音量 → interact.volume.get → getVolume/getMaxVolume/getMinVolume(MEDIA),回包 current/max/min 是设备真实档位。
  • 播放提示音(按音量) → interact.volume.play → createAudioRenderer() + 440Hz PCM,真机能听到一声,回包带 bytes、sampleRate、durationMs。
  • 尝试改全局音量 → interact.volume.setSystem → setVolume(MEDIA, target),真机如实回 1007,页面特意用了红色按钮,就是提醒「这条本来就该失败」。

这里每一行都不是装饰:data.needPermission 字段会明写 ohos.permission.ACCESS_NOTIFICATION_POLICY,data.hint 会区分「改的是本应用音频流增益(0~1)」和「系统全局音量另见 volume.setSystem」。把「该失败的」按钮做成红的、把权限名打在回包里,是为了别再让人以为整个声音功能是坏的。

请添加图片描述

第二张图是「播放提示音」成功后的回包,重点在那几个能算出来的数字:

{"ok":true,"code":0,"data":{"volume":0.6,"sampleRate":44100,"durationMs":320,"bytes":28224,"api":"audio.createAudioRenderer() → setVolume(v) → start() → write(PCM) → stop()","hint":"改的是本应用音频流增益(0~1),无需权限;系统全局音量另见 volume.setSystem"},"message":"已按音量 0.6 播放 440Hz 提示音"}

请添加图片描述

28224 不是随便来的:44100 × 320 / 1000 = 14112 个采样点,SAMPLE_FORMAT_S16LE 每点 2 字节,14112 × 2 = 28224。回包把 bytes 打出来,是为了真机上「写了多少数据」这件事可核对,而不是黑箱。

请添加图片描述
主动交代边界:三个按钮在浏览器预览里全部回 1004 needsDevice:

{"ok":false,"code":1004,"message":"「interact.volume.play」是真机系统能力,浏览器预览无对应服务,请装 entry-default-signed.hap 到鸿蒙 PC 验证(Web 端不模拟、不伪造成功)","data":{"needsDevice":true,"method":"interact.volume.play"}}

请添加图片描述

Web Audio API 在浏览器里当然能出声,但那不是鸿蒙 audio 这个系统服务,用它来「模拟」只会把「应用流增益 vs 系统音量」这条边界彻底糊掉。所以声音能力在 Web 端一律不造结果。页面 dev-note 也写明了:真机上「尝试改全局音量」回 1007 属预期。

请添加图片描述
请添加图片描述


3. 原理:两个 setVolume,改的根本不是同一个东西

把这次碰到的 audio API 按「方法 → 归属 → 权限 → 普适性」摊开:

方法归属权限普适性 / 状态
getVolume(MEDIA)系统 AudioManager无@deprecated since 9,仍能读
getMaxVolume/getMinVolume(MEDIA)系统 AudioManager无@deprecated since 9,仍能读
setVolume(MEDIA, v)系统 AudioManagerACCESS_NOTIFICATION_POLICY(provisionEnable: False)@deprecated since 9,普通应用必失败
createAudioRenderer(opts)应用自建音频流无audio syscap,非所有设备支持
AudioRenderer.setVolume(0~1)应用音频流增益无公开 API,真机能跑通
start/write/stop/release应用音频流生命周期无Function may throw exceptions

AudioManager.setVolume() 和 AudioRenderer.setVolume() 名字一模一样,但前者动的是整个系统的媒体音量、被受限权限锁死,后者动的只是本应用这一条流的增益、完全自由。 这句话是这一篇最要紧的模型判断。我最早就是把这两个 setVolume 当成一个,才会在 201 面前反复怀疑声明没写对。

三个细节决定了后面所有的写法:

第一,AudioVolumeType.MEDIA = 3。@ohos.multimedia.audio.d.ts:449 里枚举排得清清楚楚:VOICE_CALL = 0、RINGTONE = 2、MEDIA = 3、ALARM = 4、ACCESSIBILITY = 5。读/改系统音量都得先选一个流类型,我全篇用 MEDIA,因为提示音属于媒体流。这个数值别手写 3,要用枚举,免得 SDK 一变就错位。

第二,ACCESS_NOTIFICATION_POLICY 的 grantMode 是 system_grant、availableLevel 是 normal,单看这两项会误以为「普通应用声明一下就行」,但 provisionEnable: False 一票否决。这跟日历那两项 user_grant / provisionEnable=True 形成最直接的对照:一个是弹窗能给,一个是给了也不给。

第三,audio 这个 syscap 在 2in1.json 里确认在列(设备支持),但 SDK 仍会吐一行 The system capacity of this api 'audio' is not supported on all devices。意思是「这台设备支持,不代表所有形态都支持」——所以 volumePlay() 里所有 audio.* 调用都得包在 try 里,不能假设一定成。


4. 工程怎么搭

先给声音链路相关的目录树:

tauri-hello/
├── entry/src/main/
│   ├── module.json5                          # 4 项权限,不含 ACCESS_NOTIFICATION_POLICY
│   ├── ets/
│   │   ├── bridge/
│   │   │   ├── MallBridge.ets               # sysCall 唯一桥
│   │   │   └── SystemCapability.ets         # 3 个 volume* 方法 + ok/err + str/num/bool
│   │   └── pages/Index.ets                  # methodList: ['sysCall']
│   └── resources/rawfile/www/
│       ├── index.html                       # 真机交互页声音区块(3 按钮 + 音量输入)
│       └── js/
│           ├── app.js                       # 3 个 capInteractVolume* + CAP_INTERACT_MATRIX「控制声音」条
│           └── platform/web.js             # interact.* 统一回 1004 needsDevice
└── entry/build/default/outputs/default/entry-default-signed.hap

这次整理最关键的变化,是把「调个音量」拆成三件各自能独立验证、又如实标注边界的事。三条边界:

  • 读、改、播分成三个方法 volumeGet/volumeSetSystem/volumePlay,让「读得到、改不了、播得响」三种结果各自有回包,别混在一个调用里互相掩盖。
  • 受限路径不硬声明权限、不假降级。module.json5 里干净地没有 ACCESS_NOTIFICATION_POLICY,volumeSetSystem() 真调 setVolume()、失败就把 201 翻成 1007 回出去。
  • 音频流状态全在 ArkTS 侧。AudioRenderer 是局部变量,finally 里释放,前端只拿到一个 ToneData 回包,不碰任何原生对象。

最小接入还是要过 sysCall:

// www/js/app.js - capInteractVolumePlay()(节选)
function capInteractVolumePlay() {
  return capCall('interact.volume.play', {
    volume: Number(capVal('cap-vol-value'))   // 0~1 应用流增益
  }, 'cap-out-interact-volume');
}
// → Platform.syscap.call → MallBridge.sysCall → SystemCapability.call() case 'interact.volume.play'

三个方法在 call() 里的分发(516–518 行):

// SystemCapability.ets - call() 分发(节选)
case 'interact.volume.get':        return await this.volumeGet();
case 'interact.volume.setSystem':  return await this.volumeSetSystem(p);
case 'interact.volume.play':       return await this.volumePlay(p);

这里有一个很容易被忽略的窗口期:volumePlay() 里的 renderer.write(buffer) 是异步的,写完不能立刻 stop(),否则 320ms 的声音只响个头。我在 write() 之后插了一个 setTimeout 等 durationMs + 60 再 stop(),就是为了覆盖不同设备 getBufferSize 差异导致的播放进度不一致。这个反直觉点在 5.5 展开。


5. 把代码讲透

5.1 读真实系统音量:公开但废弃的三个 get

volumeGet() 是三个方法里唯一「读系统」的:

// SystemCapability.ets - volumeGet()(1665–1679 行,节选)
const mgr: audio.AudioManager = audio.getAudioManager();
const cur: number = await mgr.getVolume(audio.AudioVolumeType.MEDIA);
const max: number = await mgr.getMaxVolume(audio.AudioVolumeType.MEDIA);
const min: number = await mgr.getMinVolume(audio.AudioVolumeType.MEDIA);
const d: VolumeData = {
  type: 'MEDIA', current: cur, max: max, min: min,
  api: 'audio.getAudioManager().getVolume(MEDIA) / getMaxVolume / getMinVolume'
};
return this.ok(d, '已读取真机媒体音量 ' + cur + '/' + max);

三个细节值得单独说:

第一,三个 get 都是 Promise<number>,要 await。AudioManager 用 audio.getAudioManager() 拿,不用 context。

第二,流类型全程用枚举 audio.AudioVolumeType.MEDIA,不写魔法数字 3。

第三,VolumeData 是应用自己定义的窄接口(85–91 行),只回 type/current/max/min/api,不把整个 AudioManager 状态塞给前端。

一个反直觉陷阱:这三个方法在 @ohos.multimedia.audio.d.ts 里全标了 @deprecated since 9,编译期会刷 'getVolume' has been deprecated. 这类 WARN。但「废弃」不等于「不能用」——在这台 API 26 的鸿蒙 PC 上它们仍返回真实档位。判断依据是:SDK 有 @useinstead 指向新 API 时要评估迁移成本,而这几个读方法当前没有阻塞性替代、且回包是只读的,所以我保留使用、把 WARN 记在案,而不是为了消 WARN 去改一堆代码。降级说明:getMinVolume 在多数设备恒为 0,回包里仍如实返回,前端别拿它做除法分母。

5.2 改全局音量:明知会失败也要真调一次

volumeSetSystem() 是「如实回错」的样板:

// SystemCapability.ets - volumeSetSystem()(1686–1705 行,节选)
const want: number = this.num(p, 'volume', -1);
if (want < 0) return this.err(SystemCapability.CODE_BAD_PARAM, 'volume 不能为空或负数');
const mgr: audio.AudioManager = audio.getAudioManager();
const max: number = await mgr.getMaxVolume(audio.AudioVolumeType.MEDIA);
const target: number = want > max ? max : want;
await mgr.setVolume(audio.AudioVolumeType.MEDIA, target);
const d: VolumeSetData = {
  type: 'MEDIA', requested: target, applied: true,
  needPermission: 'ohos.permission.ACCESS_NOTIFICATION_POLICY'
};
return this.ok(d, '系统媒体音量已设为 ' + target);
// catch:
// return this.err(CODE_PERMISSION_DENIED,
//   '改全局音量被系统拒绝(需 ACCESS_NOTIFICATION_POLICY 受限权限,普通应用拿不到):' + JSON.stringify(e));

三个细节值得单独说:

第一,target 用 want > max ? max : want 做了上限收敛,避免传入超过设备最大档位的值——这是参数校验,不是权限问题。

第二,VolumeSetData.needPermission(92–97 行)把需要的权限名写进回包,即便成功路径也标注,让读者一眼看到这条路的门槛。

第三,setVolume() 真的调了,失败走 CODE_PERMISSION_DENIED = 1007。没有先查权限再假成功,也没有干脆不调直接回错——真调一次,是为了让原生错误码进回包。

反直觉陷阱:「明知拿不到权限,为什么还写这个方法?」因为它是一份可验证的边界证据。真机上用户点这个红按钮,看到的是带 201 和权限名的 1007,而不是一句含糊的「不支持」。降级说明:万一将来签名 profile 升级到带 ACL 白名单、provisionEnable 条件变化,这段成功路径会自然生效,不用改代码。

5.3 造一条音频流:AudioRendererOptions 在严格模式下的填法

真正能跑通的 volumePlay() 从构造 AudioRendererOptions 开始:

// SystemCapability.ets - volumePlay()(1712–1731 行,节选)
const sampleRate: number = audio.AudioSamplingRate.SAMPLE_RATE_44100;  // 44100
const durationMs: number = 320;
const opts: audio.AudioRendererOptions = {
  streamInfo: {
    samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100,
    channels: audio.AudioChannel.CHANNEL_1,
    sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
    encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
  },
  rendererInfo: {
    usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
    rendererFlags: 0
  }
};
renderer = await audio.createAudioRenderer(opts);
await renderer.setVolume(volume);

三个细节值得单独说:

第一,AudioRendererOptions 是嵌套结构,streamInfo(采样率/声道/格式/编码)和 rendererInfo(用途/标志)两层都得填全。ArkTS 严格模式下又是显式标注类型,不能有裸字面量或漏字段。

第二,SAMPLE_FORMAT_S16LE 决定了后面 PCM 每采样点 2 字节、小端序;ENCODING_TYPE_RAW 说明喂进去的是裸 PCM,不是 AAC/MP3 这类压缩流。这两个字段直接约束了 5.4 的写法。

第三,setVolume(volume) 这里的 volume 是 0~1 的浮点增益(1713–1714 行 clamp 过),和系统音量那个 0~N 的整数档位完全是两套量纲。方法都叫 setVolume,参数含义天差地别。

反直觉陷阱:createAudioRenderer() 在 @ohos.multimedia.audio.d.ts 有 callback 和 Promise 两个重载(182/208 行),我用的是返回 Promise<AudioRenderer> 的那个。用错重载、或在 renderer 还没 start() 时就 setVolume(),都不会立刻报错,但声音出不来。降级说明:STREAM_USAGE_MUSIC 对应媒体流,和 5.1 读的 MEDIA 是同一类业务,别混到 STREAM_USAGE_ALARM 去。

5.4 手写 440Hz PCM:正弦波、淡入淡出、字节序

这段是全文最「手工」的部分——没有音频文件,直接算样本:

// SystemCapability.ets - volumePlay()(1733–1741 行,节选)
const samples: number = Math.floor(sampleRate * durationMs / 1000);  // 14112
const buffer: ArrayBuffer = new ArrayBuffer(samples * 2);            // 28224 字节
const view: DataView = new DataView(buffer);
for (let i = 0; i < samples; i++) {
  const env: number = Math.min(1, i / 2000, (samples - i) / 2000);  // 线性淡入淡出
  const v: number = Math.sin(2 * Math.PI * 440 * i / sampleRate) * 0.5 * env * 32767;
  view.setInt16(i * 2, Math.floor(v), true);                        // true = 小端
}

三个细节值得单独说:

第一,samples = floor(44100 × 320 / 1000) = 14112,buffer 按 S16LE 每点 2 字节开 28224。采样率、时长、字节数三者是算出来的,改任何一个都要跟着改。

第二,env 是淡入淡出包络:min(1, i/2000, (samples-i)/2000),前 2000 点从 0 线性升到 1、后 2000 点从 1 降回 0。不加这个,正弦波 abrupt 起止会「啪」一声爆音。

第三,view.setInt16(i*2, Math.floor(v), true) 的第三个参数 true 指定小端序,和 SAMPLE_FORMAT_S16LE 的 LE 对齐;32767 是 16 位有符号最大值,*0.5 留一半幅度免得削波。

反直觉陷阱:Math.sin() 出来是 [-1,1] 的浮点,直接塞进 ArrayBuffer 是不行的——ArrayBuffer 只是一块裸内存,必须靠 DataView.setInt16 按格式写入。我第一版想用 Float32Array 直接写,格式和 S16LE 对不上,renderer 读出来全是杂音。降级说明:440Hz 是标准 A 音、320ms 是短提示音长度,这俩是演示参数;真实业务里换频率/时长,公式不变。

5.5 生命周期与 finally:start / write / 等 / stop / release

volumePlay() 的收尾把「异步播放」这件事处理干净:

// SystemCapability.ets - volumePlay()(1742–1762 行,节选)
await renderer.start();
await renderer.write(buffer);
await new Promise<void>((resolve: () => void) => {
  setTimeout(() => { resolve(); }, durationMs + 60);   // 等声音播完
});
await renderer.stop();
const d: ToneData = {
  volume: volume, sampleRate: sampleRate, durationMs: durationMs,
  bytes: buffer.byteLength,
  api: 'audio.createAudioRenderer() → setVolume(v) → start() → write(PCM) → stop()',
  hint: '改的是本应用音频流增益(0~1),无需权限;系统全局音量另见 volume.setSystem'
};
return this.ok(d, '已按音量 ' + volume + ' 播放 440Hz 提示音');
// finally:
// if (renderer !== undefined) {
//   try { await renderer.release(); } catch (e) { /* 忽略释放异常 */ }
// }

三个细节值得单独说:

第一,write() 是异步的,写完立刻 stop() 会截断声音。中间那个 setTimeout(durationMs + 60) 是等 320ms 播完再停,+60 是留给不同设备 getBufferSize 差异的余量。

第二,renderer 声明成 audio.AudioRenderer | undefined(1717 行)并初始化 undefined,是为了能在 finally 里判空。createAudioRenderer() 在 try 里赋值,后面任何一步抛错都能安全释放。

第三,finally 里的 release() 又套了一层 try/catch 且忽略异常——SDK 对 write 标了 Function may throw exceptions. Special handling is required.,release() 同理;释放失败不该覆盖掉真正的播放错误。ToneData(99–106 行)只在全部成功后才构造。

反直觉陷阱:release() 放在 finally,不是 try 末尾。因为 start/write/stop 任何一步抛错都会跳过后续语句,只有 finally 保证 renderer 一定被回收——漏一次,连续点几次「播放提示音」就会攒下几条没释放的音频流。降级说明:ToneData.bytes 用 buffer.byteLength 而不是重新算,保证和真正写进去的数据一致。


6. 我踩过的坑(每一条都有真实报错)

这一节可能是全文最值钱的部分。以下坑全部来自这次开发的真实报错和排查记录。

坑 1:setVolume(MEDIA, v) 直接回 201。 就是开头那一幕:

调用失败(1007):改全局音量被系统拒绝(需 ACCESS_NOTIFICATION_POLICY 受限权限,普通应用拿不到):{"code":201}

一开始以为是 module.json5 漏声明 ACCESS_NOTIFICATION_POLICY,差点就去加权限。翻 PermissionDefinitions.json 看到 provisionEnable=False 才刹住:system_grant + normal + provisionEnable:False 合起来是「普通应用申请不到」,硬声明只会在安装/审核阶段被拒。「需要某权限」和「能申请到某权限」是两件事,provisionEnable 那一个字段就能把整条路判死。

坑 2:把 provisionEnable: False 当成「再弹个窗试试」。 日历那两项 user_grant 是弹窗能解决的,我一度把这个经验照搬到声音上,想给 ACCESS_NOTIFICATION_POLICY 也走 requestPermissionsFromUser():

ohos.permission.ACCESS_NOTIFICATION_POLICY: grantMode=system_grant availableLevel=normal provisionEnable=False

grantMode 明写 system_grant——它连 user_grant 都不是,根本没有「运行时弹窗」这个环节。一开始以为是授权时序没摆对(日历篇坑 1 的思维定式),后来才反应过来这是另一类门:system_grant 的权限走的是安装期 provisioning,provisionEnable: False 直接在profile 层拒绝,跟弹不弹窗无关。

坑 3:三条 deprecated WARN 刷屏,差点为消警告乱改代码。 第一次编译,build.log 里连着出现:

'getVolume' has been deprecated.
'getMaxVolume' has been deprecated.
'getMinVolume' has been deprecated.
'setVolume' has been deprecated.
To use this API, you need to apply for the permissions: ohos.permission.ACCESS_NOTIFICATION_POLICY

第一反应是「这套 AudioManager API 全废了,得换新的」。翻 @ohos.multimedia.audio.d.ts 才看清:这几个是 @deprecated since 9,但在这台 API 26 设备上仍返回结果,SDK 给的是 @useinstead 建议不是强制下线。为消四条 WARN 去重写读音量逻辑,性价比极低且可能引入新类型问题。deprecated 是「建议迁移」,不是「不能调用」;先看有没有阻塞性替代和 @useinstead,再决定动不动。

坑 4:audio syscap 不是所有设备都支持。 同一份 build.log 里还有一行:

The system capacity of this api 'audio' is not supported on all devices

2in1.json 里 SystemCapability.Multimedia.Audio.Renderer 确实在列(这台 PC 支持),但 SDK 仍提示「非全设备」。一开始以为「既然设备支持就不用管」,后来把所有 audio.* 调用都包进 try、catch 翻 1003。设备 syscap 在列只说明「这台行」,代码仍要对「换个形态就不行」负责——volumePlay() 的 catch 和 finally 就是为这个准备的。

坑 5:PCM 用 Float32Array 直接写,格式对不上出杂音。 第一版图省事:

// 错误写法:S16LE 要的是 16 位整数,不是 32 位浮点
const arr = new Float32Array(samples);
arr[i] = Math.sin(...);   // renderer 按 S16LE 读,全是噪声

SAMPLE_FORMAT_S16LE 要的是 16 位有符号、小端。改成 ArrayBuffer + DataView.setInt16(i*2, val, true) 才对。streamInfo.sampleFormat 决定了内存的字节布局,不是「有块 buffer 就能播」。 回包里那个 bytes: 28224 就是改对之后核对出来的。

坑 6:没加淡入淡出,提示音「啪」一声。 正弦波直接 abrupt 起止,真机上每次响都带一下爆音。加上 env = min(1, i/2000, (samples-i)/2000) 的线性包络之后才干净。数字音频的起点和终点不是 0 幅值,硬切就是脉冲噪声——这是纯数学问题,跟权限、跟 SDK 都没关系。

坑 7:write() 完立刻 stop(),声音只响个头。 第一版没有 setTimeout:

回包 ok:true,但真机只听到极短一「嗒」,远不到 320ms

write() 是异步提交,renderer 后台还在播。一开始以为是 PCM 数据算短了,samples 反复核对过没问题;后来才想到是 stop() 抢在播放完成前。补一个 durationMs + 60 的等待才完整。异步写入不等于播放完成,停流前要给数据播完留窗口。

坑 8:release() 没放 finally,连点几次攒下没回收的流。 SDK 对 write 标了 Function may throw exceptions. Special handling is required.,release 同理。第一版把 release() 写在 try 末尾,某次 write() 抛错后 renderer 没被回收,连点「播放提示音」几次后行为开始不稳定。改成 finally 里判 undefined 再 release()、且再套 try/catch 忽略释放异常。凡是「创建—使用—释放」的原生对象,释放必须在 finally,且释放失败不能盖掉主错误。


7. 现在怎么用:从 Demo 到真机

构建命令(本机验证过的那条):

cd /storage/Users/currentUser/Documents/DevEcoStudioProjects/tauri-hello
export DEVECO_SDK_HOME=/storage/Users/currentUser/WorkBuddy/2026-11-21-17-24-54/harmony-sdk-home
node /data/service/hnp/hmos-clt.org/hmos-clt_1.0.0/hvigor/bin/hvigorw.js \
  --mode module -p product=default assembleHap --no-daemon
# BUILD SUCCESSFUL in 11 s 783 ms(仅 WARN,无 ERROR)
# 产物:entry/build/default/outputs/default/entry-default-signed.hap(748020 字节)

签名用 DevEco 自动生成的调试材料(build-profile.json5 的 signingConfigs[0]),不进仓库。自测交代:7 个 JS node --check 全过、104 个 onclick 全导出、HTML 无重复 id;HAP 里 ets/modules.abc 校验过 3 个 interact.volume.* 全在包、createAudioRenderer / setVolume / SAMPLE_RATE_44100 相关符号命中。真机验证顺序:先点「读真实系统音量」确认 current/max/min 是设备真实档位,再点「播放提示音(按音量)」听那声 440Hz、看回包 bytes: 28224,最后点「尝试改全局音量」确认它如实回 1007(这是预期,不是故障);DevEco 过滤 hilog DOMAIN 0x5504 看原生侧打印。

免得读者踩到同一堵墙,硬限制清单:

  • 改系统全局音量要 ACCESS_NOTIFICATION_POLICY,该项 provisionEnable: False,普通 normal 应用拿不到;别去 module.json5 硬声明,只会连累安装。
  • getVolume/getMaxVolume/getMinVolume/setVolume 自 API 9 废弃,当前设备仍返回结果,属于「能编过能读、带 WARN」的旧路,别为消 WARN 盲改。
  • 两个 setVolume 不是一个东西:AudioManager 那个是 0~N 系统档位、受限;AudioRenderer 那个是 0~1 应用流增益、自由。
  • SAMPLE_FORMAT_S16LE 决定 PCM 是 16 位小端整数,用 DataView.setInt16(..., true) 写,Float32Array 直接写会出杂音。
  • PCM 要加淡入淡出包络,否则起止爆音;write() 后要等 durationMs 播完再 stop()。
  • AudioRenderer 必须在 finally 里 release(),audio syscap 非全设备支持,所有调用都要 try/catch 如实回错。
  • 浏览器预览发不出鸿蒙 audio 声音,interact.volume.* 一律回 1004 needsDevice。

最开始我以为它是一根从 0 拉到 max 的滑块,一个 setVolume() 的事;现在我知道那根滑块被 provisionEnable: False 焊死在系统侧,普通应用碰不得,能做的是自己造一条音频流、自己算 14112 个采样点、自己把浮点正弦波一个个写成小端 16 位整数、加包络、等它播完、再在 finally 里把流收拾干净。「控制」这个词在这台机器上,控制的从来不是系统音量,而是「我这条流」——认清了这点,那个红按钮回 1007 时就一点都不别扭了。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐