1# 媒体子系统音频接口变更说明
2
3## c1.multimedia.1 ohos.multimedia.audio AudioManager接口setAudioParameter/getAudioParameter废弃
4
5**访问级别**
6
7公开接口
8
9**废弃原因**
10
11不再开放三方应用与音频芯片通过定制参数直接修改配置的通道，收归系统内部管控，通用功能由专有接口替代
12
13**废弃影响**
14
15非兼容性变更，需要开发者进行适配。
16
17**废弃发生版本**
18
19从OpenHarmony SDK 4.1.6.5开始。
20
21**废弃的接口**
22
23接口属于AudioManager
24
25setAudioParameter(key: string, value: string, callback: AsyncCallback<void>): void;
26
27setAudioParameter(key: string, value: string): Promise<void>;
28
29getAudioParameter(key: string, callback: AsyncCallback<string>): void;
30
31getAudioParameter(key: string): Promise<string>;
32
33**适配指导**
34
35对于系统应用，根据废弃接口提示，使用替代接口：
36
37setExtraParameters(mainKey: string, kvpairs: Record<string, string>): Promise<void>;
38
39getExtraParameters(mainKey: string, subKeys?: Array<string>): Promise<Record<string, string>>;
40
41mainKey与原接口参数key保持一致，kvpairs是原有value字符串内多个key-value配对的拆分写法。
42
43对于三方应用，本接口提供的功能本身不对三方开放，请按需使用系统在AudioManager模块中提供的公开音频管理接口。
44
45废弃接口会在至少5个SDK版本内保持兼容，请应用按需规划适配计划。
46
47## c1.multimedia.2 ohos.multimedia.audio AudioVolumeGroupManager接口setMicrophoneMute废弃
48
49**访问级别**
50
51公开接口
52
53**废弃原因**
54
55虽然本接口是公开接口，但使用本接口需要获取权限ohos.permission.MANAGE_AUDIO_CONFIG。
56本权限未开放给三方应用申请，因此三方应用实际无法使用本接口提供的能力。根据SDK规范，进行废弃，调整为系统接口，不对外可见。
57
58**废弃影响**
59
60非兼容性变更，需要开发者进行适配。
61
62**废弃发生版本**
63
64从OpenHarmony SDK 4.1.6.5开始。
65
66**废弃的接口**
67
68接口属于AudioVolumeGroupManager
69
70setMicrophoneMute(mute: boolean, callback: AsyncCallback<void>): void;
71
72setMicrophoneMute(mute: boolean): Promise<void>;
73
74**适配指导**
75
76系统应用，根据废弃接口提示，使用替代接口，功能完全一致：
77
78setMicMute(mute: boolean): Promise<void>;
79
80三方应用，由于原本就无法获取ohos.permission.MANAGE_AUDIO_CONFIG权限授权，原接口处于无效状态，因此对三方应用无实际影响。
81
82废弃接口会在至少5个SDK版本内保持兼容，请应用按需规划适配计划。
83
84## c1.multimedia.3 ohos.multimedia.audio CaptureFilterOptions属性usages行为变更
85
86**访问级别**
87
88公开接口
89
90**变更原因**
91
92本属性用于在音频内录功能中，对录制的音频usage进行筛选，当筛选STREAM_USAGE_VOICE_COMMUNICATION作为录制目标时，
93应用需要具备ohos.permission.CAPTURE_VOICE_DOWNLINK_AUDIO权限。
94但这个权限并不对三方应用开放授权，按照SDK规范，需要将权限剥离出公开接口。
95
96**变更影响**
97
98非兼容性变更，需要开发者进行适配。
99
100**变更发生版本**
101
102从OpenHarmony SDK 4.1.6.5开始。
103
104**变更的接口/组件**
105
106变更前：
107```
108/**
109 * Filter by stream usages. If you want to capture voice streams, additional permission is needed.
110 * @permission ohos.permission.CAPTURE_VOICE_DOWNLINK_AUDIO
111 * @syscap SystemCapability.Multimedia.Audio.PlaybackCapture
112 * @since 10
113 */
114 ```
115接口允许调用者筛选STREAM_USAGE_VOICE_COMMUNICATION作为录制目标，但需要获取ohos.permission.CAPTURE_VOICE_DOWNLINK_AUDIO权限。
116
117变更后：
118```
119/**
120 * Filter by stream usages. But not allow to capture voice streams.
121 * @syscap SystemCapability.Multimedia.Audio.PlaybackCapture
122 * @since 11
123 */
124 ```
125接口不再允许调用者筛选STREAM_USAGE_VOICE_COMMUNICATION作为录制目标，权限声明删除。当无权限，但选择STREAM_USAGE_VOICE_COMMUNICATION作为录制目标时，无法创建AudioCapturer对象，返回ERROR_SYSTEM错误。
126
127**适配指导**
128
129三方应用，由于本身无法获取权限授权，此变更无任何影响，无需适配
130
131系统应用，即使拥有ohos.permission.CAPTURE_VOICE_DOWNLINK_AUDIO权限，也不再能够筛选STREAM_USAGE_VOICE_COMMUNICATION作为录制目标，需将此类型从筛选中删除。
132
133## c1.multimedia.4 ohos.multimedia.audio AudioManager订阅事件interrupt接口废弃
134
135**访问级别**
136
137公开接口
138
139**废弃原因**
140
141SDK10时OpenHarmony已全面使用内置焦点模式，见开发指南中的[多音频播放的并发策略](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/media/audio-playback-concurrency.md)
142本接口为历史遗留的外置焦点接口，与内置焦点独立，已经无法起到焦点抢占的作用，因此废弃，避免误导开发者。
143
144**废弃影响**
145
146非兼容性变更，需要开发者进行适配。
147
148**废弃发生版本**
149
150从OpenHarmony SDK 4.1.6.5开始。
151
152**废弃的接口**
153
154接口属于AudioManager
155
156on(type: 'interrupt', interrupt: AudioInterrupt, callback: Callback<InterruptAction>): void;
157
158off(type: 'interrupt', interrupt: AudioInterrupt, callback?: Callback<InterruptAction>): void;
159
160**适配指导**
161
162根据内置焦点模式实现多音频并发策略控制，参考[多音频播放的并发策略](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/media/audio-playback-concurrency.md)
163
164## c1.multimedia.5 ohos.multimedia.audio AudioRenderer接口write/AudioCapturer接口read废弃
165
166**访问级别**
167
168公开接口
169
170**废弃原因**
171
172AudioRenderer/AudioCapturer新增了writeData, readData订阅接口，通过回调请求方式，省去开发者自行管理数据处理时机的工作。
173并通过让系统管理数据请求时机，避免出现数据轮转时机不准确导致的underrun/overrun问题。
174
175**废弃影响**
176
177非兼容性变更，需要开发者进行适配。
178
179**废弃发生版本**
180
181从OpenHarmony SDK 4.1.6.5开始。
182
183**废弃的接口**
184
185接口属于AudioRenderer
186
187write(buffer: ArrayBuffer, callback: AsyncCallback<number>): void;
188
189write(buffer: ArrayBuffer): Promise<number>;
190
191接口属于AudioCapturer
192
193read(size: number, isBlockingRead: boolean, callback: AsyncCallback<ArrayBuffer>): void;
194
195read(size: number, isBlockingRead: boolean): Promise<ArrayBuffer>;
196
197**适配指导**
198
199根据废弃接口提示，使用新接口即可。
200
201AudioRenderer新接口：
202
203on(type: 'writeData', callback: Callback<ArrayBuffer>): void;
204
205off(type: 'writeData', callback?: Callback<ArrayBuffer>): void;
206
207通过订阅方式，收到Callback时，应用需要填写播放数据到ArrayBuffer内，Callback结束后，系统会自动从ArrayBuffer内取走数据进行输出。
208
209AudioCapturer新接口：
210
211on(type: 'readData', callback: Callback<ArrayBuffer>): void;
212
213off(type: 'readData', callback?: Callback<ArrayBuffer>): void;
214
215通过订阅方式，收到Callback时，应用需要从ArrayBuffer内取出录音数据，Callback结束后，系统会把后续录音数据填入ArrayBuffer，准备触发下次回调。
216
217废弃接口会在至少5个SDK版本内保持兼容，请应用按需规划适配计划
218
219## c1.multimedia.6 ohos.multimedia.audio 内录类型获取偏好录音设备行为变更
220
221**访问级别**
222
223公开接口
224
225**变更原因**
226
227在使用内录场景进行录音时，实际并不需要使用到麦克风录音设备，需要返回正确的设备类型
228
229**变更影响**
230
231兼容性变更，开发无需做任何适配
232
233**变更发生版本**
234
235从OpenHarmony SDK 4.1.6.5开始。
236
237**变更的接口/组件**
238
239AudioRoutingManager接口:
240
241getPreferredInputDeviceForCapturerInfo(capturerInfo: AudioCapturerInfo, callback: AsyncCallback<AudioDeviceDescriptors>): void
242
243getPreferredInputDeviceForCapturerInfo(capturerInfo: AudioCapturerInfo): Promise<AudioDeviceDescriptors>;
244
245变更前：
246
247当输入类型为SOURCE_TYPE_PLAYBACK_CAPTURE时，会返回设备类型为DeviceType.MIC的AudioDeviceDescriptor
248
249变更后：
250
251当输入类型为SOURCE_TYPE_PLAYBACK_CAPTURE时，会返回设备类型为DeviceType.INVALID的AudioDeviceDescriptor
252
253**适配指导**
254
255内录场景下的返回值结果修正，无需适配
256
257## c1.multimedia.7 ohos.multimedia.audio AudioManager系列订阅接口行为变更
258
259**访问级别**
260
261公开接口
262
263**变更原因**
264
265历史版本的订阅接口，实现不符合通用的订阅接口规范，并且可能导致应用订阅的回调被覆盖问题，需要整改
266
267**变更影响**
268
269如应用使用了多次订阅，预期应为订阅事件发生时，所有订阅过的回调函数会被遍历依次调用，而非仅回调最后一次订阅的
270
271**变更发生版本**
272
273从OpenHarmony SDK 4.1.6.5开始。
274
275**变更的接口/组件**
276
277AudioVolumeManager接口:
278
279on(type: 'volumeChange', callback: Callback<VolumeEvent>): void;
280
281AudioVolumeGroupManager接口:
282
283on(type: 'ringerModeChange', callback: Callback<AudioRingMode>): void;
284
285on(type: 'micStateChange', callback: Callback<MicStateChangeEvent>): void;
286
287AudioRoutingManager接口:
288
289on(type: 'deviceChange', deviceFlag: DeviceFlag, callback: Callback<DeviceChangeAction>): void;
290
291AudioStreamManager接口:
292
293on(type: 'audioRendererChange', callback: Callback<AudioRendererChangeInfoArray>): void;
294
295on(type: 'audioCapturerChange', callback: Callback<AudioCapturerChangeInfoArray>): void;
296
297变更前：
298
299当同一个事件被重复订阅多次，仅最后订阅的回调函数能收到事件发生的通知
300
301变更后：
302
303当同一个事件被重复订阅多次，所有未去订阅的回调函数，都能收到事件发生的通知
304
305**适配指导**
306
307一个事件仅订阅一次，无需适配
308
309一个事件被多次订阅，但预期是会被遍历回调，无需适配
310
311一个事件被多次订阅，但预期是仅有最后一个被回调，需要添加off去订阅，将不需要的回调函数从订阅列表删除
312
313## c1.multimedia.8 ohos.multimedia.audio availableDevice系统接口添加错误码
314
315**访问级别**
316
317系统接口
318
319**变更原因**
320
321系统接口添加相应错误码
322
323**变更影响**
324
325兼容性变更，开发无需做任何适配
326
327**变更发生版本**
328
329从OpenHarmony SDK 4.1.6.5开始。
330
331**变更的接口/组件**
332
333AudioRoutingManager接口:
334
335getAvailableDevices(deviceUsage: DeviceUsage): AudioDeviceDescriptors;
336
337on(type: 'availableDeviceChange', deviceUsage: DeviceUsage, callback: Callback<DeviceChangeAction>): void;
338
339off(type: 'availableDeviceChange', callback?: Callback<DeviceChangeAction>): void;
340
341变更前：
342
343三方应用调用系统接口时，返回默认结果，订阅不生效
344
345变更后：
346
347三方应用调用系统接口时，抛出通用错误码202
348
349**适配指导**
350
351系统应用使用，无需适配
352
353三方应用，不应该使用系统接口
354
355## c1.multimedia.9 ohos.multimedia.audioHaptic createPlayer权限声明
356
357**访问级别**
358
359公开接口
360
361**变更原因**
362
363AudioHapticPlayer内包含震动功能，这部分功能生效依赖ohos.permission.VIBRATE权限
364
365**变更影响**
366
367非兼容性变更，应用可按业务需要添加权限
368
369**变更发生版本**
370
371从OpenHarmony SDK 4.1.6.5开始。
372
373**变更的接口/组件**
374
375AudioHapticManager接口:
376
377createPlayer(id: number, options?: AudioHapticPlayerOptions): Promise<AudioHapticPlayer>;
378
379变更前：
380
381```
382/**
383 * Create an audio haptic player. This method uses a promise to return the result.
384 * @param { number } id - Source id.
385 * @param { AudioHapticPlayerOptions } options - Options when creating audio haptic player.
386 * @returns { Promise<AudioHapticPlayer> } Promise used to return the result.
387 * @throws { BusinessError } 401 - The parameter check failed.
388 * @throws { BusinessError } 5400102 - Operation not allowed.
389 * @throws { BusinessError } 5400103 - I/O error.
390 * @throws { BusinessError } 5400106 - Unsupport format.
391 * @syscap SystemCapability.Multimedia.AudioHaptic.Core
392 * @since 11
393 */
394```
395
396无权限声明，但若不申请权限，播放无法使能震动，仅音频播放
397
398变更后：
399
400```
401/**
402 * Create an audio haptic player. This method uses a promise to return the result. If haptics is needed, caller
403 * should have the permission of ohos.permission.VIBRATE.
404 * @permission ohos.permission.VIBRATE
405 * @param { number } id - Source id.
406 * @param { AudioHapticPlayerOptions } options - Options when creating audio haptic player.
407 * @returns { Promise<AudioHapticPlayer> } Promise used to return the result.
408 * @throws { BusinessError } 201 - Permission denied.
409 * @throws { BusinessError } 401 - The parameter check failed.
410 * @throws { BusinessError } 5400102 - Operation not allowed.
411 * @throws { BusinessError } 5400103 - I/O error.
412 * @throws { BusinessError } 5400106 - Unsupport format.
413 * @syscap SystemCapability.Multimedia.AudioHaptic.Core
414 * @since 11
415 */
416```
417
418含ohos.permission.VIBRATE权限声明和权限用途注释说明
419
420**适配指导**
421
422接口行为与修改前一致，如果应用需要使用震动能力，需要申请ohos.permission.VIBRATE权限
423
424## c1.multimedia.10 ohos.multimedia.audio AudioManager错误码实现错误修正
425
426**访问级别**
427
428公开接口
429
430**变更原因**
431
432公开接口，返回的错误码类型声明为number，但历史实现错误为string，实现修复
433
434**变更影响**
435
436声明无变更，遵循接口定义的开发者无需适配
437
438**变更发生版本**
439
440从OpenHarmony SDK 4.1.6.5开始。
441
442**变更的接口/组件**
443
444AudioManager接口:
445
446getVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void;
447
448getVolume(volumeType: AudioVolumeType): Promise<number>;
449
450getMaxVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void;
451
452getMaxVolume(volumeType: AudioVolumeType): Promise<number>;
453
454isMute(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void;
455
456isMute(volumeType: AudioVolumeType): Promise<boolean>;
457
458变更前：
459
460接口通过异步返回的BusinessError.code值类型为string
461
462变更后：
463
464接口通过异步返回的BusinessError.code值类型为number
465
466**适配指导**
467
468声明无变更，错误码本来就声明的就是number类型。
469
470如开发者根据历史接口实际返回结果主动发现返回的错误码不符合定义，而直接使用字符串校验，需要根据原有API定义适配，使用AudioErrors数字错误码。