🎧用Howler.js后，我天天网页搓碟当DJ🎵

原文链接：https://github.com/goldfire/howler.js
作者：GoldFire Studios
译者：倔强青铜三

前言

大家好，我是倔强青铜三。是一名热情的软件工程师，我热衷于分享和传播IT技术，致力于通过我的知识和技能推动技术交流与创新，欢迎关注我，微信公众号：倔强青铜三。欢迎点赞、收藏、关注，一键三连！！！

现代网页音频库：Howler.js

howler.js 是一个现代网络音频库。它默认使用Web Audio API，回退到HTML5 Audio。这使得在JavaScript中处理音频变得简单且在所有平台上都可靠。

更多信息、实时演示和用户展示可在howlerjs.com找到。

特性

单一API满足所有音频需求
默认使用Web Audio API，回退到HTML5 Audio
处理跨环境的边缘情况和错误
支持所有编解码器，实现全浏览器支持
自动缓存，提高性能
单独、分组或全局控制声音
同时播放多个声音
简单的声音精灵定义和播放
完全控制淡入淡出、速率、寻址、音量等
轻松添加3D空间音效或立体声平移
模块化 - 按需使用，易于扩展
无外部依赖，纯JavaScript
体积轻巧，仅7kb gzip压缩

浏览器兼容性

在以下浏览器/版本中测试过：

Google Chrome 7.0+
Internet Explorer 9.0+
Firefox 4.0+
Safari 5.1.4+
移动Safari 6.0+（用户输入后）
Opera 12.0+
Microsoft Edge

实时演示

文档

快速开始

多种方式快速上手：

克隆仓库：git clone https://github.com/goldfire/howler.js.git
使用npm安装：npm install howler
使用Yarn安装：yarn add howler
使用Bower安装：bower install howler
托管CDN：cdnjs jsDelivr

在浏览器中：

<script src="/path/to/howler.js"></script>
<script>
    var sound = new Howl({
      src: ['sound.webm', 'sound.mp3']
    });
</script>

作为依赖项：

import {Howl, Howler} from 'howler';

const {Howl, Howler} = require('howler');

包含的分发文件：

howler：这是默认的完整捆绑源代码，包括howler.core和howler.spatial。它包括howler提供的所有功能。
howler.core：这只包括核心功能，旨在创建Web Audio和HTML5 Audio之间的一致性。它不包括任何空间/立体声音频功能。
howler.spatial：这是一个插件，添加了空间/立体声音频功能。它需要howler.core才能运行，因为它只是核心的附加功能。

示例

最基本的，播放MP3：

var sound = new Howl({
  src: ['sound.mp3']
});

sound.play();

流媒体音频（适用于现场音频或大文件）：

var sound = new Howl({
  src: ['stream.mp3'],
  html5: true
});

sound.play();

定义和播放声音精灵：

var sound = new Howl({
  src: ['sounds.webm', 'sounds.mp3'],
  sprite: {
    blast: [0, 3000],
    laser: [4000, 1000],
    winner: [6000, 5000]
  }
});

// 射击激光！
sound.play('laser');

监听事件：

var sound = new Howl({
  src: ['sound.webm', 'sound.mp3']
});

// 首次调用后清除监听器。
sound.once('load', function(){
  sound.play();
});

// 声音播放结束时触发。
sound.on('end', function(){
  console.log('Finished!');
});

控制多个声音：

var sound = new Howl({
  src: ['sound.webm', 'sound.mp3']
});

// 播放返回唯一声音ID，可以用于Howl上的任何方法来控制特定声音。
var id1 = sound.play();
var id2 = sound.play();

// 淡出第一个声音，加速第二个声音。
sound.fade(1, 0, 1000, id1);
sound.rate(1.5, id2);

ES6：

import {Howl, Howler} from 'howler';

// 设置新的Howl。
const sound = new Howl({
  src: ['sound.webm', 'sound.mp3']
});

// 播放声音。
sound.play();

// 改变全局音量。
Howler.volume(0.5);

更多深入示例（附带实时演示）可在示例目录找到。

核心

选项

src `Array/String` `[]` `必需`

