howler.js

描述

howler.js是现代网络的音频库。它默认为Web Audio API，并回到HTML5音频。这使得在所有平台上都可以轻松可靠地使用音频。

其他信息，实时演示和用户展示柜可在howlerjs.com上找到。

在Twitter上关注howler.js和与开发有关的讨论：@GoldFirestudios。

特征

• 所有音频需求的单个API
• 默认为Web音频API，然后返回到HTML5音频
• 处理跨环境的边缘案例和错误
• 支持所有编解码器，以提供完整的跨浏览器支持
• 自动缓存以提高性能
• 控制声音单独，分组或全球
• 一次播放多种声音
• 简单的声音精灵定义和播放
• 完全控制褪色，速率，寻求，数量等。
• 轻松添加3D空间声音或立体声音调
• 模块化 – 使用您想要的东西，易于扩展
• 没有外部依赖性，只有纯JavaScript
• 像7kb的gzz

浏览器兼容性

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

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

现场演示

• 音频播放器
• 收音机
• 空间音频
• 音频精灵

文档

内容

• 快速开始
• 例子
• 核
  • 选项
  • 方法
  • 全局选项
  • 全局方法
• 插件：空间
  • 选项
  • 方法
  • 全局方法
• 小组播放
• 移动播放
• 杜比音频播放
• Facebook即时游戏
• 格式建议
• 执照

快速开始

启动和运行的几个选项：

• 克隆仓库： git clone https://github*.*c*om/goldfire/howler\\.js.git
• 使用NPM安装： npm install howler
• 使用纱线安装： yarn add howler
• 安装鲍尔： bower install howler
• 托管CDN： cdnjs jsDelivr

在浏览器中：

howler.js\”></script>
<script>
var sound = new Howl({
src: [\’sound.webm\’, \’sound.mp3\’]
});
</script>\”>

 < 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音频和HTML5音频之间创建奇偶校验的核心功能。它不包含任何空间/立体声音频功能。
• 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 : [ \'sound.webm\' , \'sound.mp3\' , \'sound.wav\' ] ,
  autoplay : true ,
  loop : true ,
  volume : 0.5 ,
  onend : function ( ) {
    console . log ( \'Finished!\' ) ;
  }
} ) ; 

定义并播放声音精灵：

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

// Shoot the laser!
sound . play ( \'laser\' ) ; 

听事件：

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

// Clear listener after first call.
sound . once ( \'load\' , function ( ) {
  sound . play ( ) ;
} ) ;

// Fires when the sound finishes playing.
sound . on ( \'end\' , function ( ) {
  console . log ( \'Finished!\' ) ;
} ) ; 

控制多种声音：

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

// Play returns a unique Sound ID that can be passed
// into any method on Howl to control that specific sound.
var id1 = sound . play ( ) ;
var id2 = sound . play ( ) ;

// Fade out the first sound and speed up the second.
sound . fade ( 1 , 0 , 1000 , id1 ) ;
sound . rate ( 1.5 , id2 ) ; 

ES6：

 import { Howl , Howler } from \'howler\' ;

