鸿蒙5.0&next开发【@ohos.multimedia.audioHaptic (音振协同)】 音频服务

于 2025-03-28 20:16:25 发布
阅读量557 收藏 15
点赞数 26
分类专栏： 鸿蒙开发 文章标签： harmonyos 音视频 华为 鸿蒙系统 鸿蒙
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/m0_70748845/article/details/146609043
版权

音振协同，表示在播放声音时，可同步发起振动。可用于来电通知、消息提醒等场景。

说明

本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import { audioHaptic } from '@kit.AudioKit';

audioHaptic.getAudioHapticManager

getAudioHapticManager(): AudioHapticManager

获取音振管理器。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

返回值：

类型说明
[AudioHapticManager]音振管理器。

示例：

let audioHapticManagerInstance: audioHaptic.AudioHapticManager = audioHaptic.getAudioHapticManager();

AudioLatencyMode

枚举，音频时延模式。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

名称值说明
AUDIO_LATENCY_MODE_NORMAL0普通时延模式。
AUDIO_LATENCY_MODE_FAST1低时延模式。该模式适用于比较短的音频文件，音频文件过长时可能被截断，该特性与[SoundPool]一致。

AudioHapticPlayerOptions

音振播放器选项。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

名称类型必填说明
muteAudioboolean否是否将音频静音，true表示将音频静音，false表示正常播放声音。若不填该参数，则默认为false。
muteHapticsboolean否是否禁止振动，true表示将禁止振动，false表示正常振动。若不填该参数，则默认为false。

AudioHapticManager

管理音振协同功能。在调用AudioHapticManager的接口前，需要先通过[getAudioHapticManager]创建实例。

registerSource

registerSource(audioUri: string, hapticUri: string): Promise

注册音频和振动资源的Uri，使用Promise方式异步返回结果。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

参数：

参数名类型必填说明
audioUristring是音频资源的Uri。对普通时延模式，音频资源格式和路径格式的支持可参考[media.AVPlayer]；对低时延模式，音频资源格式支持可参考[SoundPool]，路径格式需满足[文件管理模块open函数]的要求。对两种时延模式，均建议传入文件的绝对路径。
hapticUristring是振动资源的Uri。振动资源格式支持可参考[vibrator]，路径格式需满足[文件管理模块open函数]的要求。建议传入文件的绝对路径。

返回值：

类型说明
PromisePromise回调返回注册资源的source id。
错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let audioUri = 'data/audioTest.wav'; // 需更改为目标音频资源的Uri。
let hapticUri = 'data/hapticTest.json'; // 需更改为目标振动资源的Uri。
let id = 0;

audioHapticManagerInstance.registerSource(audioUri, hapticUri).then((value: number) => {
  console.info(`Promise returned to indicate that the source id of the registerd source ${value}.`);
  id = value;
}).catch ((err: BusinessError) => {
  console.error(`Failed to register source ${err}`);
});

unregisterSource

unregisterSource(id: number): Promise

取消注册音频和振动资源，使用Promise方式异步返回结果。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

参数：

参数名类型必填说明
idnumber是已注册资源的source id。
错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let audioUri = 'data/audioTest.wav'; // 需更改为目标音频资源的Uri。
let hapticUri = 'data/hapticTest.json'; // 需更改为目标振动资源的Uri。
let id = 0;

audioHapticManagerInstance.registerSource(audioUri, hapticUri).then((value: number) => {
  console.info(`Promise returned to indicate that the source id of the registerd source ${value}.`);
  id = value;
}).catch ((err: BusinessError) => {
  console.error(`Failed to register source ${err}`);
});

