We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Only Essential Cookies
Accept All

SoundPool (音频池)

音频池提供了短音频的加载、播放、音量设置、循环设置、停止播放、资源卸载等功能。

SoundPool需要和@ohos.multimedia.media配合使用,需要先通过media.createSoundPool完成音频池实例的创建。

NOTE

本模块首批接口从API version 10开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

导入模块

import { media } from '@kit.MediaKit';
import { audio } from '@kit.AudioKit';

PlayParameters

表示音频池播放参数设置。

通过设置播放相关参数,来控制播放的音量,循环次数,播放优先级等参数。

系统能力: SystemCapability.Multimedia.Media.SoundPool

名称 类型 必填 说明
loop number 设置循环参数,0为循环一次,-1表示一直循环。默认值:0。
rate number 设置音频播放的倍速,具体倍速范围参照AudioRendererRate。默认值:0。
leftVolume number 设置左声道音量,设置范围(0.0~1.0)。默认值:1.0。
rightVolume number 设置右声道音量。(当前不支持左右分别设置,将以左声道音量为准)。默认值:1.0。
priority number 音频流播放的优先级,0为最低优先级,数值越大优先级越高,通过相互比较大小确定播放优先级。默认值:0。

SoundPool

音频池提供了系统声音的加载、播放、音量设置、循环设置、停止播放、资源卸载等功能, 在调用SoundPool的接口前,需要先通过createSoundPool创建实例。

NOTE

在使用SoundPool实例的方法时,建议开发者注册相关回调,主动获取当前状态变化。

load

load(uri: string, callback: AsyncCallback<number>): void

加载音频资源。使用callback方式异步获取资源ID,入参uri通过获取文件fd生成以"fd://"开头的文件描述字符串。

该方法不支持加载rawfile目录资源,需要通过load(fd: number, offset: number, length: number, callback: AsyncCallback<number>): void或者load(fd: number, offset: number, length: number): Promise<number>实现。

NOTE

将资源句柄(fd)或加载路径描述(uri)传递给音频池播放器之后,请不要通过该资源句柄或加载路径描述做其他读写操作,包括但不限于将同一个资源句柄或加载路径描述传递给多个音频池播放器。

同一时间通过同一个资源句柄或加载路径描述读写文件时存在竞争关系,将导致播放异常。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
uri string 音频文件的加载路径描述,一般以"fd://"开头的文件描述。
callback AsyncCallback<number> 异步音频资源加载返回的资源id,有效值大于0。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
5400102 Operation not allowed. Return by callback.
5400103 I/O error. Return by callback.
5400105 Service died. Return by callback.

示例:

import { fileIo } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let uri:string = "";
    let file: fileIo.File;
    //获取fd的uri路径
    fileIo.open('/test_01.mp3', fileIo.OpenMode.READ_ONLY).then((file_: fileIo.File) => {
      file = file_;
      console.info("file fd: " + file.fd);
      uri = 'fd://' + (file.fd).toString()
      soundPool.load(uri, (error: BusinessError, soundId_: number) => {
        if (error) {
          console.error(`Failed to load soundPool: errCode is ${error.code}, errMessage is ${error.message}`)
        } else {
          console.info(`Succeeded in loading soundPool` + JSON.stringify(soundId_))
        }
      });
    }); // '/test_01.mp3' 作为样例,使用时需要传入文件对应路径。
  }
});

load

load(uri: string): Promise<number>

加载音频资源。使用Promise方式异步获取资源ID,入参uri通过获取文件fd生成以"fd://"开头的文件描述字符串。

该方法不支持加载rawfile目录资源,需要通过load(fd: number, offset: number, length: number, callback: AsyncCallback<number>): void或者load(fd: number, offset: number, length: number): Promise<number>实现。

NOTE

将资源句柄(fd)或加载路径描述(uri)传递给音频池播放器之后,请不要通过该资源句柄或加载路径描述做其他读写操作,包括但不限于将同一个资源句柄或加载路径描述传递给多个音频池播放器。