// Setup the new Howl.
const sound = new Howl ( {
  src : [ \'sound.webm\' , \'sound.mp3\' ]
} ) ;

// Play the sound.
sound . play ( ) ;

// Change global volume.
Howler . volume ( 0.5 ) ;

在示例目录中可以找到更多深入的示例（随附的实时演示）。

核

选项

SRC Array/String required []

为声音加载轨道的源（urls或base64数据URI）。这些应该按照偏好顺序， howler.js将自动加载与当前浏览器兼容的第一个。如果您的文件没有扩展名，则需要使用format属性明确指定扩展名。

卷Number 1.0

特定轨道的体积从0.0到1.0 。

html5 Boolean false

设置为true强制HTML5音频。这应该用于大型音频文件，以便您不必在播放之前等待完整文件的下载和解码。

循环Boolean false

设置为true自动循环声音。

预紧Boolean|String true

定义Howl时，会自动开始下载音频文件。如果使用HTML5音频，则可以将其设置为\'metadata\' ，以便预加载文件的元数据（例如，在没有下载整个文件的情况下获取其持续时间）。

自动播放Boolean false

加载声音时，设置为true以自动启动播放。

静音Boolean false

设置为true以加载音频静音。

精灵Object {}

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

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

汇率Number 1.0

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

池Number 5

不活动的声音池的大小。一旦声音停止或完成播放，它们就会被标记为结束并准备清理。我们保留其中的池以回收以提高性能。通常，这不需要更改。重要的是要记住，当声音被暂停时，不会从游泳池中删除，并且仍将被视为活动性，以便以后可以恢复。

格式Array []

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

xhr Object null

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

 // Using each of the properties.
new Howl ( {
  xhr : {
    method : \'POST\' ,
    headers : {
      Authorization : \'Bearer:\' + token ,
    } ,
    withCredentials : true ,
  }
} ) ;

// Only changing the method.
new Howl ( {
  xhr : {
    method : \'POST\' ,
  }
} ) ; 

on load Function

加载声音时会发射。

OnloadError Function

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

负载错误代码在规格中定义：

• 1-用户代理按用户的请求中止了媒体资源的获取过程。
• 2-某些描述的网络错误导致用户代理在确定资源可用后停止获取媒体资源。
• 3-在解码媒体资源时，发生了一些描述的错误，在确定资源可用之后。
• 4- SRC属性或分配的媒体提供商对象指示的媒体资源不合适。

OnPlayError Function

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

OnPlay Function

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

ONEND Function

当声音完成播放时会发射（如果循环播放，它将在每个循环的末端发射）。第一个参数是声音的ID。

on par Function

当声音暂停时会发射。第一个参数是声音的ID。

启用Function

当声音停止时发射。第一个参数是声音的ID。

onMute Function

当声音被静音/未渗透时，会发射。第一个参数是声音的ID。

onvolume Function

当声音的音量发生变化时会发射。第一个参数是声音的ID。

Onrate Function

当声音的播放速度发生变化时，会发射。第一个参数是声音的ID。

Onseek Function

当寻求声音时发火。第一个参数是声音的ID。

输入Function

当当前的声音逐渐消失时，会发射。第一个参数是声音的ID。

Onunlock Function

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

方法

播放（[精灵/ID]）

开始声音的播放。返回与其他方法一起使用的声音ID。只有无法束缚的方法。

• 精灵/ID ： String/Number optional为一个可以是精灵或声音ID的参数。如果通过精灵，将根据Sprite的定义播放新的声音。如果通过声音ID，将播放先前播放的声音（例如，在暂停之后）。但是，如果通过池中排出的声音ID即可通过，那么什么都不会发挥作用。

暂停（[id]）

暂停声音或小组的播放，节省了播放的seek 。

• ID ： Number optional声音ID。如果没有传递，则所有的声音都会暂停。

停止（[id]）

停止播放声音， seek为0 。

• ID ： Number optional声音ID。如果没有传递，则组中的所有声音都将停止。

静音（[静音]，[id]）

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

• 静音： Boolean optional为静音和假静音。
• ID ： Number optional声音ID。如果没有传递，则组中的所有声音都将停止。

卷（[卷]，[id]）

获取此声音或组的卷。此方法可选为0、1或2个参数。

• 音量： Number optional体积从0.0到1.0 。
• ID ： Number optional声音ID。如果没有传递，则组中的所有声音都相对于自己的音量而变化。

淡入（从，到持续时间，[id]）

在两卷之间淡出目前播放的声音。完成后，发射fade事件。

• 从： Number量到（ 0.0至1.0 ）淡入数量。
• 到： Number卷为（ 0.0至1.0 ）。
• 持续时间：毫秒的Number时间褪色。
• ID ： Number optional声音ID。如果没有传递，则组中的所有声音都会消失。

费率（[速率]，[id]）

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

• 费率： Number optional播放速率。 0.5至4.0，1.0为正常速度。
• ID ： Number optional声音ID。如果没有通过，则组中所有声音的播放率都会改变。

寻求（[seek]，[id]）

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

• 寻求： Number optional位置将当前播放移至（以秒为单位）。
• ID ： Number optional声音ID。如果没有通过，则第一个声音将寻求。

循环（[loop]，[id]）

获取/设置是循环声音还是组。此方法可以选择进行0、1或2个参数。

• 循环： Boolean optional循环或不循环，这就是问题。
• ID ： Number optional声音ID。如果没有传递，则组中的所有声音都会更新其loop属性。

状态（）

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

玩（[id]）

检查当前是否正在播放声音，返回Boolean 。如果没有传递声音ID，请检查Howl组中的任何声音是否在播放。

• ID ： Number optional要检查的声音ID。

持续时间（[id]）

获取音频源的持续时间（以秒为单位）。将返回0，直到load事件发生后。

• ID ： Number optional要检查的声音ID。通过ID将返回在这种情况下播放的精灵的持续时间；否则，返回了完整的源持续时间。

在（事件，功能，[id]）

听事件。可以通过多次调用多个事件来添加多个事件。

• 事件：fire/set的事件的String名称（ load ， loaderror ， playerror ，play， play ， end ， pause ， stop ， mute ， volume ， rate ， seek ，搜索，淡入， fade ， unlock ）。
• 功能： Function将功能定义为事件上的功能。
• ID ： Number optional仅收听此声音ID的事件。

一次（事件，功能，[id]）

与on相同，但在回击后它会自行自身。

• 事件：fire/set的事件的String名称（ load ， loaderror ， playerror ，play， play ， end ， pause ， stop ， mute ， volume ， rate ， seek ，搜索，淡入， fade ， unlock ）。
• 功能： Function将功能定义为事件上的功能。
• ID ： Number optional仅收听此声音ID的事件。

关闭（事件，[函数]，[id]）

删除已设置的事件侦听器。无参数呼叫以删除所有事件。

• 事件：事件的String名称（ load ， loaderror ， playerror ， play ， end ，Pause， pause ， stop ，Mute， mute ， volume ， rate ， seek ，淡出， fade ， unlock ）。
• 函数： Function optional侦听器要删除。省略以删除所有类型事件。
• ID ： Number optional仅删除此声音ID的事件。

加载（）

默认情况下，这是默认情况下调用的，但是如果将preload设置为False，则必须在播放任何声音之前调用load 。

卸下（）

卸载并销毁一个how叫对象。这将立即停止在此声音上附加的所有声音，并将其从缓存中删除。

全局选项

使用Webaudio Boolean

如果可以使用Web音频API， true 。

没有audio Boolean

如果没有音频，则为true 。

Autounlock Boolean true

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

html5poolsize Number 10

每个HTML5音频对象都必须单独解锁，因此我们保留一个全局的未锁定节点池，以在所有Howl实例之间共享。该池在第一个用户交互中创建，并设置为此属性的大小。

AutoSuspend Boolean true

无活动30秒后，自动暂停了网络音频听力膜片，以减少处理和能源使用情况。自动恢复新的播放。将此属性设置为false以禁用此行为。

Web Audio Only CTX Boolean网络音频

使用Web Audio API揭示AudioContext 。

Hastergain Boolean Web Audio Only

用Web Audio API揭示主GainNode 。这对于编写插件或高级用法很有用。

全局方法

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

静音（静音）

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

• 静音： Boolean真静音，并假静音。

卷（[卷]）

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

• 音量： Number optional体积从0.0到1.0 。

停止（）

停止所有声音并重置他们的寻求位置。

编解码器（ext）

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

• ext ： String文件扩展名。之一：“ mp3”，“ mpeg”，“ opus”，“ ogg”，“ oga”，“ wav”，“ aac”，“ caf”，“ m4a”，“ m4b”，“ m4b”，“ mp4”，“ mp4”，“ weba”，“ webm”，“ webm”，“ webm”，“ dolby”，“ flac”。

卸下（）

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

插件：空间

选项

方向Array [1, 0, 0]

设置音频源指向3D笛卡尔坐标空间的方向。根据cone属性，根据声音的定向程度，指向听众的声音可能是安静的或保持沉默的。

立体声Number null

设置此声音或组的音频源的立体声镀膜值。这使得以-1.0值为左/右图的左/右平移变得易于设置，值为1.0 。

pos Array null

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

Pannerattr Object

为声音或一组声音设置Panner节点的属性。有关所有可用选项，请参见pannerAttr方法。

Onstereo Function

当当前声音具有立体声板时发生射击。第一个参数是声音的ID。

ONPOS Function

当当前声音的侦听器位置更改时，火就会发生。第一个参数是声音的ID。

偏置Function

当当前的声音具有侦听器的方向时，火就会发生变化。第一个参数是声音的ID。

方法

立体声（PAN，[ID]）

获取/设置此声音或组中所有音频源的立体声板。

• PAN ： Number一个值为-1.0的值一直左，而1.0一直向右。
• ID ： Number optional声音ID。如果没有传递，则所有组中的所有内容都将更新。

pos（x，y，z，[id]）

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

• X ： Number音频源的X位置。
• Y ： Number音频源的Y位置。
• Z ： Number音频源的z位。
• ID ： Number optional声音ID。如果没有传递，则所有组中的所有内容都将更新。

方向（x，y，z，[id]）

获取/设置音频源指向3D笛卡尔坐标空间的方向。根据cone属性，根据声音的定向程度，指向听众的声音可能是安静的或保持沉默的。

• X ： Number源的X-方向。
• Y ： Number源源。
• Z ： Number源源源。
• ID ： Number optional声音ID。如果没有传递，则所有组中的所有内容都将更新。

Pannerattr（O，[ID]）

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

• O ： Object所有要更新的值。
  • Coneinnerangle 360定向音频源的参数，这是一个程度的角度，其中不会减小体积。
  • ConeOuterAngle 360定向音频源的参数，这是一个角度，以程度为角度，在其之外，该体积将减小为coneOuterGain的恒定值。
  • ConeOuterGain 0定向音频源的参数，这是coneOuterAngle之外的增益。它是[0, 1]范围内的线性值。
  • DistanceModel inverse确定用于减少音量的算法，因为音频从听众移开。可以是linear ， inverse或exponential 。您可以在规格中找到每个的实现。
  • MaxDistance 10000源和侦听器之间的最大距离，之后将不会进一步减少音量。
  • 恢复1随着源与侦听器的进一步移动，减少音量的参考距离。这只是距离模型的变量，并且取决于使用哪个模型和坐标的规模，其效果不同。通常，在此距离处的体积将等于1。
  • rollofffactor 1随着源从侦听器移动时，音量降低了多快。这只是距离模型的一个变量，可以linear和[0, ∞]的[0, 1]范围内，并以inverse指数为exponential 。
  • PanningModel HRTF确定哪种空间化算法用于定位音频。可以是HRTF或equalpower 。
• ID ： Number optional声音ID。如果没有传递，则所有组中的所有内容都将更新。

全局方法

立体声（PAN）

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

• PAN ： Number一个值为-1.0的值一直左，而1.0一直向右。

pos（x，y，z）

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

• X ： Number听众的X位。
• Y ： Number听众的Y位置。
• Z ： Number是听众的Z位。

方向（X，Y，Z，XUP，YUP，ZUP）

获取/设置听众指向3D笛卡尔空间的方向。必须提供前向量。正面是听众的脸指向的方向，并且是听众顶部指向的方向。因此，这些值有望彼此成直角。

• X ： Number侦听器的X取向。
• Y ： Number聆听者的Y方向。
• Z ： Number Z-取向的侦听器。
• XUP ： Number听众顶部的X定向。
• 是的： 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 ]
  }
} ) ;

