Buzz.js

Sound

WARNING

重要提示：为了节省带宽，移动设备在没有用户干预的情况下不会加载/播放声音(没有自动播放)。 iPhone 和 iPad 一次只能播放一种声音，不允许动态改变音量。

构造器

new buzz.sound( sources, [settings] )

创建一个新的 sound 实例。

var mySound = new buzz.sound("/sounds/mysound.ogg");
1

可以将多种声音文件的URI放入数组中：

var mySound = new buzz.sound([
    "/sounds/mysound.ogg",
    "/sounds/mysound.mp3",
    "/sounds/mysound.aac",
    "/sounds/mysound.wav"
]);
1
2
3
4
5
6

您可以用下面这种方式提升可读性。

var mySound = new buzz.sound("/sounds/mysound", {
    formats: [ "ogg", "mp3", "aac", "wav" ]
});
1
2
3

设置

var mySound = new buzz.sound("/sounds/mysound", {
    formats: [ "ogg", "mp3", "aac", "wav" ],
    preload: true,
    autoplay: true,
    loop: false
});
1
2
3
4
5
6
设置项 可选值 描述
preload metadata/true/false 若设置为布尔值，则指定页面在加载时是否预加载声音文件。若设置为metadata，则浏览器只会加载元数据，如持续时间等。
autoplay true/false 是否自动播放
loop true/false 是否循环播放，部分浏览器对它的支持性并不好，因此请不要过分期待完美的循环。
volume 0-100 设置默认音量，默认值：80
webAudioAPi true/false 如果可用的话，通过Web Audio API 进行路由以提高性能。默认值：false
crossOrigin true/false 默认值：false。当在 HTTPS 中加载另一个域名的音频文件时，Chrome 将不会加载文件，同时报错“MediaElementAudioSource outputs zeroes due to CORS access restrictions”。该配置 就是为解决这个问题而生。

注意：目标域名应当设置合适的Access-Control-Allow-Origin HTTP头。

方法

所有的方法都可以进行链式调用。

mySound.loop().play().fadeIn();
1

sound.load()

加载声音。

mySound.load();
1

播放

sound.play()

加载声音并开始播放。

mySound.play();
1

sound.pause()

暂停声音播放，声音再次播放时会从当前暂停位置开始播放。

mySound.pause();
1

sound.togglePlay()

自动暂停或播放声音。

mySound.togglePlay();
1

sound.isPaused()

返回当前声音是否是暂停状态。

if (mySound.isPaused()) {
    alert("声音已暂停!");
}
1
2
3

sound.stop()

停止播放声音。再次播放则从起始位置开始。

mySound.stop();
1

sound.isEnded()

返回当前声音播放是否已结束。

if (mySound.isEnded()) {
    alert("The sound has ended!");
}
1
2
3

sound.loop()

设置声音循环播放。

mySound.loop();
1

sound.unloop()

停止声音的循环播放。

mySound.unloop();
1

音量

sound.mute()

静音。

mySound.mute();
1
sound.unmute()

取消静音。

mySound.unmute();
1

sound.toggleMute()

切换静音与否状态。

mySound.toggleMute();
1

sound.isMuted()

返回当前声音文件是否是静音状态。

if (mySound.isMuted()) {
    alert("该声音已静音");
}
1
2
3

sound.setVolume(volume)

设置音量。范围0-100。

mySound.setVolume(90);
1
sound.getVolume();

获取当前音量。范围0-100。

var volume = mySound.getVolume();
1

sound.increaseVolume([volume])

根据传入的值提升音量，默认值为1。

mySound.increaseVolume(); // 当前音量 +1
1

sound.decreaseVolume( [volume] )

根据传入的值降低音量，默认值为1。

mySound.decreaseVolume(10); // 当前音量 -10
1

sound.fadeIn( [duration], [callback] )

在duration毫秒内将声音从0提升到100。结束之后调用传入的回调函数callback。

mySound.fadeIn(2000);
1

sound.fadeOut( [duration], [callback] )

在duration毫秒内将声音从当前音量降低到0。结束之后调用传入的回调函数callback

mySound.fadeOut(2000);
1

sound.fadeTo( volume, [duration], [callback] )

在duration毫秒内将声音从当前音量变为volume。结束之后调用传入的回调函数callback

// 在2秒内将音量从20提升到90而后再降低回20.
mySound.setVolume(20).fadeTo(90, 2000, function () {
    this.fadeTo(20, 2000);
});
1
2
3
4

sound.fadeWith( sound, [duration] )

在duration毫秒内逐渐降低当前声音的音量，而后切换到另一个声音并提升音量，形成切换效果。

var myOtherSound = new buzz.sound("/sounds/myothersound.ogg");
mySound.fadeWith(myOtherSound, 2000);
1
2

事件

sound.bind( event, callback )

