@ohos.multimedia.audioHaptic (Audio-Haptic)
Audio-haptic enables users to get rhythmic auditory and haptic feedback while having incoming calls or messages.
NOTE
The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Modules to Import
import audioHaptic from '@ohos.multimedia.audioHaptic';
audioHaptic.getAudioHapticManager
getAudioHapticManager(): AudioHapticManager
Obtains an AudioHapticManager instance.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Return value
Type | Description |
---|---|
AudioHapticManager | AudioHapticManager instance. |
Example
let audioHapticManagerInstance: audioHaptic.AudioHapticManager = audioHaptic.getAudioHapticManager();
AudioLatencyMode
Enumerates the audio latency modes.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Name | Value | Description |
---|---|---|
AUDIO_LATENCY_MODE_NORMAL | 0 | Normal latency mode. |
AUDIO_LATENCY_MODE_FAST | 1 | Low latency mode. This mode is applicable to short audio files. A long audio file may be truncated in this mode. It functions the same as SoundPool. |
AudioHapticPlayerOptions
Describes the options for the audio-haptic player.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Name | Type | Mandatory | Description |
---|---|---|---|
muteAudio | boolean | No | Whether to mute the audio. The value true means to mute the audio, and false means the opposite. If this parameter is not specified, the default value false is used. |
muteHaptics | boolean | No | Whether to mute haptics feedback. The value true means to mute haptics feedback, and false means the opposite. If this parameter is not specified, the default value false is used. |
AudioHapticManager
Manages the audio-haptic feature. Before calling any API in AudioHapticManager, you must use getAudioHapticManager to create an AudioHapticManager instance.
registerSource
registerSource(audioUri: string, hapticUri: string): Promise<number>
Registers an audio-haptic source. This API uses a promise to return the result.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
audioUri | string | Yes | URI of the audio source. In normal latency mode, the supported audio resource formats and path formats are defined in media.AVPlayer. In low latency mode, the supported audio resource formats are defined in SoundPool, and the path format must meet the requirements of fs.open. In both modes, you are advised to pass in the absolute path of the file. |
hapticUri | string | Yes | URI of the haptic source. The supported haptic resource formats are defined in vibrator. The path format must meet the requirements of fs.open. You are advised to pass in the absolute path of the file. |
Return value
Type | Description |
---|---|
Promise<number> | Promise used to return the source ID. |
Example
import { BusinessError } from '@ohos.base';
let audioUri = 'data/audioTest.wav'; // Change it to the URI of the target audio source.
let hapticUri = 'data/hapticTest.json'; // Change it to the URI of the target haptic source.
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<void>
Unregisters an audio-haptic source. This API uses a promise to return the result.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | number | Yes | Source ID. |
Example
import { BusinessError } from '@ohos.base';
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
Sets the latency mode for an audio-haptic source.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | number | Yes | Source ID. |
latencyMode | AudioLatencyMode | Yes | Audio latency mode. |
Error codes
For details about the error codes, see Media Error Codes.
ID | Error Message |
---|---|
5400102 | Operation not allowed. |
Example
let latencyMode: audioHaptic.AudioLatencyMode = audioHaptic.AudioLatencyMode.AUDIO_LATENCY_MODE_FAST;
audioHapticManagerInstance.setAudioLatencyMode(id, latencyMode);
setStreamUsage
setStreamUsage(id: number, usage: audio.StreamUsage): void
Sets the stream usage for an audio-haptic source.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | number | Yes | Source ID. |
usage | audio.StreamUsage | Yes | Stream usage. |
Error codes
For details about the error codes, see Media Error Codes.
ID | Error Message |
---|---|
5400102 | Operation not allowed. |
Example
import audio from '@ohos.multimedia.audio';
let usage: audio.StreamUsage = audio.StreamUsage.STREAM_USAGE_NOTIFICATION;
audioHapticManagerInstance.setStreamUsage(id, usage);
createPlayer
createPlayer(id: number, options?: AudioHapticPlayerOptions): Promise<AudioHapticPlayer>
Creates an audio-haptic player. This API uses a promise to return the result.
Required permissions: ohos.permission.VIBRATE
If the audio-haptic player needs to trigger vibration, check whether the application has the permission.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
id | number | Yes | Source ID. |
options | AudioHapticPlayerOptions | No | Options of the audio-haptic player. |
Return value
Type | Description |
---|---|
Promise<AudioHapticPlayer> | Promise used to return the audio-haptic player. |
Error codes
For details about the error codes, see Media Error Codes.
ID | Error Message |
---|---|
5400102 | Operation not allowed. |
5400103 | I/O error. |
5400106 | Unsupport format. |
Example
import { BusinessError } from '@ohos.base';
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
Enumerates the audio haptic types.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Name | Value | Description |
---|---|---|
AUDIO_HAPTIC_TYPE_AUDIO | 0 | Audio. |
AUDIO_HAPTIC_TYPE_HAPTIC | 1 | Haptic. |
AudioHapticPlayer
Implements audio-haptic playback. Before calling any API in AudioHapticPlayer, you must use createPlayer to create an AudioHapticPlayer instance.
isMuted
isMuted(type: AudioHapticType): boolean
Checks whether an audio-haptic type is muted.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | AudioHapticType | Yes | Audio-haptic type. |
Return value
Type | Description |
---|---|
boolean | Whether the audio-haptic type is muted. |
Example
let audioHapticType: audioHaptic.AudioHapticType = audioHaptic.AudioHapticType.AUDIO_HAPTIC_TYPE_AUDIO;
let result: boolean = audioHapticPlayerInstance.isMuted(audioHapticType);
start
start(): Promise<void>
Starts playing the audio and haptic source. This API uses a promise to return the result.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
For details about the error codes, see Media Error Codes.
ID | Error Message |
---|---|
5400102 | Operate not permit. |
5400103 | IO error. |
5400105 | Service died. |
Example
import { BusinessError } from '@ohos.base';
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<void>
Stops playing the audio-haptic source. This API uses a promise to return the result.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
For details about the error codes, see Media Error Codes.
ID | Error Message |
---|---|
5400102 | Operate not permit. |
5400105 | Service died. |
Example
import { BusinessError } from '@ohos.base';
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<void>
Releases this audio-haptic player. This API uses a promise to return the result.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
For details about the error codes, see Media Error Codes.
ID | Error Message |
---|---|
5400105 | Service died. |
Example
import { BusinessError } from '@ohos.base';
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>): void
Subscribes to end of stream (EOS) events. This API uses a callback to obtain the events.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is fixed at 'endOfStream'. |
callback | Callback<void> | Yes | Callback triggered when the event is received. |
Example
audioHapticPlayerInstance.on('endOfStream', async() => {
console.info(`Receive the callback of endOfStream.`);
});
off('endOfStream')
off(type: 'endOfStream', callback?: Callback<void>): void
Unsubscribes from EOS events.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is fixed at 'endOfStream'. |
callback | Callback<void> | No | Callback used for unsubscription. |
Example
audioHapticPlayerInstance.off('endOfStream');
on('audioInterrupt')
on(type: 'audioInterrupt', callback: Callback<audio.InterruptEvent>): void
Subscribes to audio interruption events. This API uses a callback to obtain the events.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is fixed at 'audioInterrupt'. |
callback | Callback<audio.InterruptEvent> | Yes | Callback triggered when the event is received. |
Example
let isPlaying: boolean; // An identifier specifying whether rendering is in progress.
let isDucked: boolean; // An identifier specifying whether the audio volume is reduced.
audioHapticPlayerInstance.on('audioInterrupt', async(interruptEvent: audio.InterruptEvent) => {
if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) {
// The system forcibly interrupts audio rendering. The application must update the status and displayed content accordingly.
switch (interruptEvent.hintType) {
case audio.InterruptHint.INTERRUPT_HINT_PAUSE:
// The audio stream has been paused and temporarily loses the focus. It will receive the interruptEvent corresponding to resume when it is able to regain the focus.
console.info('Force paused. Update playing status and stop writing');
isPlaying = false; // A simplified processing indicating several operations for switching the application to the paused state.
break;
case audio.InterruptHint.INTERRUPT_HINT_STOP:
// The audio stream has been stopped and permanently loses the focus. The user must manually trigger the operation to resume rendering.
console.info('Force stopped. Update playing status and stop writing');
isPlaying = false; // A simplified processing indicating several operations for switching the application to the paused state.
break;
case audio.InterruptHint.INTERRUPT_HINT_DUCK:
// The audio stream is rendered at a reduced volume.
console.info('Force ducked. Update volume status');
isDucked = true; // A simplified processing indicating several operations for updating the volume status.
break;
case audio.InterruptHint.INTERRUPT_HINT_UNDUCK:
// The audio stream is rendered at the normal volume.
console.info('Force ducked. Update volume status');
isDucked = false; // A simplified processing indicating several operations for updating the volume status.
break;
default:
break;
}
} else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) {
// The application can choose to take action or ignore.
switch (interruptEvent.hintType) {
case audio.InterruptHint.INTERRUPT_HINT_RESUME:
// It is recommended that the application continue rendering. (The audio stream has been forcibly paused and temporarily lost the focus. It can resume rendering now.)
console.info('Resume force paused renderer or ignore');
// To continue rendering, the application must perform the required operations.
break;
default:
break;
}
}
});
off('audioInterrupt')
off(type: 'audioInterrupt', callback?: Callback<audio.InterruptEvent>): void
Unsubscribes from audio interruption events.
System capability: SystemCapability.Multimedia.AudioHaptic.Core
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes | Event type. The value is fixed at 'audioInterrupt'. |
callback | Callback<void> | No | Callback used for unsubscription. |
Example
audioHapticPlayerInstance.off('audioInterrupt');