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