同一时间通过同一个资源句柄或加载路径描述读写文件时存在竞争关系,将导致播放异常。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
uri string 音频文件的加载路径描述,一般以"fd://"开头的文件描述。

返回值:

类型 说明
Promise<number> 以Promise方式异步加载音频池资源,返回资源的id,有效值大于0。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
5400102 Operation not allowed. Return by promise.
5400103 I/O error. Return by promise.
5400105 Service died. Return by promise.

示例:

import { fileIo } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let uri:string = "";
    let soundID: number = 0;
    let file: fileIo.File;
    //获取fd的uri路径
    fileIo.open('/test_01.mp3', fileIo.OpenMode.READ_ONLY).then((file_: fileIo.File) => {
      file = file_;
      console.info("file fd: " + file.fd);
      uri = 'fd://' + (file.fd).toString()
      soundPool.load(uri).then((soundId: number) => {
        console.info('Succeeded in loading uri');
        soundID = soundId;
      }, (err: BusinessError) => {
        console.error('Failed to load soundPool and catch error is ' + err.message);
      });
    }); // '/test_01.mp3' 作为样例,使用时需要传入文件对应路径。
  }
});

load

load(fd: number, offset: number, length: number, callback: AsyncCallback<number>): void

加载音频资源。使用callback方式异步获取资源ID,入参可手动传入资源信息或通过读取应用内置资源自动获取。

NOTE

将资源句柄(fd)或加载路径描述(uri)传递给音频池播放器之后,请不要通过该资源句柄或加载路径描述做其他读写操作,包括但不限于将同一个资源句柄或加载路径描述传递给多个音频池播放器。

同一时间通过同一个资源句柄或加载路径描述读写文件时存在竞争关系,将导致播放异常。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
fd number 资源句柄,通过resourceManager.getRawFd获取。
offset number 资源偏移量,需要基于预置资源的信息输入,非法值会造成音视频资源解析错误。
length number 资源长度,需要基于预置资源的信息输入,非法值会造成音视频资源解析错误。
callback AsyncCallback<number> 获取回调的soundID,有效值大于0。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
5400102 Operation not allowed. Return by callback.
5400103 I/O error. Return by callback.
5400105 Service died. Return by callback.

示例1:

import { fileIo } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let file: fileIo.File;
    let soundID: number = 0;
    let fileSize: number = 1; //通过fileIo.stat()获取size值
    let uri: string = "";
    //获取fd的描述信息,test_01.mp3不是rawfile目录资源下面的音频
    fileIo.open('/test_01.mp3', fileIo.OpenMode.READ_ONLY).then((file_: fileIo.File) => {
      file = file_;
      console.info("file fd: " + file.fd);
      uri = 'fd://' + (file.fd).toString()
      soundPool.load(file.fd, 0, fileSize, (error: BusinessError, soundId_: number) => {
        if (error) {
          console.error(`Failed to load soundPool: errCode is ${error.code}, errMessage is ${error.message}`)
        } else {
          soundID = soundId_;
          console.info('Succeeded in loading soundId:' + soundId_);
        }
      });
    }); // '/test_01.mp3' 作为样例,使用时需要传入文件对应路径。
  }
});

示例2:

import { media } from '@kit.MediaKit';
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
let soundID: number = 0;
media.createSoundPool(5, audioRendererInfo, async (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    //test_01.mp3为rawfile目录资源下面的音频
    let fileDescriptor = await getContext().resourceManager.getRawFd('test_01.mp3');
    soundPool.load(fileDescriptor.fd, fileDescriptor.offset, fileDescriptor.length, (error: BusinessError, soundId_: number) => {
      if (error) {
        console.error(`Failed to load soundPool: errCode is ${error.code}, errMessage is ${error.message}`)
      } else {
        soundID = soundId_;
        console.info('Succeeded in loading soundId:' + soundId_);
      }
    });
  }
});

