1# SoundPool (音频池) 2 3音频池提供了短音频的加载、播放、音量设置、循环设置、停止播放、资源卸载等功能。 4 5SoundPool需要和@ohos.multimedia.media配合使用，需要先通过[media.createSoundPool](js-apis-media.md#mediacreatesoundpool10)完成音频池实例的创建。 6 7> **说明：** 8> 9> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 10 11## 导入模块 12 13```js 14import { media } from '@kit.MediaKit'; 15import { audio } from '@kit.AudioKit'; 16``` 17 18## PlayParameters 19 20表示音频池播放参数设置。 21 22通过设置播放相关参数，来控制播放的音量，循环次数，播放优先级等参数。 23 24**系统能力：** SystemCapability.Multimedia.Media.SoundPool 25 26| 名称 | 类型 | 必填 | 说明 | 27| --------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 28| loop | number | 否 | 设置循环次数。<br>当loop≥0时，实际播放次数为loop+1。<br> 当loop＜0时，表示一直循环。<br>默认值：0，表示仅播放一次。 | 29| rate | number | 否 | 设置音频播放的倍速，具体倍速范围参照[AudioRendererRate](../apis-audio-kit/js-apis-audio.md#audiorendererrate8)。默认值：0。 | 30| leftVolume | number | 否 | 设置左声道音量，设置范围（0.0~1.0）。默认值：1.0。 | 31| rightVolume | number | 否 | 设置右声道音量，设置范围（0.0~1.0）。（当前不支持左右分别设置，将以左声道音量为准）。默认值：1.0。 | 32| priority | number | 否 | 音频流播放的优先级，0为最低优先级，数值越大优先级越高，通过相互比较大小确定播放优先级，设置范围为大于等于0的整数。默认值：0。 | 33 34## SoundPool 35 36音频池提供了系统声音的加载、播放、音量设置、循环设置、停止播放、资源卸载等功能, 在调用SoundPool的接口前，需要先通过[createSoundPool](js-apis-media.md#mediacreatesoundpool10)创建实例。 37 38> **说明：** 39> 40> 在使用SoundPool实例的方法时，建议开发者注册相关回调，主动获取当前状态变化。 41> - [on('loadComplete')](#onloadcomplete)：监听资源加载完成。 42> - [on('playFinishedWithStreamId')](#onplayfinishedwithstreamid18)：监听播放完成，同时返回播放结束的音频的streamId。 43> - [on('playFinished')](#onplayfinished)：监听播放完成。 44> - [on('error')](#onerror)：监听错误事件。 45 46### load 47 48load(uri: string, callback: AsyncCallback\<number>): void 49 50加载音频资源。使用callback方式异步获取资源ID，入参uri通过获取文件fd生成以"fd://"开头的文件描述字符串。 51该方法不支持加载rawfile目录资源，需要通过[load(fd: number, offset: number, length: number, callback: AsyncCallback\<number>): void](#load-2)或者[load(fd: number, offset: number, length: number): Promise\<number>](#load-3)实现。 52 53>**说明：** 54> 55>将资源句柄（fd）或加载路径描述（uri）传递给音频池播放器之后，请不要通过该资源句柄或加载路径描述做其他读写操作，包括但不限于将同一个资源句柄或加载路径描述传递给多个音频池播放器。 56>同一时间通过同一个资源句柄或加载路径描述读写文件时存在竞争关系，将导致播放异常。 57 58**系统能力：** SystemCapability.Multimedia.Media.SoundPool 59 60**参数：** 61 62| 参数名 | 类型 | 必填 | 说明 | 63| -------- | -------------------------------------- | ---- | ------------------------------------- | 64| uri | string | 是 | 音频文件的加载路径描述，一般以"fd://"开头的文件描述。 | 65| callback | AsyncCallback\<number> | 是 | 异步音频资源加载返回的资源id，有效值大于0。 | 66 67**错误码：** 68 69以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 70 71| 错误码ID | 错误信息 | 72| -------- | --------------------------------------- | 73| 5400102 | Operation not allowed. Return by callback.| 74| 5400103 | I/O error. Return by callback. | 75| 5400105 | Service died. Return by callback. | 76 77**示例：** 78 79```ts 80import { fileIo } from '@kit.CoreFileKit'; 81import { BusinessError } from '@kit.BasicServicesKit'; 82 83//创建soundPool实例。 84let soundPool: media.SoundPool; 85let audioRendererInfo: audio.AudioRendererInfo = { 86 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 87 rendererFlags: 1 88} 89media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 90 if (error) { 91 console.error(`Failed to createSoundPool`) 92 return; 93 } else { 94 soundPool = soundPool_; 95 console.info(`Succeeded in createSoundPool`) 96 let uri:string = ""; 97 let file: fileIo.File; 98 //获取fd的uri路径。 99 fileIo.open('/test_01.mp3', fileIo.OpenMode.READ_ONLY).then((file_: fileIo.File) => { 100 file = file_; 101 console.info("file fd: " + file.fd); 102 uri = 'fd://' + (file.fd).toString() 103 soundPool.load(uri, (error: BusinessError, soundId_: number) => { 104 if (error) { 105 console.error(`Failed to load soundPool: errCode is ${error.code}, errMessage is ${error.message}`) 106 } else { 107 console.info(`Succeeded in loading soundPool` + JSON.stringify(soundId_)) 108 } 109 }); 110 }); // '/test_01.mp3' 作为样例，使用时需要传入文件对应路径。 111 } 112}); 113``` 114 115### load 116 117load(uri: string): Promise\<number> 118 119加载音频资源。使用Promise方式异步获取资源ID，入参uri通过获取文件fd生成以"fd://"开头的文件描述字符串。 120该方法不支持加载rawfile目录资源，需要通过[load(fd: number, offset: number, length: number, callback: AsyncCallback\<number>): void](#load-2)或者[load(fd: number, offset: number, length: number): Promise\<number>](#load-3)实现。 121 122>**说明：** 123> 124>将资源句柄（fd）或加载路径描述（uri）传递给音频池播放器之后，请不要通过该资源句柄或加载路径描述做其他读写操作，包括但不限于将同一个资源句柄或加载路径描述传递给多个音频池播放器。 125>同一时间通过同一个资源句柄或加载路径描述读写文件时存在竞争关系，将导致播放异常。 126 127**系统能力：** SystemCapability.Multimedia.Media.SoundPool 128 129**参数：** 130 131| 参数名 | 类型 | 必填 | 说明 | 132| ------ | -------------------------------------- | ---- | -------------------------- | 133| uri | string | 是 | 音频文件的加载路径描述，一般以"fd://"开头的文件描述。 | 134 135**返回值：** 136 137| 类型 | 说明 | 138| -------------- | ------------------------------------------ | 139| Promise\<number> | 以Promise方式异步加载音频池资源，返回资源的id，有效值大于0。 | 140 141**错误码：** 142 143以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 144 145| 错误码ID | 错误信息 | 146| -------- | --------------------------------------- | 147| 5400102 | Operation not allowed. Return by promise.| 148| 5400103 | I/O error. Return by promise. | 149| 5400105 | Service died. Return by promise. | 150 151**示例：** 152 153```ts 154import { fileIo } from '@kit.CoreFileKit'; 155import { BusinessError } from '@kit.BasicServicesKit'; 156 157//创建soundPool实例。 158let soundPool: media.SoundPool; 159let audioRendererInfo: audio.AudioRendererInfo = { 160 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 161 rendererFlags: 1 162} 163media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 164 if (error) { 165 console.error(`Failed to createSoundPool`) 166 return; 167 } else { 168 soundPool = soundPool_; 169 console.info(`Succeeded in createSoundPool`) 170 let uri:string = ""; 171 let soundID: number = 0; 172 let file: fileIo.File; 173 //获取fd的uri路径。 174 fileIo.open('/test_01.mp3', fileIo.OpenMode.READ_ONLY).then((file_: fileIo.File) => { 175 file = file_; 176 console.info("file fd: " + file.fd); 177 uri = 'fd://' + (file.fd).toString() 178 soundPool.load(uri).then((soundId: number) => { 179 console.info('Succeeded in loading uri'); 180 soundID = soundId; 181 }, (err: BusinessError) => { 182 console.error('Failed to load soundPool and catch error is ' + err.message); 183 }); 184 }); // '/test_01.mp3' 作为样例，使用时需要传入文件对应路径。 185 } 186}); 187 188``` 189 190### load 191 192load(fd: number, offset: number, length: number, callback: AsyncCallback\<number>): void 193 194加载音频资源。使用callback方式异步获取资源ID，入参可手动传入资源信息或通过读取应用内置资源自动获取。 195 196>**说明：** 197> 198>将资源句柄（fd）或加载路径描述（uri）传递给音频池播放器之后，请不要通过该资源句柄或加载路径描述做其他读写操作，包括但不限于将同一个资源句柄或加载路径描述传递给多个音频池播放器。 199>同一时间通过同一个资源句柄或加载路径描述读写文件时存在竞争关系，将导致播放异常。 200 201**系统能力：** SystemCapability.Multimedia.Media.SoundPool 202 203**参数：** 204 205| 参数名 | 类型 | 必填 | 说明 | 206| -------- | ---------------------- | ---- | --------------------------- | 207| fd | number | 是 | 资源句柄，通过[resourceManager.getRawFd](../apis-localization-kit/js-apis-resource-manager.md#getrawfd9)获取。 | 208| offset | number | 是 | 资源偏移量，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 209| length | number | 是 | 资源长度，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 210| callback | AsyncCallback\<number> | 是 | 获取回调的soundID，有效值大于0。 | 211 212**错误码：** 213 214以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 215 216| 错误码ID | 错误信息 | 217| -------- | --------------------------------------- | 218| 5400102 | Operation not allowed. Return by callback. | 219| 5400103 | I/O error. Return by callback. | 220| 5400105 | Service died. Return by callback. | 221 222**示例1：** 223 224```ts 225import { fileIo } from '@kit.CoreFileKit'; 226import { BusinessError } from '@kit.BasicServicesKit'; 227 228//创建soundPool实例。 229let soundPool: media.SoundPool; 230let audioRendererInfo: audio.AudioRendererInfo = { 231 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 232 rendererFlags: 1 233} 234media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 235 if (error) { 236 console.error(`Failed to createSoundPool`) 237 return; 238 } else { 239 soundPool = soundPool_; 240 console.info(`Succeeded in createSoundPool`) 241 let file: fileIo.File; 242 let soundID: number = 0; 243 let fileSize: number = 1; //通过fileIo.stat()获取size值。 244 let uri: string = ""; 245 //获取fd的描述信息，test_01.mp3不是rawfile目录资源下面的音频。 246 fileIo.open('/test_01.mp3', fileIo.OpenMode.READ_ONLY).then((file_: fileIo.File) => { 247 file = file_; 248 console.info("file fd: " + file.fd); 249 uri = 'fd://' + (file.fd).toString() 250 soundPool.load(file.fd, 0, fileSize, (error: BusinessError, soundId_: number) => { 251 if (error) { 252 console.error(`Failed to load soundPool: errCode is ${error.code}, errMessage is ${error.message}`) 253 } else { 254 soundID = soundId_; 255 console.info('Succeeded in loading soundId:' + soundId_); 256 } 257 }); 258 }); // '/test_01.mp3' 作为样例，使用时需要传入文件对应路径。 259 } 260}); 261 262``` 263 264**示例2：** 265 266```ts 267import { media } from '@kit.MediaKit'; 268import { audio } from '@kit.AudioKit'; 269import { BusinessError } from '@kit.BasicServicesKit'; 270 271function create(context: Context) { 272 //创建soundPool实例。 273 let soundPool: media.SoundPool; 274 let audioRendererInfo: audio.AudioRendererInfo = { 275 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 276 rendererFlags: 1 277 } 278 let soundID: number = 0; 279 media.createSoundPool(5, audioRendererInfo, async (error: BusinessError, soundPool_: media.SoundPool) => { 280 if (error) { 281 console.error(`Failed to createSoundPool`) 282 return; 283 } else { 284 soundPool = soundPool_; 285 console.info(`Succeeded in createSoundPool`) 286 //test_01.mp3为rawfile目录资源下面的音频。 287 let fileDescriptor = await context.resourceManager.getRawFd('test_01.mp3'); 288 soundPool.load(fileDescriptor.fd, fileDescriptor.offset, fileDescriptor.length, (error: BusinessError, soundId_: number) => { 289 if (error) { 290 console.error(`Failed to load soundPool: errCode is ${error.code}, errMessage is ${error.message}`) 291 } else { 292 soundID = soundId_; 293 console.info('Succeeded in loading soundId:' + soundId_); 294 } 295 }); 296 } 297 }); 298} 299 300``` 301 302### load 303 304load(fd: number, offset: number, length: number): Promise\<number> 305 306加载音频资源。使用Promise方式异步获取资源ID，入参可手动传入资源信息或通过读取应用内置资源自动获取。 307 308>**说明：** 309> 310>将资源句柄（fd）或加载路径描述（uri）传递给音频池播放器之后，请不要通过该资源句柄或加载路径描述做其他读写操作，包括但不限于将同一个资源句柄或加载路径描述传递给多个音频池播放器。 311>同一时间通过同一个资源句柄或加载路径描述读写文件时存在竞争关系，将导致播放异常。 312 313**系统能力：** SystemCapability.Multimedia.Media.SoundPool 314 315**参数：** 316 317| 参数名 | 类型 | 必填 | 说明 | 318| -------- | ---------------------- | ---- | --------------------------- | 319| fd | number | 是 | 资源句柄，通过过[resourceManager.getRawFd](../apis-localization-kit/js-apis-resource-manager.md#getrawfd9)获取。 | 320| offset | number | 是 | 资源偏移量，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 321| length | number | 是 | 资源长度，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 322 323**返回值：** 324 325| 类型 | 说明 | 326| ---------------- | -------------------------------- | 327| Promise\<number> | 以Promise方式获取返回的soundID，有效值大于0。 | 328 329**错误码：** 330 331以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 332 333| 错误码ID | 错误信息 | 334| -------- | --------------------------------------- | 335| 5400102 | Operation not allowed. Return by promise.| 336| 5400103 | I/O error. Return by promise. | 337| 5400105 | Service died. Return by promise. | 338 339**示例1：** 340 341```ts 342import { fileIo } from '@kit.CoreFileKit'; 343import { BusinessError } from '@kit.BasicServicesKit'; 344 345//创建soundPool实例。 346let soundPool: media.SoundPool; 347let audioRendererInfo: audio.AudioRendererInfo = { 348 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 349 rendererFlags: 1 350} 351media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 352 if (error) { 353 console.error(`Failed to createSoundPool`) 354 return; 355 } else { 356 soundPool = soundPool_; 357 console.info(`Succeeded in createSoundPool`) 358 let file: fileIo.File; 359 let soundID: number = 0; 360 let fileSize: number = 1; //通过fileIo.stat()获取size值。 361 let uri: string = ""; 362 //获取fd的描述信息，test_01.mp3不是rawfile目录资源下面的音频。 363 fileIo.open('/test_01.mp3', fileIo.OpenMode.READ_ONLY).then((file_: fileIo.File) => { 364 file = file_; 365 console.info("file fd: " + file.fd); 366 uri = 'fd://' + (file.fd).toString() 367 soundPool.load(file.fd, 0, fileSize).then((soundId: number) => { 368 console.info('Succeeded in loading soundpool'); 369 soundID = soundId; 370 }, (err: BusinessError) => { 371 console.error('Failed to load soundpool and catch error is ' + err.message); 372 }); 373 }); 374 } 375}); 376 377``` 378 379**示例2：** 380 381```ts 382import { media } from '@kit.MediaKit'; 383import { audio } from '@kit.AudioKit'; 384import { BusinessError } from '@kit.BasicServicesKit'; 385 386function create(context: Context) { 387 //创建soundPool实例。 388 let soundPool: media.SoundPool; 389 let audioRendererInfo: audio.AudioRendererInfo = { 390 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 391 rendererFlags: 1 392 } 393 let soundID: number = 0; 394 media.createSoundPool(5, audioRendererInfo, async (error: BusinessError, soundPool_: media.SoundPool) => { 395 if (error) { 396 console.error(`Failed to createSoundPool`) 397 return; 398 } else { 399 soundPool = soundPool_; 400 console.info(`Succeeded in createSoundPool`) 401 //test_01.mp3为rawfile目录资源下面的音频。 402 let fileDescriptor = await context.resourceManager.getRawFd('test_01.mp3'); 403 soundPool.load(fileDescriptor.fd, fileDescriptor.offset, fileDescriptor.length).then((soundId: number) => { 404 console.info('Succeeded in loading soundpool'); 405 soundID = soundId; 406 }, (err: BusinessError) => { 407 console.error('Failed to load soundpool and catch error is ' + err.message); 408 }); 409 } 410 }); 411} 412 413``` 414 415### play 416 417play(soundID: number, params: PlayParameters, callback: AsyncCallback\<number>): void 418 419播放音频资源。使用callback方式异步获取音频流streamID。 420 421**系统能力：** SystemCapability.Multimedia.Media.SoundPool 422 423**参数：** 424 425| 参数名 | 类型 | 必填 | 说明 | 426| -------- | ---------------------- | ---- | --------------------------- | 427| soundID | number | 是 | 资源ID，通过load方法获取。 | 428| params | [PlayParameters](#playparameters) | 是 | play播放相关参数的设置。 | 429| callback | AsyncCallback\<number> | 是 | 获取回调的音频流ID，有效值大于0。 | 430 431**错误码：** 432 433以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 434 435| 错误码ID | 错误信息 | 436| -------- | --------------------------------------- | 437| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by callback. | 438| 5400102 | Operation not allowed. Return by callback. | 439| 5400105 | Service died. Return by callback. | 440 441**示例：** 442 443```js 444import { BusinessError } from '@kit.BasicServicesKit'; 445 446//创建soundPool实例。 447let soundPool: media.SoundPool; 448let audioRendererInfo: audio.AudioRendererInfo = { 449 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 450 rendererFlags: 1 451} 452media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 453 if (error) { 454 console.error(`Failed to createSoundPool`) 455 return; 456 } else { 457 soundPool = soundPool_; 458 console.info(`Succeeded in createSoundPool`) 459 let soundID: number = 0; 460 let streamID: number = 0; 461 let playParameters: media.PlayParameters = { 462 loop: 3, // 循环3次。 463 rate: audio.AudioRendererRate.RENDER_RATE_NORMAL, // 正常倍速。 464 leftVolume: 0.5, // range = 0.0-1.0 465 rightVolume: 0.5, // range = 0.0-1.0 466 priority: 0, // 最低优先级。 467 } 468 soundPool.play(soundID, playParameters, (error: BusinessError, streamId: number) => { 469 if (error) { 470 console.error(`Failed to play soundpool: errCode is ${error.code}, errMessage is ${error.message}`) 471 } else { 472 streamID = streamId; 473 console.info('Succeeded in playing soundpool, streamId:' + streamId); 474 } 475 }); 476 } 477}); 478 479``` 480 481### play 482 483play(soundID: number, callback: AsyncCallback\<number>): void 484 485播放音频资源。使用callback方式异步获取音频流streamID。 486 487**系统能力：** SystemCapability.Multimedia.Media.SoundPool 488 489**参数：** 490 491| 参数名 | 类型 | 必填 | 说明 | 492| -------- | ---------------------- | ---- | --------------------------- | 493| soundID | number | 是 | 资源ID，通过load方法获取。 | 494| callback | AsyncCallback\<number> | 是 | 获取回调的音频流ID，有效值大于0。 | 495 496**错误码：** 497 498以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 499 500| 错误码ID | 错误信息 | 501| -------- | --------------------------------------- | 502| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by callback. | 503| 5400102 | Operation not allowed. Return by callback. | 504| 5400105 | Service died. Return by callback. | 505 506**示例：** 507 508```js 509import { BusinessError } from '@kit.BasicServicesKit'; 510 511//创建soundPool实例。 512let soundPool: media.SoundPool; 513let audioRendererInfo: audio.AudioRendererInfo = { 514 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 515 rendererFlags: 1 516} 517media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 518 if (error) { 519 console.error(`Failed to createSoundPool`) 520 return; 521 } else { 522 soundPool = soundPool_; 523 console.info(`Succeeded in createSoundPool`) 524 let soundID: number = 0; 525 let streamID: number = 0; 526 soundPool.play(soundID, (error: BusinessError, streamId: number) => { 527 if (error) { 528 console.error(`Failed to play soundpool: errCode is ${error.code}, errMessage is ${error.message}`) 529 } else { 530 streamID = streamId; 531 console.info('Succeeded in playing soundpool, streamId:' + streamId); 532 } 533 }); 534 } 535}); 536 537``` 538 539### play 540 541play(soundID: number, params?: PlayParameters): Promise\<number> 542 543播放音频资源。使用Promise方式异步获取音频流streamID。 544 545**系统能力：** SystemCapability.Multimedia.Media.SoundPool 546 547**参数：** 548 549| 参数名 | 类型 | 必填 | 说明 | 550| -------- | ---------------------- | ---- | --------------------------- | 551| soundID | number | 是 | 资源ID，通过load方法获取。 | 552| params | [PlayParameters](#playparameters) | 否 | play播放相关参数的设置。 | 553 554**返回值：** 555 556| 类型 | 说明 | 557| ---------------- | -------------------------------- | 558| Promise\<number> | 以Promise方式获取返回的音频流ID，有效值大于0。 | 559 560**错误码：** 561 562以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 563 564| 错误码ID | 错误信息 | 565| -------- | --------------------------------------- | 566| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. | 567| 5400102 | Operation not allowed. Return by promise. | 568| 5400105 | Service died. Return by promise. | 569 570**示例：** 571 572```js 573import { BusinessError } from '@kit.BasicServicesKit'; 574 575//创建soundPool实例。 576let soundPool: media.SoundPool; 577let audioRendererInfo: audio.AudioRendererInfo = { 578 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 579 rendererFlags: 1 580} 581media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 582 if (error) { 583 console.error(`Failed to createSoundPool`) 584 return; 585 } else { 586 soundPool = soundPool_; 587 console.info(`Succeeded in createSoundPool`) 588 let soundID: number = 0; 589 let streamID: number = 0; 590 let playParameters: media.PlayParameters = { 591 loop: 3, // 循环4次。 592 rate: audio.AudioRendererRate.RENDER_RATE_NORMAL, // 正常倍速。 593 leftVolume: 0.5, // range = 0.0-1.0。 594 rightVolume: 0.5, // range = 0.0-1.0。 595 priority: 0, // 最低优先级。 596 } 597 598 soundPool.play(soundID, playParameters).then((streamId: number) => { 599 console.info('Succeeded in playing soundpool'); 600 streamID = streamId; 601 },(err: BusinessError) => { 602 console.error('Failed to play soundpool and catch error is ' + err.message); 603 }); 604 } 605}); 606 607``` 608 609### stop 610 611stop(streamID: number, callback: AsyncCallback\<void>): void 612 613停止播放音频资源。使用callback方式异步获取返回值。 614 615**系统能力：** SystemCapability.Multimedia.Media.SoundPool 616 617**参数：** 618 619| 参数名 | 类型 | 必填 | 说明 | 620| -------- | ---------------------- | ---- | --------------------------- | 621| streamID | number | 是 | 音频流ID，通过play方法获取。 | 622| callback | AsyncCallback\<void> | 是 | 异步音频池stop的回调方法。 | 623 624**错误码：** 625 626以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 627 628| 错误码ID | 错误信息 | 629| -------- | --------------------------------------- | 630| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by callback. | 631| 5400102 | Operation not allowed. Return by callback. | 632| 5400105 | Service died. Return by callback. | 633 634**示例：** 635 636```js 637import { BusinessError } from '@kit.BasicServicesKit'; 638 639//创建soundPool实例。 640let soundPool: media.SoundPool; 641let audioRendererInfo: audio.AudioRendererInfo = { 642 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 643 rendererFlags: 1 644} 645media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 646 if (error) { 647 console.error(`Failed to createSoundPool`) 648 return; 649 } else { 650 soundPool = soundPool_; 651 console.info(`Succeeded in createSoundPool`) 652 let streamID: number = 0; 653 //先调用play方法给拿到对应的streamID。 654 soundPool.stop(streamID, (error: BusinessError) => { 655 if (error) { 656 console.error(`Failed to stop soundpool: errCode is ${error.code}, errMessage is ${error.message}`) 657 } else { 658 console.info('Succeeded in stopping soundpool'); 659 } 660 }) 661 } 662}); 663 664``` 665 666### stop 667 668stop(streamID: number): Promise\<void> 669 670停止streamID对应的音频播放。使用Promise方式异步获取返回值。 671 672**系统能力：** SystemCapability.Multimedia.Media.SoundPool 673 674**参数：** 675 676| 参数名 | 类型 | 必填 | 说明 | 677| -------- | ---------------------- | ---- | --------------------------- | 678| streamID | number | 是 | 音频流ID，通过play方法获取。 | 679 680**返回值：** 681 682| 类型 | 说明 | 683| ---------------- | -------------------------------- | 684| Promise\<void> | 以Promise方式返回，无返回值。 | 685 686**错误码：** 687 688以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 689 690| 错误码ID | 错误信息 | 691| -------- | --------------------------------------- | 692| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. | 693| 5400102 | Operation not allowed. Return by promise. | 694| 5400105 | Service died. Return by promise. | 695 696**示例：** 697 698```js 699import { BusinessError } from '@kit.BasicServicesKit'; 700 701//创建soundPool实例。 702let soundPool: media.SoundPool; 703let audioRendererInfo: audio.AudioRendererInfo = { 704 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 705 rendererFlags: 1 706} 707media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 708 if (error) { 709 console.error(`Failed to createSoundPool`) 710 return; 711 } else { 712 soundPool = soundPool_; 713 console.info(`Succeeded in createSoundPool`) 714 let streamID: number = 0; 715 //先调用play方法给拿到对应的streamID。 716 soundPool.stop(streamID).then(() => { 717 console.info('Succeeded in stopping soundpool'); 718 }, (err: BusinessError) => { 719 console.error('Failed to stop soundpool and catch error is ' + err.message); 720 }); 721 } 722}); 723``` 724 725### setLoop 726 727setLoop(streamID: number, loop: number, callback: AsyncCallback\<void>): void; 728 729设置循环模式。使用callback方式异步获取返回值。 730 731**系统能力：** SystemCapability.Multimedia.Media.SoundPool 732 733**参数：** 734 735| 参数名 | 类型 | 必填 | 说明 | 736| -------- | ---------------------- | ---- | --------------------------- | 737| streamID | number | 是 | 音频流ID，通过play方法获取。 | 738| loop | number | 是 | 设置循环次数。<br>当loop≥0时，实际播放次数为loop+1。<br> 当loop＜0时，表示一直循环。 | 739| callback | AsyncCallback\<void> | 是 | 异步setLoop的回调方法。 | 740 741**错误码：** 742 743以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 744 745| 错误码ID | 错误信息 | 746| -------- | --------------------------------------- | 747| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by callback. | 748| 5400102 | Operation not allowed. Return by callback. | 749| 5400105 | Service died. Return by callback. | 750 751**示例：** 752 753```js 754import { BusinessError } from '@kit.BasicServicesKit'; 755 756//创建soundPool实例。 757let soundPool: media.SoundPool; 758let audioRendererInfo: audio.AudioRendererInfo = { 759 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 760 rendererFlags: 1 761} 762media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 763 if (error) { 764 console.error(`Failed to createSoundPool`) 765 return; 766 } else { 767 soundPool = soundPool_; 768 console.info(`Succeeded in createSoundPool`) 769 let streamID: number = 0; 770 //先通过调用play方法获取到对应的streamID。 771 //设置循环2次。 772 soundPool.setLoop(streamID, 2, (error: BusinessError) => { 773 if (error) { 774 console.error(`Failed to setLoop soundPool: errCode is ${error.code}, errMessage is ${error.message}`) 775 } else { 776 console.info('Succeeded in setLoopping soundpool, streamID:' + streamID); 777 } 778 }); 779 } 780}); 781 782``` 783 784### setLoop 785 786setLoop(streamID: number, loop: number): Promise\<void> 787 788设置循环模式。使用Promise方式异步获取返回值。 789 790**系统能力：** SystemCapability.Multimedia.Media.SoundPool 791 792**参数：** 793 794| 参数名 | 类型 | 必填 | 说明 | 795| -------- | ---------------------- | ---- | --------------------------- | 796| streamID | number | 是 | 音频流ID，通过play方法获取。 | 797| loop | number | 是 | 设置循环次数。<br>当loop≥0时，实际播放次数为loop+1。<br> 当loop＜0时，表示一直循环。| 798 799**返回值：** 800 801| 类型 | 说明 | 802| ---------------- | -------------------------------- | 803| Promise\<void> | 异步音频池setLoop方法的Promise返回值。 | 804 805**错误码：** 806 807以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 808 809| 错误码ID | 错误信息 | 810| -------- | --------------------------------------- | 811| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. | 812| 5400102 | Operation not allowed. Return by promise. | 813| 5400105 | Service died. Return by promise. | 814 815**示例：** 816 817```js 818import { BusinessError } from '@kit.BasicServicesKit'; 819 820//创建soundPool实例。 821let soundPool: media.SoundPool; 822let audioRendererInfo: audio.AudioRendererInfo = { 823 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 824 rendererFlags: 1 825} 826media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 827 if (error) { 828 console.error(`Failed to createSoundPool`) 829 return; 830 } else { 831 soundPool = soundPool_; 832 console.info(`Succeeded in createSoundPool`) 833 let streamID: number = 0; 834 //先通过调用play方法获取到对应的streamID。 835 //设置循环1次。 836 soundPool.setLoop(streamID, 1).then(() => { 837 console.info('Succeeded in setLoopping soundpool, streamID:' + streamID); 838 }).catch((err: BusinessError) => { 839 console.error('Failed to setLoop soundPool and catch error is ' + err.message); 840 }); 841 } 842}); 843 844``` 845 846### setPriority 847 848setPriority(streamID: number, priority: number, callback: AsyncCallback\<void>): void 849 850设置音频流播放的优先级。使用callback方式异步获取返回值。 851 852**系统能力：** SystemCapability.Multimedia.Media.SoundPool 853 854**参数：** 855 856| 参数名 | 类型 | 必填 | 说明 | 857| -------- | ---------------------- | ---- | --------------------------- | 858| streamID | number | 是 | 音频流ID，通过play方法获取。 | 859| priority | number | 是 | 优先级，0表示最低优先级。设置范围为大于等于0的整数。 | 860| callback | AsyncCallback\<void> | 是 | 异步音频池setPriority方法的回调方法。 | 861 862**错误码：** 863 864以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 865 866| 错误码ID | 错误信息 | 867| -------- | --------------------------------------- | 868| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by callback. | 869| 5400102 | Operation not allowed. Return by callback. | 870| 5400105 | Service died. Return by callback. | 871 872**示例：** 873 874```js 875import { BusinessError } from '@kit.BasicServicesKit'; 876 877//创建soundPool实例。 878let soundPool: media.SoundPool; 879let audioRendererInfo: audio.AudioRendererInfo = { 880 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 881 rendererFlags: 1 882} 883media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 884 if (error) { 885 console.error(`Failed to createSoundPool`) 886 return; 887 } else { 888 soundPool = soundPool_; 889 console.info(`Succeeded in createSoundPool`) 890 let streamID: number = 0; 891 // 先调用play方法获取到对应资源的streamID。 892 // 给对应的streamID资源设置优先级为1。 893 soundPool.setPriority(streamID, 1, (error: BusinessError) => { 894 if (error) { 895 console.error(`Failed to setPriority soundPool: errCode is ${error.code}, errMessage is ${error.message}`) 896 } else { 897 console.info('Succeeded in setPriority soundpool, streamID:' + streamID); 898 } 899 }); 900 } 901}); 902 903``` 904 905### setPriority 906 907setPriority(streamID: number, priority: number): Promise\<void> 908 909设置音频流优先级。使用Promise方式异步获取返回值。 910 911**系统能力：** SystemCapability.Multimedia.Media.SoundPool 912 913**参数：** 914 915| 参数名 | 类型 | 必填 | 说明 | 916| -------- | ---------------------- | ---- | --------------------------- | 917| streamID | number | 是 | 音频流ID，通过play方法获取。 | 918| priority | number | 是 | 优先级，0表示最低优先级。设置范围为大于等于0的整数。 | 919 920**返回值：** 921 922| 类型 | 说明 | 923| ---------------- | -------------------------------- | 924| Promise\<void> | 异步音频池setPriority的Promise返回值。 | 925 926**错误码：** 927 928以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 929 930| 错误码ID | 错误信息 | 931| -------- | --------------------------------------- | 932| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. | 933| 5400102 | Operation not allowed. Return by promise. | 934| 5400105 | Service died. Return by promise. | 935 936**示例：** 937 938```js 939import { BusinessError } from '@kit.BasicServicesKit'; 940 941//创建soundPool实例。 942let soundPool: media.SoundPool; 943let audioRendererInfo: audio.AudioRendererInfo = { 944 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 945 rendererFlags: 1 946} 947media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 948 if (error) { 949 console.error(`Failed to createSoundPool`) 950 return; 951 } else { 952 soundPool = soundPool_; 953 console.info(`Succeeded in createSoundPool`) 954 let streamID: number = 0; 955 // 先调用play方法获取到对应资源的streamID。 956 // 给对应的streamID资源设置优先级为1。 957 958 soundPool.setPriority(streamID, 1).then(() => { 959 console.info('Succeeded in setPriority soundpool'); 960 }, (err: BusinessError) => { 961 console.error('Failed to setPriority soundPool and catch error is ' + err.message); 962 }); 963 } 964}); 965 966``` 967 968### setRate 969 970setRate(streamID: number, rate: audio.AudioRendererRate, callback: AsyncCallback\<void>): void 971 972设置音频流播放速率。使用callback方式异步获取返回值。 973 974**系统能力：** SystemCapability.Multimedia.Media.SoundPool 975 976**参数：** 977 978| 参数名 | 类型 | 必填 | 说明 | 979| -------- | ---------------------- | ---- | --------------------------- | 980| streamID | number | 是 | 音频流ID，通过play方法获取。 | 981| rate | [audio.AudioRendererRate](../apis-audio-kit/js-apis-audio.md#audiorendererrate8) | 是 | 音频rate相关参数。 | 982| callback | AsyncCallback\<void> | 是 | 异步音频池setRate方法的回调方法。 | 983 984**错误码：** 985 986以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 987 988| 错误码ID | 错误信息 | 989| -------- | --------------------------------------- | 990| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by callback. | 991| 5400102 | Operation not allowed. Return by callback. | 992| 5400105 | Service died. Return by callback. | 993 994**示例：** 995 996```js 997import { BusinessError } from '@kit.BasicServicesKit'; 998 999//创建soundPool实例。 1000let soundPool: media.SoundPool; 1001let audioRendererInfo: audio.AudioRendererInfo = { 1002 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1003 rendererFlags: 1 1004} 1005media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 1006 if (error) { 1007 console.error(`Failed to createSoundPool`) 1008 return; 1009 } else { 1010 soundPool = soundPool_; 1011 console.info(`Succeeded in createSoundPool`) 1012 let streamID: number = 0; 1013 let selectedAudioRendererRate: audio.AudioRendererRate = audio.AudioRendererRate.RENDER_RATE_NORMAL; // 默认正常速率 1014 // 先调用play方法获取到对应资源的streamID。 1015 soundPool.setRate(streamID, selectedAudioRendererRate, (error: BusinessError) => { 1016 if (error) { 1017 console.error(`Failed to setRate soundPool: errCode is ${error.code}, errMessage is ${error.message}`) 1018 } else { 1019 console.info('Succeeded in setRate success, streamID:' + streamID); 1020 } 1021 }) 1022 } 1023}); 1024 1025``` 1026 1027### setRate 1028 1029setRate(streamID: number, rate: audio.AudioRendererRate): Promise\<void> 1030 1031设置音频流的播放速率。使用Promise方式异步获取返回值。 1032 1033**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1034 1035**参数：** 1036 1037| 参数名 | 类型 | 必填 | 说明 | 1038| -------- | ---------------------- | ---- | --------------------------- | 1039| streamID | number | 是 | 音频流ID，通过play方法获取。 | 1040| rate | [audio.AudioRendererRate](../apis-audio-kit/js-apis-audio.md#audiorendererrate8) | 是 | 音频rate相关参数。 | 1041 1042**返回值：** 1043 1044| 类型 | 说明 | 1045| ---------------- | -------------------------------- | 1046| Promise\<void> | 异步音频池setRate方法的Promise返回值。 | 1047 1048**错误码：** 1049 1050以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1051 1052| 错误码ID | 错误信息 | 1053| -------- | --------------------------------------- | 1054| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. | 1055| 5400102 | Operation not allowed. Return by promise. | 1056| 5400105 | Service died. Return by promise. | 1057 1058**示例：** 1059 1060```js 1061import { BusinessError } from '@kit.BasicServicesKit'; 1062 1063//创建soundPool实例。 1064let soundPool: media.SoundPool; 1065let audioRendererInfo: audio.AudioRendererInfo = { 1066 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1067 rendererFlags: 1 1068} 1069media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 1070 if (error) { 1071 console.error(`Failed to createSoundPool`) 1072 return; 1073 } else { 1074 soundPool = soundPool_; 1075 console.info(`Succeeded in createSoundPool`) 1076 let streamID: number = 0; 1077 let selectedAudioRendererRate: audio.AudioRendererRate = audio.AudioRendererRate.RENDER_RATE_NORMAL; // 默认正常速率 1078 // 先调用play方法获取到对应资源的streamID。 1079 soundPool.setRate(streamID, selectedAudioRendererRate).then(() => { 1080 console.info('Succeeded in setRate soundpool'); 1081 }, (err: BusinessError) => { 1082 console.error('Failed to setRate soundpool and catch error is ' + err.message); 1083 }); 1084 } 1085}); 1086 1087``` 1088 1089### setVolume 1090 1091setVolume(streamID: number, leftVolume: number, rightVolume: number, callback: AsyncCallback\<void>): void 1092 1093设置音频流播放音量。使用callback方式异步获取返回值。 1094 1095**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1096 1097**参数：** 1098 1099| 参数名 | 类型 | 必填 | 说明 | 1100| -------- | ---------------------- | ---- | --------------------------- | 1101| streamID | number | 是 | 音频流ID，通过play方法获取。 | 1102| leftVolume | number | 是 | 左声道音量，设置范围为0.0-1.0之间。 | 1103| rightVolume | number | 是 | 右声道音量，设置范围为0.0-1.0之间，当前右声道设置无效，以左声道为准。 | 1104| callback | AsyncCallback\<void> | 是 | 异步音频池setVolume方法的回调方法。 | 1105 1106**错误码：** 1107 1108以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1109 1110| 错误码ID | 错误信息 | 1111| -------- | --------------------------------------- | 1112| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by callback. | 1113| 5400102 | Operation not allowed. Return by callback. | 1114| 5400105 | Service died. Return by callback. | 1115 1116**示例：** 1117 1118```js 1119import { BusinessError } from '@kit.BasicServicesKit'; 1120 1121//创建soundPool实例。 1122let soundPool: media.SoundPool; 1123let audioRendererInfo: audio.AudioRendererInfo = { 1124 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1125 rendererFlags: 1 1126} 1127media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 1128 if (error) { 1129 console.error(`Failed to createSoundPool`) 1130 return; 1131 } else { 1132 soundPool = soundPool_; 1133 console.info(`Succeeded in createSoundPool`) 1134 let streamID: number = 0; 1135 // 先调用play方法获取到对应资源的streamID。 1136 //设置音量为0.5。 1137 soundPool.setVolume(streamID, 0.5, 0.5, (error: BusinessError) => { 1138 if (error) { 1139 console.error(`Failed to setVolume soundPool: errCode is ${error.code}, errMessage is ${error.message}`) 1140 } else { 1141 console.info('Succeeded in setVolume soundpool, streamID:' + streamID); 1142 } 1143 }) 1144 } 1145}); 1146 1147``` 1148 1149### setVolume 1150 1151setVolume(streamID: number, leftVolume: number, rightVolume: number): Promise\<void> 1152 1153设置音频流的播放音量。使用Promise方式异步获取返回值。 1154 1155**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1156 1157**参数：** 1158 1159| 参数名 | 类型 | 必填 | 说明 | 1160| -------- | ---------------------- | ---- | --------------------------- | 1161| streamID | number | 是 | 音频流ID，通过play方法获取。 | 1162| leftVolume | number | 是 | 左声道音量，设置范围为0.0-1.0之间。 | 1163| rightVolume | number | 是 | 右声道音量，设置范围为0.0-1.0之间，当前右声道设置无效，以左声道为准。 | 1164 1165**返回值：** 1166 1167| 类型 | 说明 | 1168| ---------------- | -------------------------------- | 1169| Promise\<void> | 异步音频池setVolume方法的Promise返回值。 | 1170 1171**错误码：** 1172 1173以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1174 1175| 错误码ID | 错误信息 | 1176| -------- | --------------------------------------- | 1177| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise. | 1178| 5400102 | Operation not allowed. Return by promise. | 1179| 5400105 | Service died. Return by promise. | 1180 1181**示例：** 1182 1183```js 1184import { BusinessError } from '@kit.BasicServicesKit'; 1185 1186//创建soundPool实例。 1187let soundPool: media.SoundPool; 1188let audioRendererInfo: audio.AudioRendererInfo = { 1189 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1190 rendererFlags: 1 1191} 1192media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 1193 if (error) { 1194 console.error(`Failed to createSoundPool`) 1195 return; 1196 } else { 1197 soundPool = soundPool_; 1198 console.info(`Succeeded in createSoundPool`) 1199 let streamID: number = 0; 1200 // 先调用play方法获取到对应资源的streamID。 1201 1202 soundPool.setVolume(streamID, 0.5, 0.5).then(() => { 1203 console.info('Succeeded in setVolume soundpool'); 1204 }, (err: BusinessError) => { 1205 console.error('Failed to setVolume soundPool and catch error is ' + err.message); 1206 }); 1207 } 1208}); 1209 1210``` 1211 1212### unload 1213 1214unload(soundID: number, callback: AsyncCallback\<void>): void 1215 1216卸载音频资源。使用callback方式异步获取返回值。 1217 1218**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1219 1220**参数：** 1221 1222| 参数名 | 类型 | 必填 | 说明 | 1223| -------- | ---------------------- | ---- | --------------------------- | 1224| soundID | number | 是 | 资源ID，通过load方法获取。 | 1225| callback | AsyncCallback\<void> | 是 | 异步音频池unload方法的回调方法。 | 1226 1227**错误码：** 1228 1229以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1230 1231| 错误码ID | 错误信息 | 1232| -------- | --------------------------------------- | 1233| 5400102 | Operation not allowed. Return by callback. | 1234| 5400103 | I/O error. Return by callback. | 1235| 5400105 | Service died. Return by callback. | 1236 1237**示例：** 1238 1239```js 1240import { BusinessError } from '@kit.BasicServicesKit'; 1241 1242//创建soundPool实例。 1243let soundPool: media.SoundPool; 1244let audioRendererInfo: audio.AudioRendererInfo = { 1245 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1246 rendererFlags: 1 1247} 1248media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 1249 if (error) { 1250 console.error(`Failed to createSoundPool`) 1251 return; 1252 } else { 1253 soundPool = soundPool_; 1254 console.info(`Succeeded in createSoundPool`) 1255 let soundID: number = 0; 1256 // 先调用load方法获取到对应资源的soundID。 1257 soundPool.unload(soundID, (error: BusinessError) => { 1258 if (error) { 1259 console.error(`Failed to unload soundPool: errCode is ${error.code}, errMessage is ${error.message}`) 1260 } else { 1261 console.info('Succceeded in unload soundPool'); 1262 } 1263 }) 1264 } 1265}); 1266 1267``` 1268 1269### unload 1270 1271unload(soundID: number): Promise\<void> 1272 1273卸载音频资源。使用Promise方式异步获取返回值。 1274 1275**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1276 1277**参数：** 1278 1279| 参数名 | 类型 | 必填 | 说明 | 1280| -------- | ---------------------- | ---- | --------------------------- | 1281| soundID | number | 是 | 资源ID，通过load方法获取。 | 1282 1283**返回值：** 1284 1285| 类型 | 说明 | 1286| ---------------- | -------------------------------- | 1287| Promise\<void> | 异步音频池unload方法的Promise返回值。 | 1288 1289**错误码：** 1290 1291以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1292 1293| 错误码ID | 错误信息 | 1294| -------- | --------------------------------------- | 1295| 5400102 | Operation not allowed. Return by promise. | 1296| 5400103 | I/O error. Return by promise. | 1297| 5400105 | Service died. Return by promise. | 1298 1299**示例：** 1300 1301```js 1302import { BusinessError } from '@kit.BasicServicesKit'; 1303 1304//创建soundPool实例。 1305let soundPool: media.SoundPool; 1306let audioRendererInfo: audio.AudioRendererInfo = { 1307 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1308 rendererFlags: 1 1309} 1310media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 1311 if (error) { 1312 console.error(`Failed to createSoundPool`) 1313 return; 1314 } else { 1315 soundPool = soundPool_; 1316 console.info(`Succeeded in createSoundPool`) 1317 let soundID: number = 0; 1318 // 先调用load方法获取到对应资源的soundID。 1319 1320 soundPool.unload(soundID).then(() => { 1321 console.info('Succceeded in unload soundPool'); 1322 }, (err: BusinessError) => { 1323 console.error('Failed to unload soundPool and catch error is ' + err.message); 1324 }); 1325 } 1326}); 1327 1328``` 1329 1330### release 1331 1332release(callback: AsyncCallback\<void>): void 1333 1334释放音频池实例。使用callback方式异步获取返回值。 1335 1336**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1337 1338**参数：** 1339 1340| 参数名 | 类型 | 必填 | 说明 | 1341| -------- | ---------------------- | ---- | --------------------------- | 1342| callback | AsyncCallback\<void> | 是 | 异步音频池release方法的回调方法。 | 1343 1344**错误码：** 1345 1346以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1347 1348| 错误码ID | 错误信息 | 1349| -------- | --------------------------------------- | 1350| 5400105 | Service died. Return by callback. | 1351 1352**示例：** 1353 1354```js 1355import { BusinessError } from '@kit.BasicServicesKit'; 1356 1357//创建soundPool实例。 1358let soundPool: media.SoundPool; 1359let audioRendererInfo: audio.AudioRendererInfo = { 1360 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1361 rendererFlags: 1 1362} 1363media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 1364 if (error) { 1365 console.error(`Failed to createSoundPool`) 1366 return; 1367 } else { 1368 soundPool = soundPool_; 1369 console.info(`Succeeded in createSoundPool`) 1370 soundPool.release((error: BusinessError) => { 1371 if (error) { 1372 console.error(`Failed to release soundPool: errCode is ${error.code}, errMessage is ${error.message}`) 1373 } else { 1374 console.info('Succeeded in releasing soundPool'); 1375 } 1376 }) 1377 } 1378}); 1379 1380 1381``` 1382 1383### release 1384 1385release(): Promise\<void> 1386 1387释放音频池实例。使用Promise方式异步获取返回值。 1388 1389**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1390 1391**返回值：** 1392 1393| 类型 | 说明 | 1394| ---------------- | -------------------------------- | 1395| Promise\<void> | 异步音频池release方法的Promise返回值。 | 1396 1397**错误码：** 1398 1399以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。 1400 1401| 错误码ID | 错误信息 | 1402| -------- | --------------------------------------- | 1403| 5400105 | Service died. Return by promise. | 1404 1405**示例：** 1406 1407```js 1408import { BusinessError } from '@kit.BasicServicesKit'; 1409 1410//创建soundPool实例。 1411let soundPool: media.SoundPool; 1412let audioRendererInfo: audio.AudioRendererInfo = { 1413 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1414 rendererFlags: 1 1415} 1416media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 1417 if (error) { 1418 console.error(`Failed to createSoundPool`) 1419 return; 1420 } else { 1421 soundPool = soundPool_; 1422 console.info(`Succeeded in createSoundPool`) 1423 soundPool.release().then(() => { 1424 console.info('Succeeded in releasing soundPool'); 1425 }, (err: BusinessError) => { 1426 console.error('Failed to release soundPool and catch error is ' + err.message); 1427 }); 1428 } 1429}); 1430 1431``` 1432 1433### on('loadComplete') 1434 1435on(type: 'loadComplete', callback: Callback\<number>): void 1436 1437音频池资源加载完成监听。 1438 1439**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1440 1441**参数：** 1442 1443| 参数名 | 类型 | 必填 | 说明 | 1444| -------- | -------- | ---- | ------------------------------------------------------------ | 1445| type | string | 是 | 支持的事件：'loadComplete'，对应的ID加载完成会触发此回调。 | 1446| callback | Callback\<number> | 是 | 对应资源加载完成的资源ID。 | 1447 1448**示例：** 1449 1450```js 1451import { BusinessError } from '@kit.BasicServicesKit'; 1452 1453//创建soundPool实例。 1454let soundPool: media.SoundPool; 1455let audioRendererInfo: audio.AudioRendererInfo = { 1456 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1457 rendererFlags: 1 1458} 1459media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 1460 if (error) { 1461 console.error(`Failed to createSoundPool`) 1462 return; 1463 } else { 1464 soundPool = soundPool_; 1465 console.info(`Succeeded in createSoundPool`) 1466 soundPool.on('loadComplete', (soundId: number) => { 1467 console.info('Succeeded in loadComplete, soundId：' + soundId) 1468 }) 1469 } 1470}); 1471 1472``` 1473 1474### off('loadComplete') 1475 1476off(type: 'loadComplete'): void 1477 1478取消监听资源的加载完成。 1479 1480**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1481 1482**参数：** 1483 1484| 参数名 | 类型 | 必填 | 说明 | 1485| ------ | ------ | ---- | ------------------------------------------------------------ | 1486| type | string | 是 | 取消注册的事件：'loadComplete'。 | 1487 1488**示例：** 1489 1490```js 1491import { BusinessError } from '@kit.BasicServicesKit'; 1492 1493//创建soundPool实例。 1494let soundPool: media.SoundPool; 1495let audioRendererInfo: audio.AudioRendererInfo = { 1496 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1497 rendererFlags: 1 1498} 1499media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 1500 if (error) { 1501 console.error(`Failed to createSoundPool`) 1502 return; 1503 } else { 1504 soundPool = soundPool_; 1505 console.info(`Succeeded in createSoundPool`) 1506 soundPool.off('loadComplete') 1507 } 1508}); 1509 1510``` 1511 1512### on('playFinishedWithStreamId')<sup>18+</sup> 1513 1514on(type: 'playFinishedWithStreamId', callback: Callback\<number>): void 1515 1516音频池资源播放完成监听，同时返回播放结束的音频的streamId。 1517 1518当仅单独注册[on('playFinished')](#onplayfinished)事件回调或者[on('playFinishedWithStreamId')](#onplayfinishedwithstreamid18)事件回调时，当音频播放完成的时候，都会触发注册的回调。 1519 1520当同时注册[on('playFinished')](#onplayfinished)事件回调和[on('playFinishedWithStreamId')](#onplayfinishedwithstreamid18)事件回调时，当音频播放完成的时候，仅会触发'playFinishedWithStreamId'事件回调，不会触发'playFinished'事件回调。 1521 1522**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1523 1524**参数：** 1525 1526| 参数名 | 类型 | 必填 | 说明 | 1527| -------- | -------- | ---- | ------------------------------------------------------------ | 1528| type | string | 是 | 支持的事件：'playFinishedWithStreamId'，音频流播放完成会触发此回调，并返回播放完成的音频的streamId。 | 1529| callback | Callback\<number> | 是 | 异步'playFinishedWithStreamId'的回调方法。返回播放完成的音频的streamId。 | 1530 1531**示例：** 1532 1533```js 1534import { BusinessError } from '@kit.BasicServicesKit'; 1535 1536//创建soundPool实例。 1537let soundPool_: media.SoundPool; 1538let audioRendererInfo: audio.AudioRendererInfo = { 1539 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1540 rendererFlags: 1 1541} 1542media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool: media.SoundPool) => { 1543 if (error) { 1544 console.error(`Failed to createSoundPool`) 1545 } else { 1546 soundPool_ = soundPool; 1547 console.info(`Succeeded in createSoundPool`) 1548 soundPool_.on('playFinishedWithStreamId', (streamId) => { 1549 console.info('The stream with streamId: ' + streamId + ' has finished playing.') 1550 }); 1551 } 1552}); 1553 1554``` 1555 1556### off('playFinishedWithStreamId')<sup>18+</sup> 1557 1558off(type: 'playFinishedWithStreamId'): void 1559 1560取消监听音频池资源播放完成。 1561 1562**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1563 1564**参数：** 1565 1566| 参数名 | 类型 | 必填 | 说明 | 1567| ------ | ------ | ---- | ------------------------------------------------------------ | 1568| type | string | 是 | 取消注册的事件：'playFinishedWithStreamId'。 | 1569 1570**示例：** 1571 1572```js 1573import { BusinessError } from '@kit.BasicServicesKit'; 1574 1575//创建soundPool实例。 1576let soundPool_: media.SoundPool; 1577let audioRendererInfo: audio.AudioRendererInfo = { 1578 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1579 rendererFlags: 1 1580} 1581media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool: media.SoundPool) => { 1582 if (error) { 1583 console.error(`Failed to createSoundPool`) 1584 } else { 1585 soundPool_ = soundPool; 1586 console.info(`Succeeded in createSoundPool`) 1587 soundPool_.off('playFinishedWithStreamId') 1588 } 1589}); 1590 1591``` 1592 1593### on('playFinished') 1594 1595on(type: 'playFinished', callback: Callback\<void>): void 1596 1597音频池资源播放完成监听。 1598 1599**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1600 1601**参数：** 1602 1603| 参数名 | 类型 | 必填 | 说明 | 1604| -------- | -------- | ---- | ------------------------------------------------------------ | 1605| type | string | 是 | 支持的事件：'playFinished'，音频流播放完成会触发此回调。 | 1606| callback | Callback\<void> | 是 | 异步'playFinished'的回调方法。 | 1607 1608**示例：** 1609 1610```js 1611import { BusinessError } from '@kit.BasicServicesKit'; 1612 1613//创建soundPool实例。 1614let soundPool: media.SoundPool; 1615let audioRendererInfo: audio.AudioRendererInfo = { 1616 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1617 rendererFlags: 1 1618} 1619media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 1620 if (error) { 1621 console.error(`Failed to createSoundPool`) 1622 return; 1623 } else { 1624 soundPool = soundPool_; 1625 console.info(`Succeeded in createSoundPool`) 1626 soundPool.on('playFinished', () => { 1627 console.info('Succeeded in playFinished') 1628 }); 1629 } 1630}); 1631 1632``` 1633 1634### off('playFinished') 1635 1636off(type: 'playFinished'): void 1637 1638取消监听音频池资源播放完成。 1639 1640**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1641 1642**参数：** 1643 1644| 参数名 | 类型 | 必填 | 说明 | 1645| ------ | ------ | ---- | ------------------------------------------------------------ | 1646| type | string | 是 | 取消注册的事件：'playFinished'。 | 1647 1648**示例：** 1649 1650```js 1651import { BusinessError } from '@kit.BasicServicesKit'; 1652 1653//创建soundPool实例。 1654let soundPool: media.SoundPool; 1655let audioRendererInfo: audio.AudioRendererInfo = { 1656 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1657 rendererFlags: 1 1658} 1659media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 1660 if (error) { 1661 console.error(`Failed to createSoundPool`) 1662 return; 1663 } else { 1664 soundPool = soundPool_; 1665 console.info(`Succeeded in createSoundPool`) 1666 soundPool.off('playFinished') 1667 } 1668}); 1669 1670``` 1671 1672### on('error') 1673 1674on(type: 'error', callback: ErrorCallback): void 1675 1676监听[SoundPool](#soundpool)的错误事件，该事件仅用于错误提示。 1677 1678**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1679 1680**参数：** 1681 1682| 参数名 | 类型 | 必填 | 说明 | 1683| -------- | -------- | ---- | ------------------------------------------------------------ | 1684| type | string | 是 | 错误事件回调类型，支持的事件：'error'，用户操作和系统都会触发此事件。 | 1685| callback | ErrorCallback | 是 | 错误事件回调方法：使用播放器的过程中发生错误，会提供错误码ID和错误信息。 | 1686 1687SoundPool回调的**错误分类**<a name = error_info></a>可以分为以下几种： 1688 1689| 错误码ID | 错误信息 | 说明 | 1690| -------- | --------------------- | ------------------------------------------------------------ | 1691| 401 | Invalid Parameter. | 入参错误，表示调用无效。 | 1692| 801 | Unsupport Capability. | 不支持该API能力，表示调用无效。 | 1693| 5400101 | No Memory. | 内存不足。 | 1694| 5400102 | Operation Not Allowed. | 当前状态机不支持此操作，表示调用无效。 | 1695| 5400103 | IO Error. | I/O异常。 | 1696| 5400105 | Service Died. | 播放进程死亡，音频池依赖的service端发生异常。| 1697 1698**示例：** 1699 1700```js 1701import { BusinessError } from '@kit.BasicServicesKit'; 1702 1703//创建soundPool实例。 1704let soundPool: media.SoundPool; 1705let audioRendererInfo: audio.AudioRendererInfo = { 1706 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1707 rendererFlags: 1 1708} 1709media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 1710 if (error) { 1711 console.error(`Failed to createSoundPool`) 1712 return; 1713 } else { 1714 soundPool = soundPool_; 1715 console.info(`Succeeded in createSoundPool`) 1716 soundPool.on('error', (error: BusinessError) => { 1717 console.error('error happened,and error message is :' + error.message) 1718 console.error('error happened,and error code is :' + error.code) 1719 }) 1720 } 1721}); 1722 1723``` 1724 1725### off('error') 1726 1727off(type: 'error'): void 1728 1729取消监听音频池的错误事件。 1730 1731**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1732 1733**参数：** 1734 1735| 参数名 | 类型 | 必填 | 说明 | 1736| ------ | ------ | ---- | ----------------------------------------- | 1737| type | string | 是 | 错误事件回调类型，取消注册的事件：'error'。 | 1738 1739**示例：** 1740 1741```js 1742import { BusinessError } from '@kit.BasicServicesKit'; 1743 1744//创建soundPool实例。 1745let soundPool: media.SoundPool; 1746let audioRendererInfo: audio.AudioRendererInfo = { 1747 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 1748 rendererFlags: 1 1749} 1750media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => { 1751 if (error) { 1752 console.error(`Failed to createSoundPool`) 1753 return; 1754 } else { 1755 soundPool = soundPool_; 1756 console.info(`Succeeded in createSoundPool`) 1757 soundPool.off('error') 1758 } 1759}); 1760``` 1761