sys.soundPool

游戏音效池：程序启动时载入音效，之后一句 play(名字) 播放，多个声音可以同时响。

• 基于系统自带的 XAudio2（Windows 8 以上），混音在系统的音频线程里完成。play 只是提交请求（约 0.03 毫秒，首次创建声道约 0.4 毫秒），声音延迟约 10 毫秒，在界面线程里直接调用即可，不需要创建线程。
• 创建音效池会打开音频设备（约 80 毫秒），程序启动时创建一个即可。
• 没有声卡或系统不支持时是静音模式：对象照常创建，play 返回 null，程序不必判断。原因见 lastError。
• 声音数据常驻内存，适合音效和不太长的背景音乐（3 分钟 48kHz 立体声约 34MB）。长音乐边解码边播放可以用 sys.mediaFoundation.streamingMp3Player。
• 所有方法在创建对象的线程里调用，对象不要传给其他线程。

快速开始

import sys.soundPool;

var sounds = sys.soundPool();
sounds.add("ding","C:\Windows\Media\Windows Ding.wav");
sounds.add("coin","/res/coin.wav"); //支持资源路径
sounds.add("bgm","/res/music.mp3",0.5); //参数 3 是这个声音的基础音量

sounds.play("coin");
sounds.play("coin",0.5,1.2); //音量 0.5，音高 1.2 倍
var bgm = sounds.loop("bgm"); //循环播放，直到 stop
sounds.stop(bgm);

声音来源

add(名字,来源,音量) 的来源可以是：

• WAV 文件路径或 WAV 数据：支持 8/16/24/32 位整数 PCM 与 32 位浮点，按原格式播放，不转换。支持发布后的内嵌资源路径。
• MP3、M4A、WMA 等文件路径：用系统 Media Foundation 一次解码为 16 位 PCM，必须是硬盘文件。
• PCM 表：{pcm=buffer;sampleRate=48000;channels=2;bitsPerSample=16}，浮点数据加 float=true。
• 提供 pcm16 方法与 sampleRate 字段的声音对象，例如 av.audio 生成的音效，不需要素材文件：

import av.audio.sfx;
sounds.add("done",av.audio.sfx("success").trim(-60)); //trim 去掉混响尾部的静音
sounds.add("pop",av.audio.sfx("pop"));

同名重复添加会替换原来的声音。add 成功返回时长（秒），失败返回 null,错误信息。

播放控制

• play(名字,音量,音高) 返回播放编号。同一个声音可以重叠播放。音量与 add 的基础音量相乘。音高范围 0.01~4，同时改变速度。
• 重复的音效（脚步、射击、金币）每次把音高在 1 附近随机取值，听起来不单调：sounds.play("coin",1,0.95 + math.random() * 0.1)。
• loop(名字,音量,音高) 循环播放，直到 stop。
• stop(编号) 停止一次播放，stop(名字) 停止这个声音的所有播放，stop() 停止全部。
• isPlaying(编号或名字) 查询是否在播放。
• setVolume(音量) 设置总音量，影响正在播放和之后的所有声音，设为 0 即静音。

每种音频格式最多同时播放 32 个声音（sys.soundPool({maxVoices=64}) 可以改），超出时打断最早开始的声音，循环播放的声音不会被打断。

关闭

close() 停止所有声音、关闭音频设备并释放声音数据。对象被回收或线程结束时也会自动关闭，一般不必手动调用。

Markdown 格式