load

load(fd: number, offset: number, length: number): Promise<number>

加载音频资源。使用Promise方式异步获取资源ID,入参可手动传入资源信息或通过读取应用内置资源自动获取。

NOTE

将资源句柄(fd)或加载路径描述(uri)传递给音频池播放器之后,请不要通过该资源句柄或加载路径描述做其他读写操作,包括但不限于将同一个资源句柄或加载路径描述传递给多个音频池播放器。

同一时间通过同一个资源句柄或加载路径描述读写文件时存在竞争关系,将导致播放异常。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
fd number 资源句柄,通过过resourceManager.getRawFd获取。
offset number 资源偏移量,需要基于预置资源的信息输入,非法值会造成音视频资源解析错误。
length number 资源长度,需要基于预置资源的信息输入,非法值会造成音视频资源解析错误。

返回值:

类型 说明
Promise<number> 以Promise方式获取返回的soundID,有效值大于0。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
5400102 Operation not allowed. Return by promise.
5400103 I/O error. Return by promise.
5400105 Service died. Return by promise.

示例1:

import { fileIo } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let file: fileIo.File;
    let soundID: number = 0;
    let fileSize: number = 1; //通过fileIo.stat()获取size值
    let uri: string = "";
    //获取fd的描述信息,test_01.mp3不是rawfile目录资源下面的音频
    fileIo.open('/test_01.mp3', fileIo.OpenMode.READ_ONLY).then((file_: fileIo.File) => {
      file = file_;
      console.info("file fd: " + file.fd);
      uri = 'fd://' + (file.fd).toString()
      soundPool.load(file.fd, 0, fileSize).then((soundId: number) => {
        console.info('Succeeded in loading soundpool');
        soundID = soundId;
      }, (err: BusinessError) => {
        console.error('Failed to load soundpool and catch error is ' + err.message);
      });
    });
  }
});

示例2:

import { media } from '@kit.MediaKit';
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
let soundID: number = 0;
media.createSoundPool(5, audioRendererInfo, async (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    //test_01.mp3为rawfile目录资源下面的音频
    let fileDescriptor = await getContext().resourceManager.getRawFd('test_01.mp3');
    soundPool.load(fileDescriptor.fd, fileDescriptor.offset, fileDescriptor.length).then((soundId: number) => {
      console.info('Succeeded in loading soundpool');
      soundID = soundId;
    }, (err: BusinessError) => {
      console.error('Failed to load soundpool and catch error is ' + err.message);
    });
  }
});

play

play(soundID: number, params: PlayParameters, callback: AsyncCallback<number>): void

播放音频资源。使用callback方式异步获取音频流streamID。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
soundID number 资源ID,通过load方法获取。
params PlayParameters play播放相关参数的设置。
callback AsyncCallback<number> 获取回调的音频流ID,有效值大于0。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by callback.
5400102 Operation not allowed. Return by callback.
5400105 Service died. Return by callback.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let soundID: number = 0;
    let streamID: number = 0;
    let playParameters: media.PlayParameters = {
      loop: 3, // 循环3次
      rate: audio.AudioRendererRate.RENDER_RATE_NORMAL, // 正常倍速
      leftVolume: 0.5, // range = 0.0-1.0
      rightVolume: 0.5, // range = 0.0-1.0
      priority: 0, // 最低优先级
    }
    soundPool.play(soundID, playParameters, (error: BusinessError, streamId: number) => {
      if (error) {
        console.error(`Failed to play soundpool: errCode is ${error.code}, errMessage is ${error.message}`)
      } else {
        streamID = streamId;
        console.info('Succeeded in playing soundpool, streamId:' + streamId);
      }
    });
  }
});

play

play(soundID: number, callback: AsyncCallback<number>): void