对声音添加一个或多个事件监听器。更多细节请参见事件部分。

mySound.bind("ended pause", function () {
    var percent = buzz.toPercent(this.getTime(), this.getDuration()),
        message = "Stopped or paused at " + percent + "%";
    document.getElementById("percent").innerHTML = message;
});
1
2
3
4
5

事件可以设置命名空间，从而方便我们在解绑或触发某些事件时不影响其他事件。

mySound.bind("ended.one pause.one", function () {
    alert("Event type one");
}).bind("ended.two pause.two", function () {
    alert("Event type two");
});
1
2
3
4
5

sound.bindOnce( event, callback )

添加一个或多个事件侦听器，但只执行一次。详情请见事件部分。

mySound.bindOnce("pause", function () {
    alert("仅会在第一次暂停时执行");
});
1
2
3

sound.unbind( event )

解绑事件侦听器，可以按照命名空间解绑。

mySound.unbind("ended.one .two");
1

sound.trigger( event )

执行绑定到事件的句柄。需要注意的是只是触发了函数，而非原生事件。

mySound.trigger("ended.one");
1

访问器 (Getters and Setters)

sound.setTime( seconds )

设置播放位置，单位秒。

mySound.setTime(90);
1

辅助方法fromTimer这里可以派上大用场。

mySound.setTime(buzz.fromTimer("01:30"));
1

sound.getTime()

获取当前的播放位置，单位是秒.

var seconds = mySound.getTime(); // 90
1

辅助方法toTimer在这里可以派上用场。

var timer = buzz.toTimer(mySound.getTime()); // 01:30
1

sound.setPercent( percent )

设置percent百分比播放位置。

mySound.setPercent(50); // 50%
1

sound.getPercent()

获得百分比percent播放位置。

var percent = mySound.getPercent() + "%";
1

sound.getDuration()

获取声音的总时长，单位是秒。

var duration = mySound.getDuration() + " seconds";
1

辅助方法toTimer在这里可以派上用场。

var timer = buzz.toTimer(mySound.getDuration()); // 05:46
1

sound.setSpeed( speed )

设置播放速度，1为通常速度，2为双倍速度，依次类推。

mySound.setSpeed(2); // x2
1

sound.getSpeed( speed )

获取播放速度。

var speed = mySound.getSpeed();
1

sound.set( property, value )

直接在 HTML5 <audio>元素上设置原生属性。

mySound.set("volume", 0.5);
mySound.set("currentTime", 90);
1
2

sound.get()

直接获取HTML5 <audio>元素上的原生属性值。

时间范围

sound.getPlayed()

获取一个数组，其中的元素表示浏览器已经播放的声音范围。

var played = mySound.getPlayed();

for (var i in played) {
    console.log(played[i]);
}
1
2
3
4
5

sound.getBuffered()

获取一个数组，其中的元素表示浏览器已经缓冲的声音范围。

var buffered = mySound.getBuffered();

for (var i in buffered) {
    console.log(buffered[i]);
}
1
2
3
4
5

sound.getSeekable()

获取一个数组，其中的元素表示浏览器可能去搜寻的声音范围。

var seekable = mySound.getSeekable();

for (var i in seekable) {
    console.log(seekable[i]);
}
1
2
3
4
5

错误和状态

sound.getErrorCode(), sound.getErrorMessage()

返回当前错误的代码/错误信息

错误代码 错误信息 含义
1 MEDIA_ERR_ABORTED 在用户的请求下，用户中止了获取声音的过程。
2 MEDIA_ERR_NETWORK 在声音已经建立并准备使用后，出现网络错误让浏览器停止获取声音。
3 MEDIA_ERR_DECODE 在资源已经建立且可用后，解码声音时发生了错误
4 MEDIA_ERR_SRC_NOT_SUPPORTED 不支持src 链接
mySound.bind("error", function () {
    alert("Error: " + this.getErrorMessage());
});
1
2
3

sound.getStateCode(), sound.getStateMessage()

返回当前状态的代码/状态信息

状态码 状态信息 含义
0 HAVE_NOTHING 无可用信息。
1 HAVE_METADATA 已经获得了足够的声音来获得一些信息。
2 HAVE_CURRENT_DATA 当前播放位置的数据是可用的。
3 HAVE_FUTURE_DATA 当前播放位置的数据可用，并且进一步的数据也是可用的。
4 HAVE_ENOUGH_DATA 所有的信息都是可用的。

sound.getNetworkStateCode(), sound.getNetworkStateMessage()

返回当前网络状态代码/状态信息。

状态码 状态信息 含义
0 NETWORK_EMPTY 声音尚未初始化。
1 NETWORK_IDLE 声音已选择，不过它并未使用网络。
2 NETWORK_LOADING 浏览器正尝试下载数据。
3 NETWORK_NO_SOURCE 声音不可用。

← Group →