要加载的音轨的源（URL或base64数据URI）。这些应按优先级顺序排列，howler.js将自动加载第一个与当前浏览器兼容的音轨。如果文件没有扩展名，您需要使用format属性显式指定扩展名。

volume `Number` `1.0`

特定音轨的音量，从0.0到1.0。

html5 `Boolean` `false`

设置为true以强制使用HTML5 Audio。这应该用于大型音频文件，以便您不必等待整个文件下载和解码后才能播放。

loop `Boolean` `false`

设置为true以自动无限循环声音。

preload `Boolean|String` `true`

在定义Howl时自动开始下载音频文件。如果使用HTML5 Audio，您可以将其设置为'metadata'，仅预加载文件的元数据（例如，仅获取其持续时间而不下载整个文件）。

autoplay `Boolean` `false`

设置为true以在声音加载后自动开始播放。

mute `Boolean` `false`

设置为true以加载时静音。

sprite `Object` `{}`

为声音定义声音精灵。偏移和持续时间以毫秒为单位定义。可选的第三个参数可用于设置精灵循环。使用audiosprite生成兼容的声音精灵是一个简单的方法。

new Howl({
  sprite: {
    key1: [offset, duration, (loop)]
  },
});

rate `Number` `1.0`

播放速率。0.5到4.0，1.0为正常速度。

pool `Number` `5`

非活动声音池的大小。一旦声音停止或播放完毕，它们被标记为结束并准备好清理。我们保持这些声音的池以便回收，以提高性能。通常不需要更改此设置。需要注意的是，当声音被暂停时，它不会被从池中移除，并且仍被视为活动，以便以后可以恢复。

format `Array` `[]`

howler.js自动从扩展名检测文件格式，但您也可以在提取无法工作的情况下（例如，与SoundCloud流一起使用时）指定格式。

xhr `Object` `null`

使用Web Audio时，howler.js使用XHR请求加载音频文件。如果您需要发送自定义头部，设置HTTP方法或启用withCredentials（参考），请使用此参数包含它们。每个都是可选的（方法默认为GET，头部默认为null，withCredentials默认为false）。例如：

// 使用每个属性。
new Howl({
  xhr: {
    method: 'POST',
    headers: {
      Authorization: 'Bearer:' + token,
    },
    withCredentials: true,
  }
});

// 只更改方法。
new Howl({
  xhr: {
    method: 'POST',
  }
});

onload `Function`

声音加载时触发。

onloaderror `Function`

声音无法加载时触发。第一个参数是声音的ID（如果存在），第二个是错误消息/代码。

加载错误代码在规范中定义：

1 - 用户代理在用户的请求下终止了媒体资源的获取过程。
2 - 某种网络错误导致用户代理停止获取媒体资源，在资源被确定为可用后。
3 - 在媒体资源被确定为可用后，解码媒体资源时发生某种错误。
4 - src属性指示的媒体资源或分配的媒体提供者对象不适合。

onplayerror `Function`

声音无法播放时触发。第一个参数是声音的ID，第二个是错误消息/代码。

onplay `Function`

声音开始播放时触发。第一个参数是声音的ID。

onend `Function`

声音播放结束时触发（如果是循环，它将在每次循环结束时触发）。第一个参数是声音的ID。

onpause `Function`

声音已暂停时触发。第一个参数是声音的ID。

onstop `Function`

声音已停止时触发。第一个参数是声音的ID。

onmute `Function`

声音已静音/取消静音时触发。第一个参数是声音的ID。

onvolume `Function`

声音音量已更改时触发。第一个参数是声音的ID。

onrate `Function`

声音播放速率已更改时触发。第一个参数是声音的ID。

onseek `Function`

声音已寻址时触发。第一个参数是声音的ID。

onfade `Function`

当前声音完成淡入/淡出时触发。第一个参数是声音的ID。

onunlock `Function`

通过触摸/点击事件自动解锁音频时触发。

方法

play([sprite/id])

开始播放声音。返回声音ID，以便用于其他方法。唯一不能链式调用的方法。

sprite/id：String/Number 可选 可以传递一个精灵或声音ID作为参数。如果传递了精灵，则根据精灵的定义播放新声音。如果传递了声音ID，则播放先前播放的声音（例如，在暂停之后）。但是，如果传递了从池中排出的声音ID，则不会播放任何声音。