audioHapticManagerInstance.unregisterSource(id).then(() => {
  console.info(`Promise returned to indicate that unregister source successfully`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to unregistere source ${err}`);
});

setAudioLatencyMode

setAudioLatencyMode(id:number, latencyMode: AudioLatencyMode): void

设置音频时延模式。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

参数：

参数名类型必填说明
idnumber是已注册资源的source id。
latencyMode[AudioLatencyMode]是音频时延模式。
错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
5400102Operation not allowed.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let audioUri = 'data/audioTest.wav'; // 需更改为目标音频资源的Uri。
let hapticUri = 'data/hapticTest.json'; // 需更改为目标振动资源的Uri。
let id = 0;

audioHapticManagerInstance.registerSource(audioUri, hapticUri).then((value: number) => {
  console.info(`Promise returned to indicate that the source id of the registerd source ${value}.`);
  id = value;
}).catch ((err: BusinessError) => {
  console.error(`Failed to register source ${err}`);
});

let latencyMode: audioHaptic.AudioLatencyMode = audioHaptic.AudioLatencyMode.AUDIO_LATENCY_MODE_FAST;

audioHapticManagerInstance.setAudioLatencyMode(id, latencyMode);

setStreamUsage

setStreamUsage(id: number, usage: audio.StreamUsage): void

设置音频流使用类型。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

参数：

参数名类型必填说明
idnumber是已注册资源的source id。
usage[audio.StreamUsage]是音频流使用类型。
错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed.
5400102Operation not allowed.

示例：

import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';

let audioUri = 'data/audioTest.wav'; // 需更改为目标音频资源的Uri。
let hapticUri = 'data/hapticTest.json'; // 需更改为目标振动资源的Uri。
let id = 0;

audioHapticManagerInstance.registerSource(audioUri, hapticUri).then((value: number) => {
  console.info(`Promise returned to indicate that the source id of the registerd source ${value}.`);
  id = value;
}).catch ((err: BusinessError) => {
  console.error(`Failed to register source ${err}`);
});

let usage: audio.StreamUsage = audio.StreamUsage.STREAM_USAGE_NOTIFICATION;

audioHapticManagerInstance.setStreamUsage(id, usage);

createPlayer

createPlayer(id: number, options?: AudioHapticPlayerOptions): Promise

创建音振播放器，使用Promise方式异步返回结果。

需要权限：  ohos.permission.VIBRATE

如果应用创建的AudioHapticPlayer需要触发振动，则需要校验应用是否拥有该权限。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

参数：

参数名类型必填说明
idnumber是已注册资源的source id。
options[AudioHapticPlayerOptions]否音振播放器选项。

返回值：

类型说明
Promise<[AudioHapticPlayer]>Promise回调返回创建的音振播放器。
错误码ID错误信息
201Permission denied.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
5400102Operation not allowed.
5400103I/O error.
5400106Unsupport format.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

let audioUri = 'data/audioTest.wav'; // 需更改为目标音频资源的Uri。
let hapticUri = 'data/hapticTest.json'; // 需更改为目标振动资源的Uri。
let id = 0;

audioHapticManagerInstance.registerSource(audioUri, hapticUri).then((value: number) => {
  console.info(`Promise returned to indicate that the source id of the registerd source ${value}.`);
  id = value;
}).catch ((err: BusinessError) => {
  console.error(`Failed to register source ${err}`);
});

let options: audioHaptic.AudioHapticPlayerOptions = {muteAudio: false, muteHaptics: false};
let audioHapticPlayerInstance: audioHaptic.AudioHapticPlayer | undefined = undefined;

audioHapticManagerInstance.createPlayer(id, options).then((value: audioHaptic.AudioHapticPlayer) => {
  audioHapticPlayerInstance = value;
  console.info(`Create the audio haptic player successfully.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to create the audio haptic player. ${err}`);
});

AudioHapticType

枚举，音振类型。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

名称值说明
AUDIO_HAPTIC_TYPE_AUDIO0音频。
AUDIO_HAPTIC_TYPE_HAPTIC1振动。

AudioHapticPlayer

音振播放器，提供音振协同播放功能。在调用AudioHapticPlayer的接口前，需要先通过[createPlayer])创建实例。

isMuted

isMuted(type: AudioHapticType): boolean

查询该音振类型是否被静音。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

参数：

参数名类型必填说明
type[AudioHapticType]是音振类型。

返回值：

类型说明
boolean查询的音振类型是否被静音。
错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Parameter verification failed.

示例：

let audioHapticType: audioHaptic.AudioHapticType = audioHaptic.AudioHapticType.AUDIO_HAPTIC_TYPE_AUDIO;

let result: boolean = audioHapticPlayerInstance.isMuted(audioHapticType);

start

start(): Promise

开始播放，使用Promise方式异步返回结果。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

返回值：

类型说明
PromisePromise回调返回开始播放成功或失败。
错误码ID错误信息
5400102Operate not permit.
5400103IO error.
5400105Service died.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

audioHapticPlayerInstance.start().then(() => {
  console.info(`Promise returned to indicate that start playing successfully.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to start playing. ${err}`);
});

stop

stop(): Promise

停止播放，使用Promise方式异步返回结果。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

返回值：

类型说明
PromisePromise回调返回停止播放成功或失败。
错误码ID错误信息
5400102Operate not permit.
5400105Service died.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

audioHapticPlayerInstance.stop().then(() => {
  console.info(`Promise returned to indicate that stop playing successfully.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to stop playing. ${err}`);
});

release

release(): Promise

释放音振播放器，使用Promise方式异步返回结果。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

返回值：

类型说明
PromisePromise回调返回释放成功或失败。
错误码ID错误信息
5400105Service died.

示例：

import { BusinessError } from '@kit.BasicServicesKit';

audioHapticPlayerInstance.release().then(() => {
  console.info(`Promise returned to indicate that release the audio haptic player successfully.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to release the audio haptic player. ${err}`);
});

on(‘endOfStream’)

on(type: ‘endOfStream’, callback: Callback): void

监听流结束事件（音频流播放结束时触发），使用callback方式返回结果。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

参数：

参数名类型必填说明
typestring是事件回调类型，支持的事件为：‘endOfStream’（流结束事件）。
callbackCallback是回调函数，无返回结果。

示例：

audioHapticPlayerInstance.on('endOfStream', () => {
  console.info(`Receive the callback of endOfStream.`);
});

off(‘endOfStream’)

off(type: ‘endOfStream’, callback?: Callback): void

取消监听流结束事件，使用callback方式返回结果。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

参数：

参数名类型必填说明
typestring是要取消订阅事件的类型。支持的事件为：‘endOfStream’。
callbackCallback否回调函数，无返回结果。

示例：

// 取消该事件的所有监听。
audioHapticPlayerInstance.off('endOfStream');

// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。
let endOfStreamCallback = () => {
  console.info(`Receive the callback of endOfStream.`);
};

audioHapticPlayerInstance.on('endOfStream', endOfStreamCallback);

audioHapticPlayerInstance.off('endOfStream', endOfStreamCallback);

on(‘audioInterrupt’)

on(type: ‘audioInterrupt’, callback: Callback<audio.InterruptEvent>): void

监听音频中断事件（当音频焦点发生变化时触发），使用callback方式返回结果。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

参数：

参数名类型必填说明
typestring是事件回调类型，支持的事件为：‘audioInterrupt’（音频中断事件）。
callbackCallback<[audio.InterruptEvent]>是回调函数，返回播放中断时，应用接收的中断事件信息。

示例：

import { audio } from '@kit.AudioKit';

let isPlaying: boolean; // 标识符，表示是否正在渲染。
let isDucked: boolean; // 标识符，表示是否被降低音量。

audioHapticPlayerInstance.on('audioInterrupt', (interruptEvent: audio.InterruptEvent) => {
  // 在发生音频打断事件时，audioHapticPlayerInstance收到interruptEvent回调，此处根据其内容做相应处理。
  // 1、可选：读取interruptEvent.forceType的类型，判断系统是否已强制执行相应操作。
  // 注：默认焦点策略下，INTERRUPT_HINT_RESUME为INTERRUPT_SHARE类型，其余hintType均为INTERRUPT_FORCE类型。因此对forceType可不做判断。
  // 2、必选：读取interruptEvent.hintType的类型，做出相应的处理。
  if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) {
    // 音频焦点事件已由系统强制执行，应用需更新自身状态及显示内容等。
    switch (interruptEvent.hintType) {
      case audio.InterruptHint.INTERRUPT_HINT_PAUSE:
        // 音频流已被暂停，临时失去焦点，待可重获焦点时会收到resume对应的interruptEvent。
        console.info('Force paused. Update playing status and stop writing');
        isPlaying = false; // 简化处理，代表应用切换至暂停状态的若干操作。
        break;
      case audio.InterruptHint.INTERRUPT_HINT_STOP:
        // 音频流已被停止，永久失去焦点，若想恢复渲染，需用户主动触发。
        console.info('Force stopped. Update playing status and stop writing');
        isPlaying = false; // 简化处理，代表应用切换至暂停状态的若干操作。
        break;
      case audio.InterruptHint.INTERRUPT_HINT_DUCK:
        // 音频流已被降低音量渲染。
        console.info('Force ducked. Update volume status');
        isDucked = true; // 简化处理，代表应用更新音量状态的若干操作。
        break;
      case audio.InterruptHint.INTERRUPT_HINT_UNDUCK:
        // 音频流已被恢复正常音量渲染。
        console.info('Force ducked. Update volume status');
        isDucked = false; // 简化处理，代表应用更新音量状态的若干操作。
        break;
      default:
        break;
    }
  } else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) {
    // 音频焦点事件需由应用进行操作，应用可以自主选择如何处理该事件，建议应用遵从InterruptHint提示处理。
    switch (interruptEvent.hintType) {
      case audio.InterruptHint.INTERRUPT_HINT_RESUME:
        // 建议应用继续渲染（说明音频流此前被强制暂停，临时失去焦点，现在可以恢复渲染）。
        // 由于INTERRUPT_HINT_RESUME操作需要应用主动执行，系统无法强制，故INTERRUPT_HINT_RESUME事件一定为INTERRUPT_SHARE类型。
        console.info('Resume force paused renderer or ignore');
        // 若选择继续渲染，需在此处主动执行开始渲染的若干操作。
        break;
      default:
        break;
    }
  }
});

off(‘audioInterrupt’)

off(type: ‘audioInterrupt’, callback?: Callback<audio.InterruptEvent>): void

取消监听音频中断事件，使用callback方式返回结果。

系统能力：  SystemCapability.Multimedia.AudioHaptic.Core

参数：

参数名类型必填说明
typestring是要取消订阅事件的类型。支持的事件为：‘audioInterrupt’。
callbackCallback<[audio.InterruptEvent]>否回调函数，取消监听时，返回应用中断事件信息。

示例：

import { audio } from '@kit.AudioKit';

// 取消该事件的所有监听。
audioHapticPlayerInstance.off('audioInterrupt');

// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。
let isPlaying: boolean; // 标识符，表示是否正在渲染。
let isDucked: boolean; // 标识符，表示是否被降低音量。
let audioInterruptCallback = (interruptEvent: audio.InterruptEvent) => {
  // 在发生音频打断事件时，audioHapticPlayerInstance收到interruptEvent回调，此处根据其内容做相应处理。
  // 1、可选：读取interruptEvent.forceType的类型，判断系统是否已强制执行相应操作。
  // 注：默认焦点策略下，INTERRUPT_HINT_RESUME为INTERRUPT_SHARE类型，其余hintType均为INTERRUPT_FORCE类型。因此对forceType可不做判断。
  // 2、必选：读取interruptEvent.hintType的类型，做出相应的处理。
  if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) {
    // 音频焦点事件已由系统强制执行，应用需更新自身状态及显示内容等。
    switch (interruptEvent.hintType) {
      case audio.InterruptHint.INTERRUPT_HINT_PAUSE:
        // 音频流已被暂停，临时失去焦点，待可重获焦点时会收到resume对应的interruptEvent。
        console.info('Force paused. Update playing status and stop writing');
        isPlaying = false; // 简化处理，代表应用切换至暂停状态的若干操作。
        break;
      case audio.InterruptHint.INTERRUPT_HINT_STOP:
        // 音频流已被停止，永久失去焦点，若想恢复渲染，需用户主动触发。
        console.info('Force stopped. Update playing status and stop writing');
        isPlaying = false; // 简化处理，代表应用切换至暂停状态的若干操作。
        break;
      case audio.InterruptHint.INTERRUPT_HINT_DUCK:
        // 音频流已被降低音量渲染。
        console.info('Force ducked. Update volume status');
        isDucked = true; // 简化处理，代表应用更新音量状态的若干操作。
        break;
      case audio.InterruptHint.INTERRUPT_HINT_UNDUCK:
        // 音频流已被恢复正常音量渲染。
        console.info('Force ducked. Update volume status');
        isDucked = false; // 简化处理，代表应用更新音量状态的若干操作。
        break;
      default:
        break;
    }
  } else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) {
    // 音频焦点事件需由应用进行操作，应用可以自主选择如何处理该事件，建议应用遵从InterruptHint提示处理。
    switch (interruptEvent.hintType) {
      case audio.InterruptHint.INTERRUPT_HINT_RESUME:
        // 建议应用继续渲染（说明音频流此前被强制暂停，临时失去焦点，现在可以恢复渲染）。
        // 由于INTERRUPT_HINT_RESUME操作需要应用主动执行，系统无法强制，故INTERRUPT_HINT_RESUME事件一定为INTERRUPT_SHARE类型。
        console.info('Resume force paused renderer or ignore');
        // 若选择继续渲染，需在此处主动执行开始渲染的若干操作。
        break;
      default:
        break;
    }
  }
};

audioHapticPlayerInstance.on('audioInterrupt', audioInterruptCallback);

audioHapticPlayerInstance.off('audioInterrupt', audioInterruptCallback);
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值