1/* 2 * Copyright (c) 2021-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 MediaKit 19 */ 20 21import type { ErrorCallback, AsyncCallback, Callback } from '../@ohos.base'; 22import type audio from '../@ohos.multimedia.audio'; 23 24/** 25 * Interface for play parameters. 26 * @typedef PlayParameters 27 * @syscap SystemCapability.Multimedia.Media.SoundPool 28 * @since 10 29 */ 30export interface PlayParameters { 31 /** 32 * loop mode (0 = no loop, -1 = loop forever) 33 * 34 * @type { ?number } 35 * @syscap SystemCapability.Multimedia.Media.SoundPool 36 * @since 10 37 */ 38 loop?: number; 39 /** 40 * playback rate 41 * 42 * @type { ?number } 43 * @syscap SystemCapability.Multimedia.Media.SoundPool 44 * @since 10 45 */ 46 rate?: number; 47 /** 48 * left volume value(range = 0.0 to 1.0),current leftVolume = rightVolume 49 * 50 * @type { ?number } 51 * @syscap SystemCapability.Multimedia.Media.SoundPool 52 * @since 10 53 */ 54 leftVolume?: number; 55 /** 56 * right volume value(range = 0.0 to 1.0),current leftVolume = rightVolume 57 * 58 * @type { ?number } 59 * @syscap SystemCapability.Multimedia.Media.SoundPool 60 * @since 10 61 */ 62 rightVolume?: number; 63 /** 64 * stream priority (0 = lowest priority) 65 * 66 * @type { ?number } 67 * @syscap SystemCapability.Multimedia.Media.SoundPool 68 * @since 10 69 */ 70 priority?: number; 71 /** 72 * Flag indicating that the sound effect and audio can be played in parallel. 73 * 74 * @type { ?boolean } 75 * @syscap SystemCapability.Multimedia.Media.SoundPool 76 * @systemapi 77 * @since 10 78 */ 79 parallelPlayFlag?: boolean; 80} 81 82/** 83 * Interface for soundPool instance. Manages and plays sound. Before calling an SoundPool method, you must use createSoundPool() 84 * to create an SoundPool instance. 85 * @typedef SoundPool 86 * @syscap SystemCapability.Multimedia.Media.SoundPool 87 * @since 10 88 */ 89export interface SoundPool { 90 /** 91 * Load the sound from the specified path. 92 * 93 * @param {string} uri The path to the audio file 94 * @param {AsyncCallback<number>} callback Callback a sound ID. This value can be used to play or unload the sound. 95 * @throws { BusinessError } 5400102 - Operation not allowed. Return by callback. 96 * @throws { BusinessError } 5400103 - I/O error. Return by callback. 97 * @throws { BusinessError } 5400105 - Service died. Return by callback. 98 * @syscap SystemCapability.Multimedia.Media.SoundPool 99 * @since 10 100 */ 101 load(uri: string, callback: AsyncCallback<number>): void; 102 /** 103 * Load the sound from the specified path. 104 * 105 * @param {string} uri The path to the audio file 106 * @returns {Promise<number>} Promise a sound ID. This value can be used to play or unload the sound. 107 * @throws { BusinessError } 5400102 - Operation not allowed. Return by promise. 108 * @throws { BusinessError } 5400103 - I/O error. Return by promise. 109 * @throws { BusinessError } 5400105 - Service died. Return by promise. 110 * @syscap SystemCapability.Multimedia.Media.SoundPool 111 * @since 10 112 */ 113 load(uri: string): Promise<number>; 114 /** 115 * Load the sound from a FileDescriptor. 116 * 117 * @param {number} fd A FileDescriptor object 118 * @param {number} offset Offset to the start of the sound 119 * @param {number} length Length of the sound 120 * @param {AsyncCallback<number>} callback Callback a sound ID. This value can be used to play or unload the sound. 121 * @throws { BusinessError } 5400102 - Operation not allowed. Return by callback. 122 * @throws { BusinessError } 5400103 - I/O error. Return by callback. 123 * @throws { BusinessError } 5400105 - Service died. Return by callback. 124 * @syscap SystemCapability.Multimedia.Media.SoundPool 125 * @since 10 126 */ 127 load(fd: number, offset: number, length: number, callback: AsyncCallback<number>): void; 128 /** 129 * Load the sound from a FileDescriptor. 130 * 131 * @param {number} fd A FileDescriptor object 132 * @param {number} offset Offset to the start of the sound 133 * @param {number} length Length of the sound 134 * @returns {Promise<number>} Promise a sound ID. This value can be used to play or unload the sound. 135 * @throws { BusinessError } 5400102 - Operation not allowed. Return by promise. 136 * @throws { BusinessError } 5400103 - I/O error. Return by promise. 137 * @throws { BusinessError } 5400105 - Service died. Return by promise. 138 * @syscap SystemCapability.Multimedia.Media.SoundPool 139 * @since 10 140 */ 141 load(fd: number, offset: number, length: number): Promise<number>; 142 /** 143 * Play a sound from a sound ID. 144 * 145 * @param {number} soundID Returned by the load() 146 * @param {PlayParameters} params Player parameters 147 * @param {AsyncCallback<number>} callback Callback used to return a non-zero streamID if successful, zero if it fails. 148 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 149 * <br>2.Incorrect parameter types. 3.Parameter verification failed. Return by callback. 150 * @throws { BusinessError } 5400102 - Operation not allowed. Return by callback. 151 * @throws { BusinessError } 5400105 - Service died. Return by callback. 152 * @syscap SystemCapability.Multimedia.Media.SoundPool 153 * @since 10 154 */ 155 play(soundID: number, params: PlayParameters, callback: AsyncCallback<number>): void; 156 /** 157 * Play a sound from a sound ID. 158 * 159 * @param {number} soundID Returned by the load() 160 * @param {AsyncCallback<number>} callback Callback used to return a non-zero streamID if successful, zero if it fails. 161 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 162 * <br>2.Incorrect parameter types. 3.Parameter verification failed. Return by callback. 163 * @throws { BusinessError } 5400102 - Operation not allowed. Return by callback. 164 * @throws { BusinessError } 5400105 - Service died. Return by callback. 165 * @syscap SystemCapability.Multimedia.Media.SoundPool 166 * @since 10 167 */ 168 play(soundID: number, callback: AsyncCallback<number>): void; 169 /** 170 * Play a sound from a sound ID. 171 * 172 * @param {number} soundID Returned by the load() 173 * @param {PlayParameters} [params] Player parameters 174 * @returns {Promise<number>} Promise used to return a non-zero streamID if successful, zero if it fails. 175 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 176 * <br>2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. 177 * @throws { BusinessError } 5400102 - Operation not allowed. Return by promise. 178 * @throws { BusinessError } 5400105 - Service died. Return by promise. 179 * @syscap SystemCapability.Multimedia.Media.SoundPool 180 * @since 10 181 */ 182 play(soundID: number, params?: PlayParameters): Promise<number>; 183 /** 184 * Stop a stream which is playing. 185 * 186 * @param {number} streamID Returned by the play() 187 * @param {AsyncCallback<void>} callback Callback used to return the result. 188 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 189 * <br>2.Incorrect parameter types. 3.Parameter verification failed. Return by callback. 190 * @throws { BusinessError } 5400102 - Operation not allowed. Return by callback. 191 * @throws { BusinessError } 5400105 - Service died. Return by callback. 192 * @syscap SystemCapability.Multimedia.Media.SoundPool 193 * @since 10 194 */ 195 stop(streamID: number, callback: AsyncCallback<void>): void; 196 /** 197 * Stop a stream which is playing. 198 * 199 * @param {number} streamID Returned by the play() 200 * @returns {Promise<void>} Promise used to return the result. 201 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 202 * <br>2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. 203 * @throws { BusinessError } 5400102 - Operation not allowed. Return by promise. 204 * @throws { BusinessError } 5400105 - Service died. Return by promise. 205 * @syscap SystemCapability.Multimedia.Media.SoundPool 206 * @since 10 207 */ 208 stop(streamID: number): Promise<void>; 209 /** 210 * Set loop mode. 211 * 212 * @param {number} streamID Returned by the play() 213 * @param {number} loop Loop mode (0 = no loop, -1 = loop forever) 214 * @param {AsyncCallback<void>} callback Callback used to return the result. 215 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 216 * <br>2.Incorrect parameter types. 3.Parameter verification failed. Return by callback. 217 * @throws { BusinessError } 5400102 - Operation not allowed. Return by callback. 218 * @throws { BusinessError } 5400105 - Service died. Return by callback. 219 * @syscap SystemCapability.Multimedia.Media.SoundPool 220 * @since 10 221 */ 222 setLoop(streamID: number, loop: number, callback: AsyncCallback<void>): void; 223 /** 224 * Set loop mode. 225 * 226 * @param {number} streamID Returned by the play() 227 * @param {number} loop Loop mode (0 = no loop, -1 = loop forever) 228 * @returns {Promise<void>} Promise used to return the result. 229 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 230 * <br>2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. 231 * @throws { BusinessError } 5400102 - Operation not allowed. Return by promise. 232 * @throws { BusinessError } 5400105 - Service died. Return by promise. 233 * @syscap SystemCapability.Multimedia.Media.SoundPool 234 * @since 10 235 */ 236 setLoop(streamID: number, loop: number): Promise<void>; 237 /** 238 * Set stream priority. 239 * 240 * @param {number} streamID Returned by the play() 241 * @param {number} priority Stream priority (0 = lowest priority) 242 * @param {AsyncCallback<void>} callback Callback used to return the result. 243 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 244 * <br>2.Incorrect parameter types. 3.Parameter verification failed. Return by callback. 245 * @throws { BusinessError } 5400102 - Operation not allowed. Return by callback. 246 * @throws { BusinessError } 5400105 - Service died. Return by callback. 247 * @syscap SystemCapability.Multimedia.Media.SoundPool 248 * @since 10 249 */ 250 setPriority(streamID: number, priority: number, callback: AsyncCallback<void>): void; 251 /** 252 * Set stream priority. 253 * 254 * @param {number} streamID Returned by the play() 255 * @param {number} priority Stream priority (0 = lowest priority) 256 * @returns {Promise<void>} Promise used to return the result. 257 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 258 * <br>2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. 259 * @throws { BusinessError } 5400102 - Operation not allowed. Return by promise. 260 * @throws { BusinessError } 5400105 - Service died. Return by promise. 261 * @syscap SystemCapability.Multimedia.Media.SoundPool 262 * @since 10 263 */ 264 setPriority(streamID: number, priority: number): Promise<void>; 265 /** 266 * Set playback rate. 267 * 268 * @param {number} streamID Returned by the play() 269 * @param {audio.AudioRendererRate} rate Playback rate 270 * @param {AsyncCallback<void>} callback Callback used to return the result. 271 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 272 * <br>2.Incorrect parameter types. 3.Parameter verification failed. Return by callback. 273 * @throws { BusinessError } 5400102 - Operation not allowed. Return by callback. 274 * @throws { BusinessError } 5400105 - Service died. Return by callback. 275 * @syscap SystemCapability.Multimedia.Media.SoundPool 276 * @since 10 277 */ 278 setRate(streamID: number, rate: audio.AudioRendererRate, callback: AsyncCallback<void>): void; 279 /** 280 * Set playback rate. 281 * 282 * @param {number} streamID Returned by the play() 283 * @param {audio.AudioRendererRate} rate Playback rate 284 * @returns {Promise<void>} Promise used to return the result. 285 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 286 * <br>2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. 287 * @throws { BusinessError } 5400102 - Operation not allowed. Return by promise. 288 * @throws { BusinessError } 5400105 - Service died. Return by promise. 289 * @syscap SystemCapability.Multimedia.Media.SoundPool 290 * @since 10 291 */ 292 setRate(streamID: number, rate: audio.AudioRendererRate): Promise<void>; 293 /** 294 * Set stream volume. 295 * 296 * @param {number} streamID Returned by the play() 297 * @param {number} leftVolume Volume value(range = 0.0 to 1.0),current leftVolume = rightVolume 298 * @param {number} rightVolume Volume value(range = 0.0 to 1.0),current leftVolume = rightVolume 299 * @param {AsyncCallback<void>} callback Callback used to return the result. 300 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 301 * <br>2.Incorrect parameter types. 3.Parameter verification failed. Return by callback. 302 * @throws { BusinessError } 5400102 - Operation not allowed. Return by callback. 303 * @throws { BusinessError } 5400105 - Service died. Return by callback. 304 * @syscap SystemCapability.Multimedia.Media.SoundPool 305 * @since 10 306 */ 307 setVolume(streamID: number, leftVolume: number, rightVolume: number, callback: AsyncCallback<void>): void; 308 /** 309 * Set stream volume. 310 * 311 * @param {number} streamID Returned by the play() 312 * @param {number} leftVolume Volume value(range = 0.0 to 1.0),current leftVolume = rightVolume 313 * @param {number} rightVolume Volume value(range = 0.0 to 1.0),current leftVolume = rightVolume 314 * @returns {Promise<void>} Promise used to return the result. 315 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 316 * <br>2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. 317 * @throws { BusinessError } 5400102 - Operation not allowed. Return by promise. 318 * @throws { BusinessError } 5400105 - Service died. Return by promise. 319 * @syscap SystemCapability.Multimedia.Media.SoundPool 320 * @since 10 321 */ 322 setVolume(streamID: number, leftVolume: number, rightVolume: number): Promise<void>; 323 /** 324 * Unload a sound from a sound ID. 325 * 326 * @param {number} soundID Returned by the load() 327 * @param {AsyncCallback<void>} callback Callback used to return the result. 328 * @throws { BusinessError } 5400102 - Operation not allowed. Return by callback. 329 * @throws { BusinessError } 5400103 - I/O error. Return by callback. 330 * @throws { BusinessError } 5400105 - Service died. Return by callback. 331 * @syscap SystemCapability.Multimedia.Media.SoundPool 332 * @since 10 333 */ 334 unload(soundID: number, callback: AsyncCallback<void>): void; 335 /** 336 * Unload a sound from a sound ID. 337 * 338 * @param {number} soundID Returned by the load() 339 * @returns {Promise<void>} Promise used to return the result. 340 * @throws { BusinessError } 5400102 - Operation not allowed. Return by promise. 341 * @throws { BusinessError } 5400103 - I/O error. Return by promise. 342 * @throws { BusinessError } 5400105 - Service died. Return by promise. 343 * @syscap SystemCapability.Multimedia.Media.SoundPool 344 * @since 10 345 */ 346 unload(soundID: number): Promise<void>; 347 /** 348 * Releases the soundPool. This method uses an asynchronous callback to return the result. 349 * 350 * @param {AsyncCallback<void>} callback Callback used to return the result. 351 * @throws { BusinessError } 5400105 - Service died. Return by callback. 352 * @syscap SystemCapability.Multimedia.Media.SoundPool 353 * @since 10 354 */ 355 release(callback: AsyncCallback<void>): void; 356 /** 357 * Releases the soundPool. This method uses a promise to return the result. 358 * 359 * @returns {Promise<void>} Promise used to return the result. 360 * @throws { BusinessError } 5400105 - Service died. Return by promise. 361 * @syscap SystemCapability.Multimedia.Media.SoundPool 362 * @since 10 363 */ 364 release(): Promise<void>; 365 /** 366 * Register listens for load result event. 367 * 368 * @param {'loadComplete'} type Type of the play finish event to listen for. 369 * @param {Callback<number>} callback Callback used to listen for load result event 370 * @syscap SystemCapability.Multimedia.Media.SoundPool 371 * @since 10 372 */ 373 on(type: 'loadComplete', callback: Callback<number>): void; 374 /** 375 * Cancel Listens for load result event. 376 * 377 * @param {'loadComplete'} type Type of the play finish event to listen for. 378 * @syscap SystemCapability.Multimedia.Media.SoundPool 379 * @since 10 380 */ 381 off(type: 'loadComplete'): void; 382 /** 383 * Register listens for play finish event. 384 * 385 * @param {'playFinished'} type Type of the play finish event to listen for. 386 * @param {Callback<void>} callback Callback used to listen for the play finish 387 * @syscap SystemCapability.Multimedia.Media.SoundPool 388 * @since 10 389 */ 390 on(type: 'playFinished', callback: Callback<void>): void; 391 /** 392 * Cancel Listens for play finish event. 393 * 394 * @param {'playFinished'} type of the play finish event to listen for. 395 * @syscap SystemCapability.Multimedia.Media.SoundPool 396 * @since 10 397 */ 398 off(type: 'playFinished'): void; 399 /** 400 * Register listens for sound play error events. 401 * 402 * @param {'error'} type Type of the sound play error event to listen for. 403 * @param {ErrorCallback} callback Callback used to listen for sound play error events. 404 * @syscap SystemCapability.Multimedia.Media.SoundPool 405 * @since 10 406 */ 407 on(type: 'error', callback: ErrorCallback): void; 408 /** 409 * Cancel Listens for sound play error events. 410 * 411 * @param {'error'} type Type of the sound play error event to listen for. 412 * @syscap SystemCapability.Multimedia.Media.SoundPool 413 * @since 10 414 */ 415 off(type: 'error'): void; 416} 417 418