pause([id])

暂停声音或组的播放，保存播放的seek位置。

id：Number 可选 声音ID。如果不传递，则暂停组中的所有声音。

stop([id])

停止声音的播放，将seek重置为0。

id：Number 可选 声音ID。如果不传递，则组中的所有声音都将停止。

mute([muted], [id])

静音声音，但不暂停播放。

muted：Boolean 可选 静音为true，取消静音为false。
id：Number 可选 声音ID。如果不传递，则组中的所有声音都将静音。

volume([volume], [id])

获取/设置此声音或组的音量。此方法可选地接受0、1或2个参数。

volume：Number 可选 音量从0.0到1.0。
id：Number 可选 声音ID。如果不传递，则组中的所有声音的音量将相对于它们自己的音量进行调整。

fade(from, to, duration, [id])

淡入/淡出一个正在播放的声音。完成后触发fade事件。

from：Number 淡入的起始音量（0.0到1.0）。
to：Number 淡入的结束音量（0.0到1.0）。
duration：Number 淡入时间，以毫秒为单位。
id：Number 可选 声音ID。如果不传递，则组中的所有声音将淡入。

rate([rate], [id])

获取/设置声音的播放速率。此方法可选地接受0、1或2个参数。

rate：Number 可选 播放速率。0.5到4.0，1.0为正常速度。
id：Number 可选 声音ID。如果不传递，则组中所有声音的播放速率将更改。

seek([seek], [id])

获取/设置声音的播放位置。此方法可选地接受0、1或2个参数。

seek：Number 可选 要移动当前播放到的位置（以秒为单位）。
id：Number 可选 声音ID。如果不传递，则第一个声音将寻址。

loop([loop], [id])

获取/设置是否循环声音或组。此方法可以可选地接受0、1或2个参数。

loop：Boolean 可选 是否循环。
id：Number 可选 声音ID。如果不传递，则组中所有声音的loop属性将更新。

state()

检查Howl的加载状态，返回unloaded、loading或loaded。

playing([id])

检查声音是否正在播放，返回Boolean。如果不传递声音ID，则检查Howl组中的任何声音是否正在播放。

id：Number 可选 要检查的声音ID。

duration([id])

获取音频源的持续时间（以秒为单位）。在load事件触发之前将返回0。

id：Number 可选 要检查的声音ID。传递ID将返回在此实例上播放的精灵的持续时间；否则，返回完整的源持续时间。

on(event, function, [id])

监听事件。可以通过多次调用此方法添加多个事件。

event：String 要触发/设置的事件名称（load, loaderror, playerror, play, end, pause, stop, mute, volume, rate, seek, fade, unlock）。
function：Function 定义要在事件上触发的函数。
id：Number 可选 仅监听此声音ID的事件。

once(event, function, [id])

与on相同，但在回调触发后自身会被移除。

event：String 要触发/设置的事件名称（load, loaderror, playerror, play, end, pause, stop, mute, volume, rate, seek, fade, unlock）。
function：Function 定义要在事件上触发的函数。
id：Number 可选 仅监听此声音ID的事件。

off(event, [function], [id])

移除已设置的事件监听器。不传递参数以移除所有事件。

event：String 事件名称（load, loaderror, playerror, play, end, pause, stop, mute, volume, rate, seek, fade, unlock）。
function：Function 可选 要移除的监听器。省略此参数以移除所有事件类型。
id：Number 可选 仅移除此声音ID的事件。

load()

默认会被调用，但如果将preload设置为false，则必须在可以播放任何声音之前调用load。

unload()

卸载并销毁一个Howl对象。这将立即停止所有附加到此声音的声音，并将其从缓存中移除。

全局选项

usingWebAudio `Boolean`

如果Web Audio API可用，则为true。

noAudio `Boolean`

如果没有音频可用，则为true。

autoUnlock `Boolean` `true`

自动尝试在移动设备（iOS、Android等）和桌面Chrome/Safari上启用音频。

html5PoolSize `Number` `10`

