管理器

介绍#

mk.audio 是框架的音频管理器，支持音频多分组管理，动态加载，最大播放数量控制优化，音频播放间隔控制

前置知识#

同时最大播放数量#

引擎存在同时最大播放数量限制（AudioSource.maxAudioChannel），所以框架对其增加强制播放配置， 当调用 play 接口时，强制播放的值为 config_.isForce，如果未传递则默认值为 GlobalConfig.Audio.isForce

  • 强制播放为 true 时: 当前播放的音频单元中找到停止优先级（stopPriorityNum）最高的音频，优先级相同则选择最先播放的音频， 然后停止这个音频，播放当前音频

  • 强制播放为 false 时: 阻止当前音频播放

属性#

audioIntervalMsLimitTab#

音频间隔限制表，用于限制同一音频资源在指定间隔内不能再次播放

  • key: AudioClip 资源的 uuid
  • value: 限制间隔时间（毫秒）

用例#

mk.audio.audioIntervalMsLimitTab['AudioClip资源的uuid'] = 1000;

// music 为 mk.Audio_.Unit 类型
mk.audio.audioIntervalMsLimitTab[music.clip!.uuid] = 1000;

groupMap#

groupMap 是包含了所有音频分组（包含音频类型和自定义的分组）的只读 Map，类型为 ReadonlyMap<number, Audio_.Group>

方法#

add#

add 是动态加载音频单元的接口，可以加载文件夹/单个资源

// 加载 db://resources/test.mp3
mk.audio.add('test.mp3', this, {
    type: GlobalConfig.Audio.Type.Music,
    loadConfig: {
        bundleStr: 'resources',
    },
    isDir: false,
    groupIdNumList: [],
});

参数#

add(url_, target_, config_)

  • url_: 资源路径，和 mk.asset.get 类型一致

  • target_: 资源跟随释放对象

  • config_: 配置数据

  • config_.type: 音频类型，枚举定义在 GlobalConfig.Audio.Type

  • config_.groupIdNumList: 音频分组 ID 列表

  • config_.loadConfig: 资源加载配置

  • config_.isDir: 是否是文件夹

play#

播放或者恢复暂停的音频单元

如果传递音频资源路径则代表动态加载后播放，动态加载的音频资源将跟随场景切换释放， 或者手动调用 find("音频跟随释放节点")?.destroy() 来进行释放

返回值（异步）：

  • null：播放失败
  • 音频单元：播放成功
mk.audio.play(this.music, {
    isLoop: false,
    volumeNum: 0.5,
});

mk.audio.play('db://assets/resources/xxx.mp3');

参数#

play(audio_, config_)

  • audio_: 音频单元或者音频资源路径

  • config_: 可选，播放配置

  • config_.isLoop: 设置音频单元是否循环（包括之后）

  • config_.volumeNum: 设置音频单元的音量（包括之后）

  • config_.isForce: 是否在超出最大播放数量时强制播放

如果 audio_ 是资源路径，则默认为音频类型为音效

pauseAll#

暂停当前所有音频，但不包括之后播放的音频

resumeAll#

恢复当前暂停的所有音频

stopAll#

停止当前的所有音频

参数#

stopAll(isPreventPlay_)

  • isPreventPlay_: 可选，是否阻止后续音频播放；默认值 false

    如果为 true，则后续可以通过执行音频类型分组的 stop(false) 来恢复对应分组的播放能力

例如

mk.audio.getGroup(GlobalConfig.Audio.Type.Music).stop(false);

getGroup#

获取音频组对象，如果不存在则创建