播放音频资源。使用callback方式异步获取音频流streamID。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
soundID number 资源ID,通过load方法获取。
callback AsyncCallback<number> 获取回调的音频流ID,有效值大于0。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by callback.
5400102 Operation not allowed. Return by callback.
5400105 Service died. Return by callback.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let soundID: number = 0;
    let streamID: number = 0;
    soundPool.play(soundID,  (error: BusinessError, streamId: number) => {
      if (error) {
        console.error(`Failed to play soundpool: errCode is ${error.code}, errMessage is ${error.message}`)
      } else {
        streamID = streamId;
        console.info('Succeeded in playing soundpool, streamId:' + streamId);
      }
    });
  }
});

play

play(soundID: number, params?: PlayParameters): Promise<number>

播放音频资源。使用Promise方式异步获取音频流streamID。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
soundID number 资源ID,通过load方法获取。
params PlayParameters play播放相关参数的设置。

返回值:

类型 说明
Promise<number> 以Promise方式获取返回的音频流ID,有效值大于0。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise.
5400102 Operation not allowed. Return by promise.
5400105 Service died. Return by promise.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let soundID: number = 0;
    let streamID: number = 0;
    let playParameters: media.PlayParameters = {
      loop: 3, // 循环4次
      rate: audio.AudioRendererRate.RENDER_RATE_NORMAL, // 正常倍速
      leftVolume: 0.5, // range = 0.0-1.0
      rightVolume: 0.5, // range = 0.0-1.0
      priority: 0, // 最低优先级
    }

    soundPool.play(soundID, playParameters).then((streamId: number) => {
      console.info('Succeeded in playing soundpool');
      streamID = streamId;
    },(err: BusinessError) => {
      console.error('Failed to play soundpool and catch error is ' + err.message);
    });
  }
});

stop

stop(streamID: number, callback: AsyncCallback<void>): void

停止播放音频资源。使用callback方式异步获取返回值。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
streamID number 音频流ID,通过play方法获取。
callback AsyncCallback<void> 异步音频池stop的回调方法。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by callback.
5400102 Operation not allowed. Return by callback.
5400105 Service died. Return by callback.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let streamID: number = 0;
    //先调用play方法给拿到对应的streamID
    soundPool.stop(streamID, (error: BusinessError) => {
      if (error) {
        console.error(`Failed to stop soundpool: errCode is ${error.code}, errMessage is ${error.message}`)
      } else {
        console.info('Succeeded in stopping soundpool');
      }
    })
  }
});

stop

stop(streamID: number): Promise<void>

停止streamID对应的音频播放。使用Promise方式异步获取返回值。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
streamID number 音频流ID,通过play方法获取。

返回值:

类型 说明
Promise<void> 以Promise方式返回,无返回值。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise.
5400102 Operation not allowed. Return by promise.
5400105 Service died. Return by promise.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let streamID: number = 0;
    //先调用play方法给拿到对应的streamID
    soundPool.stop(streamID).then(() => {
      console.info('Succeeded in stopping soundpool');
    }, (err: BusinessError) => {
      console.error('Failed to stop soundpool and catch error is ' + err.message);
    });
  }
});

setLoop

setLoop(streamID: number, loop: number, callback: AsyncCallback<void>): void;

设置循环模式。使用callback方式异步获取返回值。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
streamID number 音频流ID,通过play方法获取。
loop number 设置循环的次数,0为默认1次,-1为一直循环。
callback AsyncCallback<void> 异步setLoop的回调方法。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by callback.
5400102 Operation not allowed. Return by callback.
5400105 Service died. Return by callback.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let streamID: number = 0;
    //先通过调用play方法获取到对应的streamID
    //设置循环2次
    soundPool.setLoop(streamID, 2, (error: BusinessError) => {
      if (error) {
        console.error(`Failed to setLoop soundPool: errCode is ${error.code}, errMessage is ${error.message}`)
      } else {
        console.info('Succeeded in setLoopping soundpool, streamID:' + streamID);
      }
    });
  }
});