每个HTML5 Audio对象必须单独解锁，因此我们保持一个全局池的解锁节点，以便在所有Howl实例之间共享。此池在第一次用户交互时创建，并设置为此属性的大小。

autoSuspend `Boolean` `true`

在30秒不活动后自动暂停Web Audio AudioContext，以减少处理和能源使用。新的播放会自动恢复。将此属性设置为false以禁用此行为。

ctx `Boolean` `Web Audio Only`

暴露Web Audio API中的AudioContext。

masterGain `Boolean` `Web Audio Only`

暴露Web Audio API中的主GainNode。这对于编写插件或高级使用非常有用。

全局方法

以下方法用于全局修改所有声音，并从Howler对象调用。

mute(muted)

静音或取消静音所有声音。

muted：Boolean 静音为true，取消静音为false。

volume([volume])

获取/设置所有声音的全局音量，相对于它们自己的音量。

volume：Number 可选 音量从0.0到1.0。

stop()

停止所有声音并将它们的寻址位置重置为开始。

codecs(ext)

检查支持的音频编解码器。如果编解码器在当前浏览器中受支持，则返回true。

ext：String 文件扩展名。其中一个："mp3", "mpeg", "opus", "ogg", "oga", "wav", "aac", "caf", "m4a", "m4b", "mp4", "weba", "webm", "dolby", "flac"。

unload()

卸载并销毁所有当前加载的Howl对象。这将立即停止所有声音并将其从缓存中移除。

插件：空间音效

选项

orientation `Array` `[1, 0, 0]`

设置音频源在3D笛卡尔坐标空间中指向的方向。根据cone属性，声音指向远离监听器时可能会很安静或无声。

stereo `Number` `null`

设置此声音或组的音频源的立体声平移值。这使得设置左右平移非常容易，-1.0为远左，1.0为远右。

pos `Array` `null`

设置此声音或组的音频源相对于全局监听器的3D空间位置。

pannerAttr `Object`

设置声音或组的声音源的panner节点属性。查看pannerAttr方法了解所有可用选项。

onstereo `Function`

当当前声音的立体声平移更改时触发。第一个参数是声音的ID。

onpos `Function`

当当前声音的监听器位置更改时触发。第一个参数是声音的ID。

onorientation `Function`

当当前声音的监听器方向更改时触发。第一个参数是声音的ID。

方法

stereo(pan, [id])

获取/设置此声音或组的音频源的立体声平移。

pan：Number -1.0为全左，1.0为全右。
id：Number 可选 声音ID。如果不传递，则组中的所有声音将更新。

pos(x, y, z, [id])

获取/设置此声音或组的音频源相对于全局监听器的3D空间位置。

x：Number 音频源的x位置。
y：Number 音频源的y位置。
z：Number 音频源的z位置。
id：Number 可选 声音ID。如果不传递，则组中的所有声音将更新。

orientation(x, y, z, [id])

获取/设置音频源在3D笛卡尔坐标空间中指向的方向。根据cone属性，声音指向远离监听器时可能会很安静或无声。

x：Number 源的x方向。
y：Number 源的y方向。
z：Number 源的z方向。
id：Number 可选 声音ID。如果不传递，则组中的所有声音将更新。

pannerAttr(o, [id])

获取/设置声音或组的panner节点属性。

o：Object 要更新的所有值。
- coneInnerAngle 360 定向音频源的参数，这是内部角度，在该角度内不会有音量降低。
- coneOuterAngle 360 定向音频源的参数，这是外部角度，超出该角度音量将降低到coneOuterGain的恒定值。
- coneOuterGain 0 定向音频源的参数，这是在coneOuterAngle之外的增益。它是一个线性值，在[0, 1]范围内。
- distanceModel inverse 确定用于降低音量的算法，音频远离监听器时。可以是linear、inverse或exponential。您可以在规范中找到每种实现。
- maxDistance 10000 源和监听器之间的最大距离，超过这个距离后音量不再降低。
- refDistance 1 降低音量的参考距离，作为距离模型的一个变量。这在不同的模型中有不同的效果，取决于您的坐标比例。通常，在此距离处音量将等于1。
- rolloffFactor 1 音量降低的速度，随着源从监听器移动。这只是距离模型的一个变量，可以是linear时的[0, 1]范围，以及inverse和exponential时的[0, ∞]范围。
- panningModel HRTF 确定用于定位音频的空间化算法。可以是HRTF或equalpower。
id：Number 可选 声音ID。如果不传递，则组中的所有声音将更新。