// Play each of the track.s
sound . play ( \'track01\' ) ;
sound . play ( \'track02\' ) ;

// Change the volume of both tracks.
sound . volume ( 0.5 ) ;

// After a second, pause both sounds in the group.
setTimeout ( function ( ) {
  sound . pause ( ) ;
} , 1000 ) ;

移动/镀铬播放

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

 Howler . autoUnlock = false ;

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

 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\' ]
} ) ;

Facebook即时游戏

howler.js为新的Facebook Instant Games平台提供了音频支持。如果在即时游戏开发时遇到任何问题，请使用标签[IG]打开问题。

格式建议

howler.js支持各种具有不同浏览器支持的音频编解码器（“ mp3”，“ opus”，“ ogg”，“ ogg”，“ wav”，“ aac”，“ m4a”，“ m4a”，“ m4b”，“ mp4”，“ mp4”，“ webm”，…），但是如果您仍然需要全部浏览器覆盖范围，至少需要在两个browsers上使用。如果您的目标是基于广泛的生产测试拥有小文件大小和高质量的最佳平衡，那么最好的选择是默认为webm并退回到mp3 。 webm几乎具有完整的浏览器覆盖范围，并结合了压缩和质量。您将需要Internet Explorer的mp3后备。

重要的是要记住， howler.js从您的一系列来源中选择第一个兼容的声音。因此，如果您希望在mp3之前使用webm ，则需要按照该顺序进行源。

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

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

赞助商

支持howler.js的持续开发，并通过指向您的网站的链接[成为赞助商]，将您的徽标获取在我们的会员上。您还可以成为较低层的支持者，并在支持者列表中获取您的名字。所有支持都非常感谢！

执照

版权（C）2013-2021 James Simpson和Goldfire Studios，Inc。

根据MIT许可发布。