1/* 2 * Copyright (c) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit AudioKit 19 */ 20 21import type { Callback } from './@ohos.base'; 22import type audio from './@ohos.multimedia.audio'; 23 24/** 25 * Provides audio haptic collaborative play interfaces. 26 * 27 * @namespace audioHaptic 28 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 29 * @since 11 30 */ 31declare namespace audioHaptic { 32 /** 33 * Obtains an {@link AudioHapticManager} instance. This object is singleton in one process. 34 * @returns { AudioHapticManager } AudioHapticManager instance. 35 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 36 * @since 11 37 */ 38 function getAudioHapticManager(): AudioHapticManager; 39 40 /** 41 * Audio Latency mode. 42 * @enum {number} 43 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 44 * @since 11 45 */ 46 enum AudioLatencyMode { 47 /** 48 * Normal audio mode. 49 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 50 * @since 11 51 */ 52 AUDIO_LATENCY_MODE_NORMAL = 0, 53 54 /** 55 * Low latency mode. This mode should be used when duration of the audio source is short. If duration of the audio 56 * source is long, it may be truncated. This behavior is the same with sound pool. 57 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 58 * @since 11 59 */ 60 AUDIO_LATENCY_MODE_FAST = 1 61 } 62 63 /** 64 * Audio haptic player options object. 65 * @typedef AudioHapticPlayerOptions 66 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 67 * @since 11 68 */ 69 interface AudioHapticPlayerOptions { 70 /** 71 * Mute audio. 72 * @type {?boolean} 73 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 74 * @since 11 75 */ 76 muteAudio?: boolean; 77 78 /** 79 * Mute haptics. 80 * @type {?boolean} 81 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 82 * @since 11 83 */ 84 muteHaptics?: boolean; 85 } 86 87 /** 88 * Audio haptic manager object. 89 * @typedef AudioHapticManager 90 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 91 * @since 11 92 */ 93 interface AudioHapticManager { 94 /** 95 * Register audio and haptic file into manager. Audio and haptic works are paired while playing. After registering 96 * source, it will returns the source id. This method uses a promise to return the source id. 97 * @param { string } audioUri - Audio file uri. 98 * @param { string } hapticUri - Haptic file uri. 99 * @returns { Promise<number> } Promise used to return the source id. 100 * @throws { BusinessError } 401 - Parameter error. Possible causes: 101 * 1.Mandatory parameters are left unspecified; 102 * 2.Incorrect parameter types. 103 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 104 * @since 11 105 */ 106 registerSource(audioUri: string, hapticUri: string): Promise<number>; 107 108 /** 109 * Unregister source. This method uses a promise to return the result. 110 * @param { number } id source id. 111 * @returns { Promise<void> } Promise used to return the result. 112 * @throws { BusinessError } 401 - Parameter error. Possible causes: 113 * 1.Mandatory parameters are left unspecified; 114 * 2.Incorrect parameter types. 115 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 116 * @since 11 117 */ 118 unregisterSource(id: number): Promise<void>; 119 120 /** 121 * Set the audio latency mode of one source. 122 * @param { number } id - Source id. 123 * @param { AudioLatencyMode } latencyMode - Audio latency mode. 124 * @throws { BusinessError } 401 - Parameter error. Possible causes: 125 * 1.Mandatory parameters are left unspecified; 126 * 2.Incorrect parameter types. 127 * @throws { BusinessError } 5400102 - Operation not allowed. 128 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 129 * @since 11 130 */ 131 setAudioLatencyMode(id:number, latencyMode: AudioLatencyMode): void; 132 133 /** 134 * Set the stream usage of one source. 135 * @param { number } id - Source id. 136 * @param { audio.StreamUsage } usage - Stream usage. 137 * @throws { BusinessError } 401 - Parameter error. Possible causes: 138 * 1.Mandatory parameters are left unspecified; 139 * 2.Incorrect parameter types; 140 * 3.Parameter verification failed. 141 * @throws { BusinessError } 5400102 - Operation not allowed. 142 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 143 * @since 11 144 */ 145 setStreamUsage(id: number, usage: audio.StreamUsage): void; 146 147 /** 148 * Create an audio haptic player. This method uses a promise to return the result. If haptics is needed, caller 149 * should have the permission of ohos.permission.VIBRATE. 150 * @permission ohos.permission.VIBRATE 151 * @param { number } id - Source id. 152 * @param { AudioHapticPlayerOptions } options - Options when creating audio haptic player. 153 * @returns { Promise<AudioHapticPlayer> } Promise used to return the result. 154 * @throws { BusinessError } 201 - Permission denied. 155 * @throws { BusinessError } 401 - Parameter error. Possible causes: 156 * 1.Mandatory parameters are left unspecified; 157 * 2.Incorrect parameter types. 158 * @throws { BusinessError } 5400102 - Operation not allowed. 159 * @throws { BusinessError } 5400103 - I/O error. 160 * @throws { BusinessError } 5400106 - Unsupport format. 161 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 162 * @since 11 163 */ 164 createPlayer(id: number, options?: AudioHapticPlayerOptions): Promise<AudioHapticPlayer>; 165 166 /** 167 * Register audio and haptic file represented by fd into manager. Audio and haptic works are paired while playing. 168 * After registering source, it will returns the source id. This method uses a promise to return the source id. 169 * @param { AudioHapticFileDescriptor } audioFd : The file descriptor of audio source from file system. 170 * @param { AudioHapticFileDescriptor } hapticFd : The file descriptor of haptic source from file system. 171 * @returns { Promise<number> } Promise used to return the source id. 172 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 173 * @since 20 174 */ 175 registerSourceFromFd(audioFd: AudioHapticFileDescriptor, hapticFd: AudioHapticFileDescriptor): Promise<number>; 176 } 177 178 /** 179 * Type of audio haptic. 180 * @enum {number} 181 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 182 * @since 11 183 */ 184 enum AudioHapticType { 185 /** 186 * Audio. 187 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 188 * @since 11 189 */ 190 AUDIO_HAPTIC_TYPE_AUDIO = 0, 191 192 /** 193 * Haptic. 194 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 195 * @since 11 196 */ 197 AUDIO_HAPTIC_TYPE_HAPTIC = 1, 198 } 199 200 /** 201 * Describes audio haptic file descriptor. 202 * Caller needs to ensure the fd is valid and the offset and length are correct. 203 * @typedef AudioHapticFileDescriptor 204 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 205 * @since 20 206 */ 207 interface AudioHapticFileDescriptor { 208 /** 209 * The file descriptor of the source. 210 * @type { number } 211 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 212 * @since 20 213 */ 214 fd: number; 215 216 /** 217 * The length in bytes of the data to be read. 218 * By default, the length is the rest of bytes in the file from the offset. 219 * @type { ?number } 220 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 221 * @since 20 222 */ 223 length?: number; 224 225 /** 226 * The offset into the file where the data to be read. 227 * By default, the offset is 0. 228 * @type { ?number } 229 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 230 * @since 20 231 */ 232 offset?: number 233 } 234 235 /** 236 * Audio haptic player object. 237 * @typedef AudioHapticPlayer 238 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 239 * @since 11 240 */ 241 interface AudioHapticPlayer { 242 /** 243 * Is muted for one AudioHapticType 244 * @param { AudioHapticType } type - Indicates the type to query. 245 * @returns { boolean } - Is muted. 246 * @throws { BusinessError } 401 - Parameter error. Possible causes: 247 * 1.Mandatory parameters are left unspecified; 248 * 2.Parameter verification failed. 249 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 250 * @since 11 251 */ 252 isMuted(type: AudioHapticType): boolean; 253 254 /** 255 * Start this player. This method uses a promise to return the result. 256 * @returns { Promise<void> } Promise used to return the result. 257 * @throws { BusinessError } 5400102 - Operate not permit. 258 * @throws { BusinessError } 5400103 - IO error. 259 * @throws { BusinessError } 5400105 - Service died. 260 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 261 * @since 11 262 */ 263 start(): Promise<void>; 264 265 /** 266 * Stop this player. This method uses a promise to return the result. 267 * @returns { Promise<void> } Promise used to return the result. 268 * @throws { BusinessError } 5400102 - Operate not permit. 269 * @throws { BusinessError } 5400105 - Service died. 270 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 271 * @since 11 272 */ 273 stop(): Promise<void>; 274 275 /** 276 * Release this player. This method uses a promise to return the result. 277 * @returns { Promise<void> } Promise used to return the result. 278 * @throws { BusinessError } 5400105 - Service died. 279 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 280 * @since 11 281 */ 282 release(): Promise<void>; 283 284 /** 285 * Subscribes end of stream event. 286 * @param { 'endOfStream' } type - Type of the playback event to listen for. 287 * @param { Callback<void> } callback - Callback used to listen for the playback end of stream. 288 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 289 * @since 11 290 */ 291 on(type: 'endOfStream', callback: Callback<void>): void; 292 293 /** 294 * Unsubscribes end of stream event. 295 * @param { 'endOfStream' } type - Type of the playback event to listen for. 296 * @param { Callback<void> } callback - Callback used to listen for the playback end of stream. 297 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 298 * @since 11 299 */ 300 off(type: 'endOfStream', callback?: Callback<void>): void; 301 302 /** 303 * Subscribes audio interrupt event. 304 * @param { 'audioInterrupt' } type - Type of the playback event to listen for. 305 * @param { Callback<audio.InterruptEvent> } callback - Callback used to listen for audio interrupt info. 306 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 307 * @since 11 308 */ 309 on(type: 'audioInterrupt', callback: Callback<audio.InterruptEvent>): void; 310 311 /** 312 * Unsubscribes audio interrupt event. 313 * @param { 'audioInterrupt' } type - Type of the playback event to listen for. 314 * @param { Callback<audio.InterruptEvent> } callback - Callback used to listen for audio interrupt info. 315 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 316 * @since 11 317 */ 318 off(type: 'audioInterrupt', callback?: Callback<audio.InterruptEvent>): void; 319 320 /** 321 * Enable haptics when the ringer mode is silent mode. 322 * This function should be called before player start or after stop, and before release. 323 * @param { boolean } enable - use {@code true} if application want to enable this feature. 324 * @throws { BusinessError } 202 - Caller is not a system application. 325 * @throws { BusinessError } 5400102 - Operate not permit in current state. 326 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 327 * @systemapi 328 * @since 20 329 */ 330 enableHapticsInSilentMode(enable: boolean): void; 331 332 /** 333 * Set audio volume for this player. This method uses a promise to return the result. 334 * This function should be called before player release. 335 * @param { number } volume - Target audio volume. 336 * The value ranges from 0.00 to 1.00. 1.00 indicates the maximum volume (100%). 337 * @returns { Promise<void> } Promise used to return the result. 338 * @throws { BusinessError } 5400102 - Operate not permit in current state. 339 * @throws { BusinessError } 5400105 - Service died. 340 * @throws { BusinessError } 5400108 - Parameter out of range. 341 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 342 * @since 20 343 */ 344 setVolume(volume: number): Promise<void>; 345 346 /** 347 * Check whether the device supports haptics intensity adjustment. 348 * @returns { boolean } - {@code true} means supported. 349 * @throws { BusinessError } 202 - Caller is not a system application. 350 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 351 * @systemapi 352 * @since 20 353 */ 354 isHapticsIntensityAdjustmentSupported(): boolean; 355 356 /** 357 * Set haptics intensity for this player. This method uses a promise to return the result. 358 * This function should be called before player release, and can only set once for each starting process. 359 * @param { number } intensity - Target Haptics intensity value. 360 * The value ranges from 0.00 to 1.00. 1.00 indicates the maximum intensity (100%). 361 * @returns { Promise<void> } Promise used to return the result. 362 * @throws { BusinessError } 202 - Caller is not a system application. 363 * @throws { BusinessError } 801 - Function is not supported in current device. 364 * @throws { BusinessError } 5400102 - Operate not permit in current state. 365 * @throws { BusinessError } 5400108 - Parameter out of range. 366 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 367 * @systemapi 368 * @since 20 369 */ 370 setHapticsIntensity(intensity: number): Promise<void>; 371 372 /** 373 * Check whether the device supports haptics intensity ramp effect. 374 * @returns { boolean } - {@code true} means supported. 375 * @throws { BusinessError } 202 - Caller is not a system application. 376 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 377 * @systemapi 378 * @since 20 379 */ 380 isHapticsRampSupported(): boolean; 381 382 /** 383 * Set haptics intensity ramp effect for this player. This method uses a promise to return the result. 384 * This function should be called before player start or after stop, and before release. 385 * @param { number } duration - ramp duration to set, unit is milliseconds. 386 * The value should be an integer, and not less than 100. 387 * @param { number } startIntensity - Starting intensity for Haptics ramp to set. 388 * The value ranges from 0.00 to 1.00. 1.00 indicates the maximum intensity (100%). 389 * @param { number } endIntensity - End intensity for haptics ramp to set. 390 * The value ranges from 0.00 to 1.00. 1.00 indicates the maximum intensity (100%). 391 * @returns { Promise<void> } Promise used to return the result. 392 * @throws { BusinessError } 202 - Caller is not a system application. 393 * @throws { BusinessError } 801 - Function is not supported in current device. 394 * @throws { BusinessError } 5400102 - Operate not permit in current state. 395 * @throws { BusinessError } 5400108 - Parameter out of range. 396 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 397 * @systemapi 398 * @since 20 399 */ 400 setHapticsRamp(duration: number, startIntensity: number, endIntensity: number): Promise<void>; 401 402 /** 403 * Set the playback to be looping. This method uses a promise to return the result. 404 * This function should be called before player release. 405 * @param { boolean } loop - Whether to loop or not, value true means loop. 406 * @returns { Promise<void> } Promise used to return the result. 407 * @throws { BusinessError } 5400102 - Operate not permit in current state. 408 * @syscap SystemCapability.Multimedia.AudioHaptic.Core 409 * @since 20 410 */ 411 setLoop(loop: boolean): Promise<void>; 412 } 413} 414export default audioHaptic; 415