全局方法

stereo(pan)

辅助方法，更新所有当前Howls的立体声平移位置。未来的Howls除非显式设置，否则不会使用此值。

pan：Number -1.0为全左，1.0为全右。

pos(x, y, z)

获取/设置监听器在3D笛卡尔空间中的位置。使用3D位置的声音将相对于监听器的位置。

x：Number 监听器的x位置。
y：Number 监听器的y位置。
z：Number 监听器的z位置。

orientation(x, y, z, xUp, yUp, zUp)

获取/设置监听器在3D笛卡尔空间中指向的方向。必须提供前向和向上向量。前向是监听器脸部指向的方向，向上是监听器顶部指向的方向。因此，这些值预期是彼此垂直的。

x：Number 监听器的x方向。
y：Number 监听器的y方向。
z：Number 监听器的z方向。
xUp：Number 监听器顶部的x方向。
yUp：Number 监听器顶部的y方向。
zUp：Number 监听器顶部的z方向。

分组播放

每个new Howl()实例也是一个组。您可以从Howl播放多个声音实例，并单独或作为组控制它们（注意：每个Howl只能包含一个音频文件）。例如，以下播放两个来自精灵的轨道，一起改变它们的音量，然后在同一个时间暂停两者。

var sound = new Howl({
  src: ['sound.webm', 'sound.mp3'],
  sprite: {
    track01: [0, 20000],
    track02: [21000, 41000]
  }
});

// 播放每个轨道。
sound.play('track01');
sound.play('track02');

// 改变两个轨道的音量。
sound.volume(0.5);

// 一秒钟后，暂停组中的两个声音。
setTimeout(function() {
  sound.pause();
}, 1000);

移动/Chrome播放

默认情况下，移动浏览器和Chrome/Safari上的音频被锁定，直到在用户交互中播放声音，然后它在页面会话的其余时间正常播放（Apple文档）。howler.js的默认行为是尝试在第一个touchend事件中通过播放空缓冲区来自动解锁音频播放。可以通过调用以下代码禁用此行为：

Howler.autoUnlock = false;

如果您尝试在页面加载时自动播放音频，可以监听playerror事件，然后等待unlock事件再次尝试播放音频：

var sound = new Howl({
  src: ['sound.webm', 'sound.mp3'],
  onplayerror: function() {
    sound.once('unlock', function() {
      sound.play();
    });
  }
});

sound.play();

杜比音频播放

包括对杜比音频格式（目前在Edge和Safari中支持）的完整支持。但是，您必须指定您正在加载的文件是dolby，因为它在mp4容器中。

var dolbySound = new Howl({
  src: ['sound.mp4', 'sound.webm', 'sound.mp3'],
  format: ['dolby', 'webm', 'mp3']
});

格式建议

Howler.js支持多种音频编解码器，浏览器支持度各不相同（"mp3", "opus", "ogg", "wav", "aac", "m4a", "m4b", "mp4", "webm", ...），但如果您想要完整的浏览器覆盖，您仍然需要至少使用其中的两个。如果您的目标是在文件大小和高质量之间取得最佳平衡，根据广泛的生产测试，您最好的选择是默认使用webm并回退到mp3。webm几乎拥有完整的浏览器覆盖率，压缩和质量的结合非常好。您需要mp3回退适用于Internet Explorer。

请记住，howler.js从您的源数组中选择第一个兼容的声音。因此，如果您希望webm在mp3之前使用，您需要按该顺序排列源。

如果您希望您的webm文件在Firefox中可以寻址，请确保使用提示元素对其进行编码。一种方法是使用ffmpeg中的dash标志：

ffmpeg -i sound1.wav -dash 1 sound1.webm

最后感谢阅读！欢迎关注我，微信公众号：倔强青铜三。欢迎点赞、收藏、关注，一键三连！！！

🎧用Howler.js后，我天天网页搓碟当DJ🎵