setLoop

setLoop(streamID: number, loop: number): Promise<void>

设置循环模式。使用Promise方式异步获取返回值。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
streamID number 音频流ID,通过play方法获取。
loop number 设置循环的次数,0为默认1次,-1为一直循环。

返回值:

类型 说明
Promise<void> 异步音频池setLoop方法的Promise返回值。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise.
5400102 Operation not allowed. Return by promise.
5400105 Service died. Return by promise.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let streamID: number = 0;
    //先通过调用play方法获取到对应的streamID
    //设置循环1次
    soundPool.setLoop(streamID, 1).then(() => {
      console.info('Succeeded in setLoopping soundpool, streamID:' + streamID);
    }).catch((err: BusinessError) => {
      console.error('Failed to setLoop soundPool and catch error is ' + err.message);
    });
  }
});

setPriority

setPriority(streamID: number, priority: number, callback: AsyncCallback<void>): void

设置音频流播放的优先级。使用callback方式异步获取返回值。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
streamID number 音频流ID,通过play方法获取。
priority number 优先级,0表示最低优先级。
callback AsyncCallback<void> 异步音频池setPriority方法的回调方法。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by callback.
5400102 Operation not allowed. Return by callback.
5400105 Service died. Return by callback.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let streamID: number = 0;
    // 先调用play方法获取到对应资源的streamID
    // 给对应的streamID资源设置优先级为1
    soundPool.setPriority(streamID, 1, (error: BusinessError) => {
      if (error) {
        console.error(`Failed to setPriority soundPool: errCode is ${error.code}, errMessage is ${error.message}`)
      } else {
        console.info('Succeeded in setPriority soundpool, streamID:' + streamID);
      }
    });
  }
});

setPriority

setPriority(streamID: number, priority: number): Promise<void>

设置音频流优先级。使用Promise方式异步获取返回值。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
streamID number 音频流ID,通过play方法获取。
priority number 优先级,0表示最低优先级。

返回值:

类型 说明
Promise<void> 异步音频池setPriority的Promise返回值。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise.
5400102 Operation not allowed. Return by promise.
5400105 Service died. Return by promise.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let streamID: number = 0;
    // 先调用play方法获取到对应资源的streamID
    // 给对应的streamID资源设置优先级为1

    soundPool.setPriority(streamID, 1).then(() => {
      console.info('Succeeded in setPriority soundpool');
    }, (err: BusinessError) => {
      console.error('Failed to setPriority soundPool and catch error is ' + err.message);
    });
  }
});

setRate

setRate(streamID: number, rate: audio.AudioRendererRate, callback: AsyncCallback<void>): void

设置音频流播放速率。使用callback方式异步获取返回值。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
streamID number 音频流ID,通过play方法获取。
rate audio.AudioRendererRate 音频rate相关参数。
callback AsyncCallback<void> 异步音频池setRate方法的回调方法。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by callback.
5400102 Operation not allowed. Return by callback.
5400105 Service died. Return by callback.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let streamID: number = 0;
    let selectedAudioRendererRate: audio.AudioRendererRate = audio.AudioRendererRate.RENDER_RATE_NORMAL; // 默认正常速率
    // 先调用play方法获取到对应资源的streamID
    soundPool.setRate(streamID, selectedAudioRendererRate, (error: BusinessError) => {
      if (error) {
        console.error(`Failed to setRate soundPool: errCode is ${error.code}, errMessage is ${error.message}`)
      } else {
        console.info('Succeeded in setRate success, streamID:' + streamID);
      }
    })
  }
});

setRate

setRate(streamID: number, rate: audio.AudioRendererRate): Promise<void>

设置音频流的播放速率。使用Promise方式异步获取返回值。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
streamID number 音频流ID,通过play方法获取。
rate audio.AudioRendererRate 音频rate相关参数。

返回值:

类型 说明
Promise<void> 异步音频池setRate方法的Promise返回值。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise.
5400102 Operation not allowed. Return by promise.
5400105 Service died. Return by promise.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let streamID: number = 0;
    let selectedAudioRendererRate: audio.AudioRendererRate = audio.AudioRendererRate.RENDER_RATE_NORMAL; // 默认正常速率
    // 先调用play方法获取到对应资源的streamID
    soundPool.setRate(streamID, selectedAudioRendererRate).then(() => {
      console.info('Succeeded in setRate soundpool');
    }, (err: BusinessError) => {
      console.error('Failed to setRate soundpool and catch error is ' + err.message);
    });
  }
});

setVolume

setVolume(streamID: number, leftVolume: number, rightVolume: number, callback: AsyncCallback<void>): void

设置音频流播放音量。使用callback方式异步获取返回值。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
streamID number 音频流ID,通过play方法获取。
leftVolume number 左声道音量,设置范围为0.0-1.0之间。
rightVolume number 右声道音量,当前右声道设置无效,以左声道为准。
callback AsyncCallback<void> 异步音频池setVolume方法的回调方法。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by callback.
5400102 Operation not allowed. Return by callback.
5400105 Service died. Return by callback.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let streamID: number = 0;
    // 先调用play方法获取到对应资源的streamID
    //设置音量为0.5
    soundPool.setVolume(streamID, 0.5, 0.5, (error: BusinessError) => {
      if (error) {
        console.error(`Failed to setVolume soundPool: errCode is ${error.code}, errMessage is ${error.message}`)
      } else {
        console.info('Succeeded in setVolume soundpool, streamID:' + streamID);
      }
    })
  }
});

setVolume

setVolume(streamID: number, leftVolume: number, rightVolume: number): Promise<void>

设置音频流的播放音量。使用Promise方式异步获取返回值。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
streamID number 音频流ID,通过play方法获取。
leftVolume number 左声道音量,设置范围为0.0-1.0之间。
rightVolume number 右声道音量,当前右声道设置无效,以左声道为准。

返回值:

类型 说明
Promise<void> 异步音频池setVolume方法的Promise返回值。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
401 Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. Return by promise.
5400102 Operation not allowed. Return by promise.
5400105 Service died. Return by promise.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let streamID: number = 0;
    // 先调用play方法获取到对应资源的streamID

    soundPool.setVolume(streamID, 0.5, 0.5).then(() => {
      console.info('Succeeded in setVolume soundpool');
    }, (err: BusinessError) => {
      console.error('Failed to setVolume soundPool and catch error is ' + err.message);
    });
  }
});

unload

unload(soundID: number, callback: AsyncCallback<void>): void

卸载音频资源。使用callback方式异步获取返回值。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
soundID number 资源ID,通过load方法获取。
callback AsyncCallback<void> 异步音频池unload方法的回调方法。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
5400102 Operation not allowed. Return by callback.
5400103 I/O error. Return by callback.
5400105 Service died. Return by callback.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let soundID: number = 0;
    // 先调用load方法获取到对应资源的soundID
    soundPool.unload(soundID, (error: BusinessError) => {
      if (error) {
        console.error(`Failed to unload soundPool: errCode is ${error.code}, errMessage is ${error.message}`)
      } else {
        console.info('Succceeded in unload soundPool');
      }
    })
  }
});

unload

unload(soundID: number): Promise<void>

卸载音频资源。使用Promise方式异步获取返回值。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
soundID number 资源ID,通过load方法获取。

返回值:

类型 说明
Promise<void> 异步音频池unload方法的Promise返回值。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
5400102 Operation not allowed. Return by promise.
5400103 I/O error. Return by promise.
5400105 Service died. Return by promise.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    let soundID: number = 0;
    // 先调用load方法获取到对应资源的soundID

    soundPool.unload(soundID).then(() => {
      console.info('Succceeded in unload soundPool');
    }, (err: BusinessError) => {
      console.error('Failed to unload soundPool and catch error is ' + err.message);
    });
  }
});

