howler.js用法

howler.js用法

示例

  • 播放最基本的 MP3 文件：

    1
    2
    3
    4
    var sound = new Howl({
      src: ['sound.mp3']
    });
    sound.play();

  • 流式传输音频（适用于实时音频或大文件）：

    1
    2
    3
    4
    5
    var sound = new Howl({
      src: ['stream.mp3'],
      html5: true
    });
    sound.play();

核心选项

  • src：所需加载的音轨的源（URL 或 base64 数据 URI）。应按优先顺序排列。如果文件没有扩展名，则需要使用 format 属性明确指定扩展名。
  • volume：特定音轨的音量，从 0.0 到 1.0。
  • html5：设置为 true 以强制使用 HTML5 Audio。这应该用于大音频文件，以便不必等待整个文件下载和解码后再播放。
  • loop：设置为 true 以自动无限循环声音。
  • preload：当定义 Howl 时自动开始下载音频文件。如果使用 HTML5 Audio，可以将其设置为 ‘metadata’，仅预加载文件的元数据（例如，获取其持续时间而无需下载整个文件）。
  • autoplay：设置为 true 以在声音加载后自动开始播放。
  • mute：设置为 true 以加载静音音频。
  • sprite：为声音定义声音精灵。偏移和持续时间以毫秒为单位定义。可选的第三个参数可用于设置精灵是否循环。使用 audiosprite 生成兼容的声音精灵是一个简单方法。

方法

  • play([sprite/id])：开始播放声音。返回声音 ID，以用于其他方法。唯一不能链接的方法。
  • pause([id])：暂停声音或组的播放，保存播放位置。
  • stop([id])：停止声音播放，将播放位置重置为 0。
  • mute([muted], [id])：静音声音，但不暂停播放。
  • volume([volume], [id])：获取/设置此声音或组的音量。
  • fade(from, to, duration, [id])：在两个音量之间淡入/淡出当前播放的声音。
  • rate([rate], [id])：获取/设置声音的播放速率。
  • seek([seek], [id])：获取/设置声音的播放位置。
  • loop([loop], [id])：获取/设置是否循环声音或组。
  • state()：检查 Howl 的加载状态，返回未加载、加载中或已加载。
  • playing([id])：检查声音是否正在播放，返回布尔值。
  • duration([id])：获取音频源的持续时间（以秒为单位）。
  • on(event, function, [id])：监听事件。
  • once(event, function, [id])：与 on 相同，但在回调触发后移除自身。
  • off(event, [function], [id])：移除已设置的事件监听器。
  • load()：默认被调用，但如果将 preload 设置为 false，则必须在播放任何声音之前调用 load。
  • unload()：卸载并销毁 Howl 对象。这将立即停止所有附加到此声音的声音并将其从缓存中移除。

全局选项

  • usingWebAudio：如果可用 Web Audio API，则为 true。
  • noAudio：如果没有音频可用，则为 true。
  • autoUnlock：自动尝试在移动设备（iOS、Android 等）和桌面 Chrome/Safari 上启用音频。
  • html5PoolSize：每个 HTML5 Audio 对象必须单独解锁，因此我们保持一个全局池的解锁节点，在所有 Howl 实例之间共享。此池在第一次用户交互时创建，并设置为此属性的大小。
  • autoSuspend：在 30 秒不活动后自动暂停 Web Audio AudioContext，以减少处理和能源使用。在新播放时自动恢复。将此属性设置为 false 以禁用此行为。
  • ctx：仅 Web Audio 时，暴露 AudioContext。
  • masterGain：仅 Web Audio 时，暴露主 GainNode。这对于编写插件或高级使用非常有用。

全局方法

  • mute(muted)：静音或取消静音所有声音。
  • volume([volume])：获取/设置所有声音的全局音量。
  • stop()：停止所有声音并将其播放位置重置为开头。
  • codecs(ext)：检查支持的音频编解码器。如果编解码器在当前浏览器中受支持，则返回 true。
  • unload()：卸载并销毁所有当前加载的 Howl 对象。这将立即停止所有声音并从缓存中移除。

插件：Spatial

  • orientation：设置音频源在 3D 笛卡尔坐标空间中指向的方向。
  • stereo：为声音或组设置音频源的立体声平移值。
  • pos：设置音频源相对于全局监听器的 3D 空间位置。
  • pannerAttr：为声音或声音组设置 panner 节点的属性。

组播放

每个新的 Howl() 实例也是一个组。你可以从 Howl 播放多个声音实例，并单独或作为组控制它们。

移动/Chrome 播放

默认情况下，移动浏览器和 Chrome/Safari 上的音频在用户交互内播放声音后才解锁，然后在页面会话的其余时间内正常播放。

Dolby Audio 播放

包括对 Dolby Audio 格式的完整支持（目前在 Edge 和 Safari 中支持）。但是，由于它位于 mp4 容器中，因此必须指定你正在加载的文件是 dolby。

Facebook Instant Games

Howler.js 为新的 Facebook Instant Games 平台提供音频支持。

格式建议

Howler.js 支持多种音频编解码器，浏览器支持度各不相同，但要实现全面浏览器覆盖，你仍然需要至少使用其中两种。如果目标是实现小文件大小和高质量之间的最佳平衡，基于广泛的生产测试，最佳选择是默认使用 webm 并回退到 mp3。webm 具有几乎全面的浏览器覆盖率，压缩和质量的组合非常好。你需要 mp3 作为 Internet Explorer 的回退。

重要的是要记住，howler.js 从你的源数组中选择第一个兼容的声音。因此，如果你想在 mp3 之前使用 webm，则需要按该顺序放置源。