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 '@ohos.multimedia.media'; 15import audio from '@ohos.multimedia.audio'; 16``` 17 18## PlayParameters 19 20表示音频池播放参数设置。 21 22通过设置播放相关参数，来控制播放的音量，循环次数，播放优先级等参数。 23 24**系统能力：** SystemCapability.Multimedia.Media.SoundPool 25 26| 名称 | 类型 | 必填 | 说明 | 27| --------------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | 28| loop | number | 否 | 设置循环参数，0为循环一次，-1表示一直循环。 | 29| rate | number | 否 | 设置音频播放的倍速，具体倍速范围参照[AudioRendererRate](js-apis-audio.md#AudioRendererRate)。 | 30| leftVolume | number | 否 | 设置左声道音量，设置范围（0~1）。 | 31| rightVolume | number | 否 | 设置右声道音量。（当前不支持左右分别设置，将以左声道音量为准）。 | 32| priority | number | 否 | 音频流播放的优先级，0为最低优先级，数值越大优先级越高，通过相互比较大小确定播放优先级。 | 33| parallelPlayFlag | boolean | 否 | 是否和其它正在播放的音频并行播放的标识，true:不抢占音频焦点和其它正在播放的音频并行播放，false:抢占焦点打断其它正在播放的音频。<br/>此接口为系统接口。| 34 35## SoundPool 36 37音频池提供了系统声音的加载、播放、音量设置、循环设置、停止播放、资源卸载等功能, 在调用SoundPool的接口前，需要先通过[createSoundPool](js-apis-media.md#mediacreatesoundpool10)创建实例 38 39### load 40 41load(uri: string, callback: AsyncCallback\<number>): void 42 43加载音频资源。使用callback方式异步获取资源ID，入参uri通过获取文件fd生成以"fd://"开头的文件描述字符串。 44 45**系统能力：** SystemCapability.Multimedia.Media.SoundPool 46 47**参数：** 48 49| 参数名 | 类型 | 必填 | 说明 | 50| -------- | -------------------------------------- | ---- | ------------------------------------- | 51| uri | string | 是 | 音频文件的加载路径描述，一般以"fd://"开头的文件描述。 | 52| callback | AsyncCallback\<number> | 是 | 异步音频资源加载返回的资源id，有效值大于0。 | 53 54**错误码：** 55 56以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 57 58| 错误码ID | 错误信息 | 59| -------- | --------------------------------------- | 60| 5400102 | Operation not allowed. Return by callback.| 61| 5400103 | I/O error. Return by callback. | 62| 5400105 | Service died. Return by callback. | 63 64**示例：** 65 66```ts 67import fs from '@ohos.file.fs'; 68 69let uri:string = ""; 70 71//获取fd的uri路径 72await fs.open('/test_01.mp3', fs.OpenMode.READ_ONLY).then((file: fs.File) => { 73 console.info("file fd: " + file.fd); 74 uri = 'fd://' + (file.fd).toString() 75}); // '/test_01.mp3' 作为样例，使用时需要传入文件对应路径。 76 77soundPool.load(uri, (error: BusinessError, soundId_: number) => { 78 if (error) { 79 console.info(`load soundPool Error: errCode is ${error.code}, errMessage is ${error.message}`) 80 } else { 81 console.info(`load soundPool Success` + JSON.stringify(soundId_)) 82 } 83}) 84``` 85 86### load 87 88load(uri: string): Promise\<number> 89 90加载音频资源。使用Promise方式异步获取资源ID，入参uri通过获取文件fd生成以"fd://"开头的文件描述字符串。 91 92**系统能力：** SystemCapability.Multimedia.Media.SoundPool 93 94**参数：** 95 96| 参数名 | 类型 | 必填 | 说明 | 97| ------ | -------------------------------------- | ---- | -------------------------- | 98| uri | string | 是 | 音频文件的加载路径描述，一般以"fd://"开头的文件描述。 | 99 100**返回值：** 101 102| 类型 | 说明 | 103| -------------- | ------------------------------------------ | 104| Promise\<number> | 异步音频池资源的加载，返回资源的id，有效值大于0。 | 105 106**错误码：** 107 108以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 109 110| 错误码ID | 错误信息 | 111| -------- | --------------------------------------- | 112| 5400102 | Operation not allowed. Return by promise.| 113| 5400103 | I/O error. Return by promise. | 114| 5400105 | Service died. Return by promise. | 115 116**示例：** 117 118```ts 119import fs from '@ohos.file.fs'; 120 121let uri:string = ""; 122let soundID: number; 123 124//获取fd的uri路径 125await fs.open('/test_01.mp3', fs.OpenMode.READ_ONLY).then((file: fs.File) => { 126 console.info("file fd: " + file.fd); 127 uri = 'fd://' + (file.fd).toString() 128}); // '/test_01.mp3' 作为样例，使用时需要传入文件对应路径。 129 130soundPool.load(uri).then((soundId: number) => { 131 console.info('soundPool load uri success'); 132 soundID = soundId; 133}).catch((err) => { 134 console.error('soundPool load failed and catch error is ' + err.message); 135}); 136 137``` 138 139### load 140 141load(fd: number, offset: number, length: number, callback: AsyncCallback\<number>): void 142 143加载音频资源。使用callback方式异步获取资源ID，入参可手动传入资源信息或通过读取应用内置资源自动获取。 144 145**系统能力：** SystemCapability.Multimedia.Media.SoundPool 146 147**参数：** 148 149| 参数名 | 类型 | 必填 | 说明 | 150| -------- | ---------------------- | ---- | --------------------------- | 151| fd | number | 是 | 资源句柄，通过resourceManager.getRawFileDescriptor获取。 | 152| offset | number | 是 | 资源偏移量，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 153| length | number | 是 | 资源长度，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 154| callback | AsyncCallback\<number> | 是 | 获取回调的soundID，有效值大于0。 | 155 156**错误码：** 157 158以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 159 160| 错误码ID | 错误信息 | 161| -------- | --------------------------------------- | 162| 5400102 | Operation not allowed. Return by callback. | 163| 5400103 | I/O error. Return by callback. | 164| 5400105 | Service died. Return by callback. | 165 166**示例：** 167 168```ts 169import fs from '@ohos.file.fs'; 170 171let fd: number; 172let soundID: number; 173let fileSize: number; 174let maxOffset: number; 175 176//获取fd的描述信息 177await fs.open('/test_01.mp3', fs.OpenMode.READ_ONLY).then((file: fs.File) => { 178 console.info("file fd: " + file.fd); 179}); 180let stat: fs.Stat = await fs.stat('/test_01.mp3'); 181fileSize = stat.size; 182maxOffset = stat.size; 183 184soundPool.load(file.fd, 0, fileSize, (error: BusinessError, soundId_: number) => { 185 if (error) { 186 console.info(`load soundPool Error: errCode is ${error.code}, errMessage is ${error.message}`) 187 } else { 188 soundID = soundId_; 189 console.info('load success soundid:' + soundId_); 190 } 191}) 192 193``` 194 195### load 196 197load(fd: number, offset: number, length: number): Promise\<number> 198 199加载音频资源。使用Promise方式异步获取资源ID，入参可手动传入资源信息或通过读取应用内置资源自动获取。 200 201**系统能力：** SystemCapability.Multimedia.Media.SoundPool 202 203**参数：** 204 205| 参数名 | 类型 | 必填 | 说明 | 206| -------- | ---------------------- | ---- | --------------------------- | 207| fd | number | 是 | 资源句柄，通过resourceManager.getRawFileDescriptor获取。 | 208| offset | number | 是 | 资源偏移量，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 209| length | number | 是 | 资源长度，需要基于预置资源的信息输入，非法值会造成音视频资源解析错误。 | 210 211**返回值：** 212 213| 类型 | 说明 | 214| ---------------- | -------------------------------- | 215| Promise\<number> | 获取回调的soundID，有效值大于0。 | 216 217**错误码：** 218 219以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 220 221| 错误码ID | 错误信息 | 222| -------- | --------------------------------------- | 223| 5400102 | Operation not allowed. Return by promise.| 224| 5400103 | I/O error. Return by promise. | 225| 5400105 | Service died. Return by promise. | 226 227**示例：** 228 229```ts 230import fs from '@ohos.file.fs'; 231 232let fd: number; 233let soundID: number; 234let fileSize: number; 235let maxOffset: number; 236 237//获取fd的描述信息 238await fs.open('/test_01.mp3', fs.OpenMode.READ_ONLY).then((file: fs.File) => { 239 console.info("file fd: " + file.fd); 240}); 241let stat: fs.Stat = await fs.stat('/test_01.mp3'); 242fileSize = stat.size; 243maxOffset = stat.size; 244 245soundPool.load(file.fd, 0, fileSize).then((soundId: number) => { 246 console.info('load success'); 247 soundID = soundId; 248}).catch((err) => { 249 console.error('soundpool load failed and catch error is ' + err.message); 250}); 251``` 252 253### play 254 255play(soundID: number, params: PlayParameters, callback: AsyncCallback\<number>): void 256 257播放音频资源。使用callback方式异步获取音频流streamID。 258 259**系统能力：** SystemCapability.Multimedia.Media.SoundPool 260 261**参数：** 262 263| 参数名 | 类型 | 必填 | 说明 | 264| -------- | ---------------------- | ---- | --------------------------- | 265| soundID | number | 是 | 资源ID，通过load方法获取。 | 266| params | [PlayParameters](#playparameters) | 是 | play播放相关参数的设置。 | 267| callback | AsyncCallback\<number> | 是 | 获取回调的音频流ID，有效值大于0。 | 268 269**错误码：** 270 271以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 272 273| 错误码ID | 错误信息 | 274| -------- | --------------------------------------- | 275| 5400102 | Operation not allowed. Return by callback. | 276| 5400105 | Service died. Return by callback. | 277 278**示例：** 279 280```js 281let soundID: number; 282let streamID: number; 283let playParameters: media.PlayParameters = { 284 loop = 3, // 循环4次 285 rate = audio.AudioRendererRate.RENDER_RATE_NORMAL, // 正常倍速 286 leftVolume = 0.5, // range = 0.0-1.0 287 rightVolume = 0.5, // range = 0.0-1.0 288 priority = 0, // 最低优先级 289 parallelPlayFlag = false // 不和其它正在播放的音频并行播放 290 } 291soundPool.play(soundID, playParameters, (error: BusinessError, streamId: number) => { 292 if (error) { 293 console.info(`play sound Error: errCode is ${error.code}, errMessage is ${error.message}`) 294 } else { 295 streamID = streamId; 296 console.info('play success soundid:' + streamId); 297 } 298}) 299``` 300 301### play 302 303play(soundID: number, callback: AsyncCallback\<number>): void 304 305播放音频资源。使用callback方式异步获取音频流streamID。 306 307**系统能力：** SystemCapability.Multimedia.Media.SoundPool 308 309**参数：** 310 311| 参数名 | 类型 | 必填 | 说明 | 312| -------- | ---------------------- | ---- | --------------------------- | 313| soundID | number | 是 | 资源ID，通过load方法获取。 | 314| callback | AsyncCallback\<number> | 是 | 获取回调的音频流ID，有效值大于0。 | 315 316**错误码：** 317 318以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 319 320| 错误码ID | 错误信息 | 321| -------- | --------------------------------------- | 322| 5400102 | Operation not allowed. Return by callback. | 323| 5400105 | Service died. Return by callback. | 324 325**示例：** 326 327```js 328let soundID: number; 329let streamID: number; 330soundPool.play(soundID, (error: BusinessError, streamId: number) => { 331 if (error) { 332 console.info(`play sound Error: errCode is ${error.code}, errMessage is ${error.message}`) 333 } else { 334 streamID = streamId; 335 console.info('play success soundid:' + streamId); 336 } 337}) 338``` 339 340### play 341 342play(soundID: number, params?: PlayParameters): Promise\<number> 343 344播放音频资源。使用Promise方式异步获取音频流streamID。 345 346**系统能力：** SystemCapability.Multimedia.Media.SoundPool 347 348**参数：** 349 350| 参数名 | 类型 | 必填 | 说明 | 351| -------- | ---------------------- | ---- | --------------------------- | 352| soundID | number | 是 | 资源ID，通过load方法获取。 | 353| params | [PlayParameters](#playparameters) | 否 | play播放相关参数的设置。 | 354 355**返回值：** 356 357| 类型 | 说明 | 358| ---------------- | -------------------------------- | 359| Promise\<number> | 获取回调的音频流ID，有效值大于0。 | 360 361**错误码：** 362 363以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 364 365| 错误码ID | 错误信息 | 366| -------- | --------------------------------------- | 367| 5400102 | Operation not allowed. Return by promise. | 368| 5400105 | Service died. Return by promise. | 369 370**示例：** 371 372```js 373let soundID: number; 374let streamID: number; 375let playParameters: media.PlayParameters = { 376 loop = 3, // 循环4次 377 rate = audio.AudioRendererRate.RENDER_RATE_NORMAL, // 正常倍速 378 leftVolume = 0.5, // range = 0.0-1.0 379 rightVolume = 0.5, // range = 0.0-1.0 380 priority = 0, // 最低优先级 381 parallelPlayFlag = false // 不和其它正在播放的音频并行播放 382 } 383 384soundPool.play(soundID, playParameters).then((streamId: number) => { 385 console.info('play success'); 386 streamID = streamId; 387}).catch((err: BusinessError) => { 388 console.error('soundpool play failed and catch error is ' + err.message); 389}); 390``` 391 392### stop 393 394stop(streamID: number, callback: AsyncCallback\<void>): void 395 396停止播放音频资源。使用callback方式异步获取返回值。 397 398**系统能力：** SystemCapability.Multimedia.Media.SoundPool 399 400**参数：** 401 402| 参数名 | 类型 | 必填 | 说明 | 403| -------- | ---------------------- | ---- | --------------------------- | 404| streamID | number | 是 | 音频流ID，通过play方法获取。 | 405| callback | AsyncCallback\<void> | 是 | 异步音频池stop的回调方法。 | 406 407**错误码：** 408 409以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 410 411| 错误码ID | 错误信息 | 412| -------- | --------------------------------------- | 413| 5400102 | Operation not allowed. Return by callback. | 414| 5400105 | Service died. Return by callback. | 415 416**示例：** 417 418```js 419let streamID: number; 420//先调用play方法给拿到对应的streamID 421soundPool.stop(streamID, (error: BusinessError) => { 422 if (error) { 423 console.info(`stop sound Error: errCode is ${error.code}, errMessage is ${error.message}`) 424 } else { 425 console.info('stop success'); 426 } 427}) 428 429``` 430 431### stop 432 433stop(streamID: number): Promise\<void> 434 435停止streamID对应的音频播放。使用Promise方式异步获取返回值。 436 437**系统能力：** SystemCapability.Multimedia.Media.SoundPool 438 439**参数：** 440 441| 参数名 | 类型 | 必填 | 说明 | 442| -------- | ---------------------- | ---- | --------------------------- | 443| streamID | number | 是 | 音频流ID，通过play方法获取。 | 444 445**返回值：** 446 447| 类型 | 说明 | 448| ---------------- | -------------------------------- | 449| Promise\<void> | 返回值。 | 450 451**错误码：** 452 453以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 454 455| 错误码ID | 错误信息 | 456| -------- | --------------------------------------- | 457| 5400102 | Operation not allowed. Return by promise. | 458| 5400105 | Service died. Return by promise. | 459 460**示例：** 461 462```js 463let streamID: number; 464//先调用play方法给拿到对应的streamID 465 466soundPool.stop(streamID).then(() => { 467 console.info('stop success'); 468}).catch((err) => { 469 console.error('soundpool load stop and catch error is ' + err.message); 470}); 471``` 472 473### setLoop 474 475setLoop(streamID: number, loop: number, callback: AsyncCallback\<void>): void; 476 477设置循环模式。使用callback方式异步获取返回值。 478 479**系统能力：** SystemCapability.Multimedia.Media.SoundPool 480 481**参数：** 482 483| 参数名 | 类型 | 必填 | 说明 | 484| -------- | ---------------------- | ---- | --------------------------- | 485| streamID | number | 是 | 音频流ID，通过play方法获取。 | 486| loop | number | 是 | 设置循环的次数，0为默认1次，小于0为一直循环。 | 487| callback | AsyncCallback\<void> | 是 | 异步setLoop的回调方法。 | 488 489**错误码：** 490 491以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 492 493| 错误码ID | 错误信息 | 494| -------- | --------------------------------------- | 495| 5400102 | Operation not allowed. Return by callback. | 496| 5400105 | Service died. Return by callback. | 497 498**示例：** 499 500```js 501let streamID: number; 502//先通过调用play方法获取到对应的streamID 503//设置循环2次 504soundPool.setLoop(streamID, 2, (error: BusinessError) => { 505 if (error) { 506 console.info(`setLoop soundPool Error: errCode is ${error.code}, errMessage is ${error.message}`) 507 } else { 508 console.info('setLoop success streamID:' + streamID); 509 } 510}) 511``` 512 513### setLoop 514 515setLoop(streamID: number, loop: number): Promise\<void> 516 517设置循环模式。使用Promise方式异步获取返回值。 518 519**系统能力：** SystemCapability.Multimedia.Media.SoundPool 520 521**参数：** 522 523| 参数名 | 类型 | 必填 | 说明 | 524| -------- | ---------------------- | ---- | --------------------------- | 525| streamID | number | 是 | 音频流ID，通过play方法获取。 | 526| loop | number | 是 | 设置循环的次数，0为默认1次，小于0为一直循环。| 527 528**返回值：** 529 530| 类型 | 说明 | 531| ---------------- | -------------------------------- | 532| Promise\<void> | 异步音频池setLoop方法的Promise返回值。 | 533 534**错误码：** 535 536以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 537 538| 错误码ID | 错误信息 | 539| -------- | --------------------------------------- | 540| 5400102 | Operation not allowed. Return by promise. | 541| 5400105 | Service died. Return by promise. | 542 543**示例：** 544 545```js 546let streamID: number; 547//先通过调用play方法获取到对应的streamID 548//设置循环1次 549soundPool.setLoop(streamID, 1).then(() => { 550 console.info('setLoop success streamID:' + streamID); 551}).catch((err) => { 552 console.error('soundpool setLoop failed and catch error is ' + err.message); 553}); 554``` 555 556### setPriority 557 558setPriority(streamID: number, priority: number, callback: AsyncCallback\<void>): void 559 560设置音频流播放的优先级。使用callback方式异步获取返回值。 561 562**系统能力：** SystemCapability.Multimedia.Media.SoundPool 563 564**参数：** 565 566| 参数名 | 类型 | 必填 | 说明 | 567| -------- | ---------------------- | ---- | --------------------------- | 568| streamID | number | 是 | 音频流ID，通过play方法获取。 | 569| priority | number | 是 | 优先级，0表示最低优先级。 | 570| callback | AsyncCallback\<void> | 是 | 异步音频池setPriority方法的回调方法。 | 571 572**错误码：** 573 574以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 575 576| 错误码ID | 错误信息 | 577| -------- | --------------------------------------- | 578| 5400102 | Operation not allowed. Return by callback. | 579| 5400105 | Service died. Return by callback. | 580 581**示例：** 582 583```js 584let streamID: number; 585// 先调用play方法获取到对应资源的streamID 586// 给对应的streamID资源设置优先级为1 587soundPool.setPriority(streamID, 1, (error: BusinessError) => { 588 if (error) { 589 console.info(`setPriority soundPool Error: errCode is ${error.code}, errMessage is ${error.message}`) 590 } else { 591 console.info('setPriority success streamID:' + streamID); 592 } 593}) 594 595``` 596 597### setPriority 598 599setPriority(streamID: number, priority: number): Promise\<void> 600 601设置音频流优先级。使用Promise方式异步获取返回值。 602 603**系统能力：** SystemCapability.Multimedia.Media.SoundPool 604 605**参数：** 606 607| 参数名 | 类型 | 必填 | 说明 | 608| -------- | ---------------------- | ---- | --------------------------- | 609| streamID | number | 是 | 音频流ID，通过play方法获取。 | 610| priority | number | 是 | 优先级，0表示最低优先级。 | 611 612**返回值：** 613 614| 类型 | 说明 | 615| ---------------- | -------------------------------- | 616| Promise\<void> | 异步音频池setPriority的Promise返回值。 | 617 618**错误码：** 619 620以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 621 622| 错误码ID | 错误信息 | 623| -------- | --------------------------------------- | 624| 5400102 | Operation not allowed. Return by promise. | 625| 5400105 | Service died. Return by promise. | 626 627**示例：** 628 629```js 630let streamID: number; 631// 先调用play方法获取到对应资源的streamID 632// 给对应的streamID资源设置优先级为1 633 634soundPool.setPriority(streamID, 1).then(() => { 635 console.info('setPriority success'); 636}).catch((err) => { 637 console.error('soundpool setPriority failed and catch error is ' + err.message); 638}); 639``` 640 641### setRate 642 643setRate(streamID: number, rate: audio.AudioRendererRate, callback: AsyncCallback\<void>): void 644 645设置音频流播放速率。使用callback方式异步获取返回值。 646 647**系统能力：** SystemCapability.Multimedia.Media.SoundPool 648 649**参数：** 650 651| 参数名 | 类型 | 必填 | 说明 | 652| -------- | ---------------------- | ---- | --------------------------- | 653| streamID | number | 是 | 音频流ID，通过play方法获取。 | 654| rate | [audio.AudioRendererRate](js-apis-audio.md#audiorendererrate8) | 是 | 音频rate相关参数。 | 655| callback | AsyncCallback\<void> | 是 | 异步音频池setRate方法的回调方法。 | 656 657**错误码：** 658 659以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 660 661| 错误码ID | 错误信息 | 662| -------- | --------------------------------------- | 663| 5400102 | Operation not allowed. Return by callback. | 664| 5400105 | Service died. Return by callback. | 665 666**示例：** 667 668```js 669let streamID: number; 670let selectedAudioRendererRate: audio.AudioRendererRate = audio.AudioRendererRate.RENDER_RATE_NORMAL; // 默认正常速率 671// 先调用play方法获取到对应资源的streamID 672 673soundPool.setRate(streamID, selectedAudioRendererRate, (error: BusinessError) => { 674 if (error) { 675 console.info(`setRate soundPool Error: errCode is ${error.code}, errMessage is ${error.message}`) 676 } else { 677 console.info('setRate success streamID:' + streamID); 678 } 679}) 680 681``` 682 683### setRate 684 685setRate(streamID: number, rate: audio.AudioRendererRate): Promise\<void> 686 687设置音频流的播放速率。使用Promise方式异步获取返回值。 688 689**系统能力：** SystemCapability.Multimedia.Media.SoundPool 690 691**参数：** 692 693| 参数名 | 类型 | 必填 | 说明 | 694| -------- | ---------------------- | ---- | --------------------------- | 695| streamID | number | 是 | 音频流ID，通过play方法获取。 | 696| rate | [audio.AudioRendererRate](js-apis-audio.md#audiorendererrate8) | 是 | 音频rate相关参数。 | 697 698**返回值：** 699 700| 类型 | 说明 | 701| ---------------- | -------------------------------- | 702| Promise\<void> | 异步音频池setRate方法的Promise返回值。 | 703 704**错误码：** 705 706以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 707 708| 错误码ID | 错误信息 | 709| -------- | --------------------------------------- | 710| 5400102 | Operation not allowed. Return by promise. | 711| 5400105 | Service died. Return by promise. | 712 713**示例：** 714 715```js 716let streamID: number; 717let selectedAudioRendererRate: audio.AudioRendererRate = audio.AudioRendererRate.RENDER_RATE_NORMAL; // 默认正常速率 718// 先调用play方法获取到对应资源的streamID 719 720soundPool.setRate(streamID, selectedAudioRendererRate).then(() => { 721 console.info('setRate success'); 722}).catch((err) => { 723 console.error('soundpool setRate failed and catch error is ' + err.message); 724}); 725``` 726 727### setVolume 728 729setVolume(streamID: number, leftVolume: number, rightVolume: number, callback: AsyncCallback\<void>): void 730 731设置音频流播放音量。使用callback方式异步获取返回值。 732 733**系统能力：** SystemCapability.Multimedia.Media.SoundPool 734 735**参数：** 736 737| 参数名 | 类型 | 必填 | 说明 | 738| -------- | ---------------------- | ---- | --------------------------- | 739| streamID | number | 是 | 音频流ID，通过play方法获取。 | 740| leftVolume | number | 是 | 左声道音量，设置范围为0.0-1.0之间。 | 741| rightVolume | number | 是 | 右声道音量，当前右声道设置无效，以左声道为准。 | 742| callback | AsyncCallback\<void> | 是 | 异步音频池setRate方法的回调方法。 | 743 744**错误码：** 745 746以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 747 748| 错误码ID | 错误信息 | 749| -------- | --------------------------------------- | 750| 5400102 | Operation not allowed. Return by callback. | 751| 5400105 | Service died. Return by callback. | 752 753**示例：** 754 755```js 756let streamID: number; 757// 先调用play方法获取到对应资源的streamID 758//设置音量为0.5 759soundPool.setVolume(streamID, 0.5, 0.5, (error: BusinessError) => { 760 if (error) { 761 console.info(`setVolume soundPool Error: errCode is ${error.code}, errMessage is ${error.message}`) 762 } else { 763 console.info('setVolume success streamID:' + streamID); 764 } 765}) 766 767``` 768 769### setVolume 770 771setVolume(streamID: number, leftVolume: number, rightVolume: number): Promise\<void> 772 773设置音频流的播放音量。使用Promise方式异步获取返回值。 774 775**系统能力：** SystemCapability.Multimedia.Media.SoundPool 776 777**参数：** 778 779| 参数名 | 类型 | 必填 | 说明 | 780| -------- | ---------------------- | ---- | --------------------------- | 781| streamID | number | 是 | 音频流ID，通过play方法获取。 | 782| leftVolume | number | 是 | 左声道音量，设置范围为0.0-1.0之间。 | 783| rightVolume | number | 是 | 右声道音量，当前右声道设置无效，以左声道为准。 | 784 785**返回值：** 786 787| 类型 | 说明 | 788| ---------------- | -------------------------------- | 789| Promise\<void> | 异步音频池setVolume方法的Promise返回值。 | 790 791**错误码：** 792 793以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 794 795| 错误码ID | 错误信息 | 796| -------- | --------------------------------------- | 797| 5400102 | Operation not allowed. Return by promise. | 798| 5400105 | Service died. Return by promise. | 799 800**示例：** 801 802```js 803let streamID: number; 804selectedAudioRendererRate: number = 0; // 默认正常速率 805// 先调用play方法获取到对应资源的streamID 806 807soundPool.setVolume(streamID, 0.5, 0.5).then(() => { 808 console.info('setVolume success'); 809}).catch((err) => { 810 console.error('soundpool setVolume failed and catch error is ' + err.message); 811}); 812``` 813 814### unload 815 816unload(soundID: number, callback: AsyncCallback\<void>): void 817 818卸载音频资源。使用callback方式异步获取返回值。 819 820**系统能力：** SystemCapability.Multimedia.Media.SoundPool 821 822**参数：** 823 824| 参数名 | 类型 | 必填 | 说明 | 825| -------- | ---------------------- | ---- | --------------------------- | 826| soundID | number | 是 | 资源ID，通过load方法获取。 | 827| callback | AsyncCallback\<void> | 是 | 异步音频池unload方法的回调方法。 | 828 829**错误码：** 830 831以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 832 833| 错误码ID | 错误信息 | 834| -------- | --------------------------------------- | 835| 5400102 | Operation not allowed. Return by callback. | 836| 5400103 | I/O error. Return by callback. | 837| 5400105 | Service died. Return by callback. | 838 839**示例：** 840 841```js 842let soundID: number; 843// 先调用load方法获取到对应资源的soundID 844soundPool.unload(soundID, (error: BusinessError) => { 845 if (error) { 846 console.info(`unload soundPool Error: errCode is ${error.code}, errMessage is ${error.message}`) 847 } else { 848 console.info('unload success:'); 849 } 850}) 851 852``` 853 854### unload 855 856unload(soundID: number): Promise\<void> 857 858卸载音频资源。使用Promise方式异步获取返回值。 859 860**系统能力：** SystemCapability.Multimedia.Media.SoundPool 861 862**参数：** 863 864| 参数名 | 类型 | 必填 | 说明 | 865| -------- | ---------------------- | ---- | --------------------------- | 866| soundID | number | 是 | 资源ID，通过load方法获取。 | 867 868**返回值：** 869 870| 类型 | 说明 | 871| ---------------- | -------------------------------- | 872| Promise\<void> | 异步音频池unload方法的Promise返回值。 | 873 874**错误码：** 875 876以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 877 878| 错误码ID | 错误信息 | 879| -------- | --------------------------------------- | 880| 5400102 | Operation not allowed. Return by promise. | 881| 5400103 | I/O error. Return by promise. | 882| 5400105 | Service died. Return by promise. | 883 884**示例：** 885 886```js 887let soundID: number; 888// 先调用load方法获取到对应资源的soundID 889 890soundPool.unload(soundID).then(() => { 891 console.info('unload success'); 892}).catch((err) => { 893 console.error('soundpool unload failed and catch error is ' + err.message); 894}); 895``` 896 897### release 898 899release(callback: AsyncCallback\<void>): void 900 901释放音频池实例。使用callback方式异步获取返回值。 902 903**系统能力：** SystemCapability.Multimedia.Media.SoundPool 904 905**参数：** 906 907| 参数名 | 类型 | 必填 | 说明 | 908| -------- | ---------------------- | ---- | --------------------------- | 909| callback | AsyncCallback\<void> | 是 | 异步音频池release方法的回调方法。 | 910 911**错误码：** 912 913以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 914 915| 错误码ID | 错误信息 | 916| -------- | --------------------------------------- | 917| 5400105 | Service died. Return by callback. | 918 919**示例：** 920 921```js 922 923soundPool.release((error: BusinessError) => { 924 if (error) { 925 console.info(`release soundPool Error: errCode is ${error.code}, errMessage is ${error.message}`) 926 } else { 927 console.info('release success'); 928 } 929}) 930 931``` 932 933### release 934 935release(): Promise\<void> 936 937释放音频池实例。使用Promise方式异步获取返回值。 938 939**系统能力：** SystemCapability.Multimedia.Media.SoundPool 940 941**返回值：** 942 943| 类型 | 说明 | 944| ---------------- | -------------------------------- | 945| Promise\<void> | 异步音频池release方法的Promise返回值。 | 946 947**错误码：** 948 949以下错误码的详细介绍请参见[媒体错误码](../errorcodes/errorcode-media.md)。 950 951| 错误码ID | 错误信息 | 952| -------- | --------------------------------------- | 953| 5400105 | Service died. Return by promise. | 954 955**示例：** 956 957```js 958 959soundPool.release().then(() => { 960 console.info('release success'); 961}).catch((err) => { 962 console.error('soundpool release failed and catch error is ' + err.message); 963}); 964``` 965 966### on('loadComplete') 967 968on(type: 'loadComplete', callback: Callback\<number>): void 969 970音频池资源加载完成监听。 971 972**系统能力：** SystemCapability.Multimedia.Media.SoundPool 973 974**参数：** 975 976| 参数名 | 类型 | 必填 | 说明 | 977| -------- | -------- | ---- | ------------------------------------------------------------ | 978| type | string | 是 | 支持的事件：'loadComplete'，对应的ID加载完成会触发此回调。 | 979| callback | Callback\<number> | 是 | 对应资源加载完成的资源ID。 | 980 981**示例：** 982 983```js 984soundPool.on('loadComplete', (soundId: number) => { 985 console.info('loadComplete success，soundId：' + soundId) 986}) 987``` 988 989### off('loadComplete') 990 991off(type: 'loadComplete'): void 992 993取消监听资源的加载完成。 994 995**系统能力：** SystemCapability.Multimedia.Media.SoundPool 996 997**参数：** 998 999| 参数名 | 类型 | 必填 | 说明 | 1000| ------ | ------ | ---- | ------------------------------------------------------------ | 1001| type | string | 是 | 取消注册的事件：'loadComplete'。 | 1002 1003**示例：** 1004 1005```js 1006soundPool.off('loadComplete') 1007``` 1008 1009### on('playFinished') 1010 1011on(type: 'playFinished', callback: Callback\<void>): void 1012 1013音频池资源播放完成监听。 1014 1015**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1016 1017**参数：** 1018 1019| 参数名 | 类型 | 必填 | 说明 | 1020| -------- | -------- | ---- | ------------------------------------------------------------ | 1021| type | string | 是 | 支持的事件：'playFinished'，音频流播放完成会触发此回调。 | 1022| callback | Callback\<void> | 是 | 异步'playFinished'的回调方法。 | 1023 1024**示例：** 1025 1026```js 1027soundPool.on('playFinished', () => { 1028 console.info('playFinished success') 1029}) 1030``` 1031 1032### off('playFinished') 1033 1034off(type: 'playFinished'): void 1035 1036取消监听音频池资源播放完成。 1037 1038**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1039 1040**参数：** 1041 1042| 参数名 | 类型 | 必填 | 说明 | 1043| ------ | ------ | ---- | ------------------------------------------------------------ | 1044| type | string | 是 | 取消注册的事件：'playFinished'。 | 1045 1046**示例：** 1047 1048```js 1049soundPool.off('playFinished') 1050``` 1051 1052### on('error') 1053 1054on(type: 'error', callback: ErrorCallback): void 1055 1056监听[SoundPool](#soundpool)的错误事件，该事件仅用于错误提示。 1057 1058**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1059 1060**参数：** 1061 1062| 参数名 | 类型 | 必填 | 说明 | 1063| -------- | -------- | ---- | ------------------------------------------------------------ | 1064| type | string | 是 | 错误事件回调类型，支持的事件：'error'，用户操作和系统都会触发此事件。 | 1065| callback | function | 是 | 错误事件回调方法：使用播放器的过程中发生错误，会提供错误码ID和错误信息。 | 1066 1067SoundPool回调的**错误分类**<a name = error_info></a>可以分为以下几种： 1068 1069| 错误码ID | 错误信息 | 说明 | 1070| -------- | --------------------- | ------------------------------------------------------------ | 1071| 401 | Invalid Parameter: | 入参错误，表示调用无效。 | 1072| 801 | Unsupport Capability: | 不支持该API能力，表示调用无效。 | 1073| 5400101 | No Memory: | 内存不足。 | 1074| 5400102 | Operation Not Allowed: | 当前状态机不支持此操作，表示调用无效。 | 1075| 5400103 | IO Error: | I/O异常。 | 1076| 5400105 | Service Died: | 播放进程死亡，音频池依赖的service端发生异常。| 1077 1078**示例：** 1079 1080```js 1081soundPool.on('error', (error: BusinessError) => { 1082 console.error('error happened,and error message is :' + error.message) 1083 console.error('error happened,and error code is :' + error.code) 1084}) 1085``` 1086 1087### off('error') 1088 1089off(type: 'error'): void 1090 1091取消监听音频池的错误事件。 1092 1093**系统能力：** SystemCapability.Multimedia.Media.SoundPool 1094 1095**参数：** 1096 1097| 参数名 | 类型 | 必填 | 说明 | 1098| ------ | ------ | ---- | ----------------------------------------- | 1099| type | string | 是 | 错误事件回调类型，取消注册的事件：'error'。 | 1100 1101**示例：** 1102 1103```js 1104soundPool.off('error') 1105```