release

release(callback: AsyncCallback<void>): void

释放音频池实例。使用callback方式异步获取返回值。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
callback AsyncCallback<void> 异步音频池release方法的回调方法。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
5400105 Service died. Return by callback.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    soundPool.release((error: BusinessError) => {
      if (error) {
        console.error(`Failed to release soundPool: errCode is ${error.code}, errMessage is ${error.message}`)
      } else {
        console.info('Succeeded in releasing soundPool');
      }
    })
  }
});

release

release(): Promise<void>

释放音频池实例。使用Promise方式异步获取返回值。

系统能力: SystemCapability.Multimedia.Media.SoundPool

返回值:

类型 说明
Promise<void> 异步音频池release方法的Promise返回值。

错误码:

以下错误码的详细介绍请参见媒体错误码

错误码ID 错误信息
5400105 Service died. Return by promise.

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    soundPool.release().then(() => {
      console.info('Succeeded in releasing soundPool');
    }, (err: BusinessError) => {
      console.error('Failed to release soundPool and catch error is ' + err.message);
    });
  }
});

on('loadComplete')

on(type: 'loadComplete', callback: Callback<number>): void

音频池资源加载完成监听。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
type string 支持的事件:'loadComplete',对应的ID加载完成会触发此回调。
callback Callback<number> 对应资源加载完成的资源ID。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    soundPool.on('loadComplete', (soundId: number) => {
      console.info('Succeeded in loadComplete, soundId:' + soundId)
    })
  }
});

off('loadComplete')

off(type: 'loadComplete'): void

取消监听资源的加载完成。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
type string 取消注册的事件:'loadComplete'。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    soundPool.off('loadComplete')
  }
});

on('playFinished')

on(type: 'playFinished', callback: Callback<void>): void

音频池资源播放完成监听。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
type string 支持的事件:'playFinished',音频流播放完成会触发此回调。
callback Callback<void> 异步'playFinished'的回调方法。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    soundPool.on('playFinished', () => {
      console.info('Succeeded in playFinished')
    });
  }
});

off('playFinished')

off(type: 'playFinished'): void

取消监听音频池资源播放完成。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
type string 取消注册的事件:'playFinished'。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    soundPool.off('playFinished')
  }
});

on('error')

on(type: 'error', callback: ErrorCallback): void

监听SoundPool的错误事件,该事件仅用于错误提示。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
type string 错误事件回调类型,支持的事件:'error',用户操作和系统都会触发此事件。
callback ErrorCallback 错误事件回调方法:使用播放器的过程中发生错误,会提供错误码ID和错误信息。

SoundPool回调的错误分类可以分为以下几种:

错误码ID 错误信息 说明
401 Invalid Parameter. 入参错误,表示调用无效。
801 Unsupport Capability. 不支持该API能力,表示调用无效。
5400101 No Memory. 内存不足。
5400102 Operation Not Allowed. 当前状态机不支持此操作,表示调用无效。
5400103 IO Error. I/O异常。
5400105 Service Died. 播放进程死亡,音频池依赖的service端发生异常。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    soundPool.on('error', (error: BusinessError) => {
      console.error('error happened,and error message is :' + error.message)
      console.error('error happened,and error code is :' + error.code)
    })
  }
});

off('error')

off(type: 'error'): void

取消监听音频池的错误事件。

系统能力: SystemCapability.Multimedia.Media.SoundPool

参数:

参数名 类型 必填 说明
type string 错误事件回调类型,取消注册的事件:'error'。

示例:

import { BusinessError } from '@kit.BasicServicesKit';

//创建soundPool实例
let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags: 1
}
media.createSoundPool(5, audioRendererInfo, (error: BusinessError, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`)
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`)
    soundPool.off('error')
  }
});
Search
Enter a keyword.