audiojs源码全解读:700行代码如何构建一个跨浏览器音频播放器

原创2026-11-11 21:43:321,362 阅读

audiojs源码全解读:700行代码如何构建一个跨浏览器音频播放器

HTML5 刚普及时的年代,各浏览器对 <audio> 标签的支持参差不齐——有的完全不认识,有的只播 ogg 不播 mp3,播放行为更是五花八门。audiojs 正是为了解决这个痛点而生的一个 HTML5 <audio> 跨浏览器 JavaScript 封装库:能用原生音频就用原生,不能就无缝切换到一个"隐形"的 Flash 播放器兜底,同时给所有浏览器提供一套统一、可用 CSS 自由定制的 HTML 播放器界面。整个核心库只有约 700 行可读性极佳的 JavaScript。这篇文章带你逐段拆解 audiojs 源码,看看这个小库是如何一步步构建出一个完整的跨浏览器音频播放器的。🎧

一、项目结构:一个库的"全家桶"

先花 30 秒认识仓库结构,做到心中有数再读源码:

文件 / 目录 角色
audiojs/audio.js 核心源码,共 722 行,本文主角
audiojs/audio.cmd.js 同逻辑的 CMD(SeaJS 风格)模块化版本
audiojs/audio.min.js 由 Closure Compiler 编译压缩后的产物
audiojs/audiojs.as Flash 端源码(ActionScript,145 行)
audiojs/audiojs.swf audiojs.as 编译出的降级播放器
audiojs/player-graphics.gif 播放器按钮精灵图(播放/暂停/加载中/错误四态合一)
demos/ 6 个示例页,覆盖加载失败、自定义皮肤、播放列表等场景
Rakefile 构建脚本:编译、发布、打包
README.md 快速上手与构建说明

注意一个关键事实:真正的运行时代码只有 三个文件(audio.js + audiojs.swf + player-graphics.gif),其余全是演示与构建工具。这就是"小库"的第一个特征——部署面积极小。

二、入口:一个"传名"的 IIFE 与路径自检测

打开 audiojs/audio.js,第一行注释就自我定位为 shim(垫片)而非 polyfill,整个库的设计基调由此确立:

// A cross-browser javascript shim for html5 audio
(function(audiojs, audiojsInstance, container) {
  ...

而文件最末一行(audiojs/audio.js#L722)才是这个 IIFE 的调用:

})('audiojs', 'audiojsInstance', this);

三个参数其实传的是三个"插槽":前两个是字符串(全局变量名,可与页面其他库冲突时替换),第三个 this 即 window。IIFE 内部于是挂出两个核心对象:

  • container['audiojs']:工厂对象(单例),存放设置、构造函数、全部辅助方法
  • container['audiojsInstance']:播放器实例构造函数,每个 <audio> 标签对应一个

路径自检测:库自己知道"我住哪儿"

紧接着的 audiojs/audio.js#L5-L19 做了一件很贴心的事——扫描页面上所有 <script> 标签,用正则 audio(\.min)?\.js.* 找到自己,推导出 audiojs.swf 和 player-graphics.gif 所在目录:

var re = new RegExp('audio(\.min)?\.js.*'),
    scripts = document.getElementsByTagName('script');

这意味着用户完全不需要手动指定资源路径,注释还特别提到它能兼容 Rails 等框架在资源路径后追加 ?1301478336 这类防缓存串的小技巧。

三、跨浏览器三件套:最关键的三段检测代码

3.1 useFlash:全库最聪明的三行

audiojs/audio.js#L47-L50:

useFlash: (function() {
  var a = document.createElement('audio');
  return !(a.canPlayType && a.canPlayType('audio/mpeg;').replace(/no/, ''));
})(),

拆开看这个巧妙的小把戏:canPlayType('audio/mpeg;') 会返回 'no'、'maybe' 或 'yes';replace(/no/, '') 把 'no' 变成空字符串(假值),于是 useFlash 只在浏览器不支持 mp3 时为 true。支持 mp3 的浏览器走原生通道,其余统统走 Flash。

README.md 里作者把设计哲学写得直白:只播 mp3,不支持 ogg——"说实话,现实世界里没人真的导出 ogg 文件"。这一取舍换来的是 Flash 兜底路径的简单纯粹。

3.2 hasFlash:三级探测 Flash 插件

audiojs/audio.js#L51-L64 按顺序尝试三种方式:

  1. navigator.plugins['Shockwave Flash'](标准方式,覆盖 Firefox / Chrome)
  2. navigator.mimeTypes['application/x-shockwave-flash'] 及其 enabledPlugin
  3. new ActiveXObject('ShockwaveFlash.ShockwaveFlash')(IE 专用,带 try/catch)

三者皆否时,newInstance 会触发默认的 flashError 回调:在播放器上显示"缺少 Flash 插件"提示,并直接附上音频文件的下载链接——保证用户至少能"带走"这首曲子。这是很老派但很可靠的降级思想。

3.3 Flash 对象是一段"模板字符串"

audiojs/audio.js#L31-L36 里,整个 <object>/<embed> 结构被写成带占位符 $1(实例名)、$2(swf 路径)、$3(防缓存时间戳)的字符串模板。注入时(见下文 injectFlash)用 replace 填值即可。其中 $3 取 +new Date + Math.random(),注释说明这是为修复 Firefox 同页多播放器时的缓存问题。

四、newInstance:一个播放器的完整装配线

audiojs/audio.js#L243-L281 的 newInstance 是全库的心脏,像一条工厂装配线,按序走完 8 个工位:

  1. 深拷贝默认 settings(用 helpers.clone 递归克隆,保证实例间互不污染)
  2. 读取 <audio> 上的 autoplay / loop / preload 属性写入设置
  3. 用 helpers.merge 浅合并用户传入的 options
  4. 调用 createPlayer 注入 UI 标记
  5. new audiojsInstance(element, s) 创建播放器实例
  6. injectCss 动态注入默认皮肤
  7. 分支决策:useFlash && hasFlash → injectFlash + attachFlashEvents;需要 Flash 却没有 → flashError
  8. attachEvents 绑定 UI 事件,把实例登记进 instances 表并返回

默认 UI:markup 与 CSS 都是字符串

settings.createPlayer.markup(audiojs/audio.js#L67-L81)就是一段 HTML 字符串:.play-pause 按钮区、.scrubber 进度条、.time 时间显示、.error-message 错误区;配套的 settings.css(audiojs/audio.js#L95-L147)则是一整段默认样式字符串,甚至包含 Retina @2x 的媒体查询。

injectCss(audiojs/audio.js#L443-L475)有两个巧妙点:

  • 注入到 <head> 最顶部——用户自己写的样式优先级天然更高,想换肤直接覆盖即可,无需库提供主题 API
  • 多个播放器共享同一个 <style title="audiojs">,避免 style 标签无限膨胀

IE6/7 的"HTML5 元素克隆"难题

旧版 IE 的 innerHTML 与 cloneNode 根本不认识 <audio> 标签。createPlayer(audiojs/audio.js#L285-L305)因此留了一个分支,配合 cloneHtml5Node:先执行一次 document.createElement('audio') 让 IE "认识"这个未知标签,再通过 DocumentFragment 间接克隆。这是 HTML5 shim 时代的经典技巧。

五、两套并行世界:UI 事件与音源事件

这是 audiojs 最本质的设计——UI 层和音源层(原生 / Flash)彻底解耦,换音源不用换 UI。

5.1 UI 事件:attachEvents

audiojs/audio.js#L308-L344 中只绑定与"界面"有关的事:

  • 点击 .play-pause → audio.playPause()
  • 点击 .scrubber → 用 clientX 换算点击位置百分比 → audio.skipTo(percent)
  • 仅在非 Flash 分支追加音源事件:timeupdate 驱动进度条、ended 处理播完、<source> 的 error 触发 loadError 并清掉轮询定时器

5.2 播放进度:用轮询代替事件

trackLoadProgress(audiojs/audio.js#L522-L549)放弃了标准的 progress 事件,改用两个 200ms 的 setInterval 轮询。注释给出了原因,非常诚实:Chrome 在从缓存加载 mp3 时存在不触发 progress 事件的 bug。

  • readyTimer:轮询 readyState,>-1 时触发 init(),>1 时若设了 autoplay 就播放,然后启动 loadTimer
  • loadTimer:轮询 buffered 区间,算出 loadedPercent 更新"已加载"灰色条

这里还藏着一处 iOS 特判:/(ipod|iphone|ipad)/i 检测到 iOS 时不提前显示 loading 状态——因为 iOS 在用户交互前根本不会开始预加载 mp3。类似的 iOS 特判也出现在 play() 里(见下一节)。

5.3 Flash 桥:attachFlashEvents

走 Flash 路线时,attachFlashEvents 会把实例上的 load / skipTo / play / pause 等方法逐一覆写成对 swf 对象的调用。两个值得玩味的细节:

  • SWF → JS 方向的回调路由:注入 swf 时 URL 里带了 playerInstance='audiojs'.instances['audiojs0'] 这样的参数;Flash 端拿到它作为前缀,ExternalInterface.call 时就能精确回调到"自己"对应的那个 JS 实例,天然支持同页多播放器
  • 为什么 JS 调 SWF 用的是 pplay() / ppause() 而不是 play() / pause()? 注释(audiojs/audio.js#L376-L377)点明了原因:IE 的 ExternalInterface 对 play 这类关键字会报错,于是改用别名

5.4 一段"历史遗迹":IE6 内存泄漏修复

events.purge(audiojs/audio.js#L554-L565)是经典的 Crockford 式 IE6 内存泄漏修复:attachEvent 绑定闭包会产生循环引用导致 IE6 无法回收 DOM,于是把所有注册元素登记在 listeners 里,window.onunload 时递归置空。今天读源码时它像考古,但在 audiojs 诞生的年代,这是兼容老浏览器的保命技能。

六、audiojsInstance:每个播放器的统一 API

构造函数(audiojs/audio.js#L602-L617)很克制:记录 element、wrapper、source、mp3(优先取 <audio src>,否则取第一个 <source>)和初始状态。

真正的 API 面在 prototype 上(audiojs/audio.js#L619-L697):

方法 要点
play() 先处理 iOS(readyState == 0 时先 init())、再处理 preload 延迟加载,最后 element.play()
pause() element.pause() 并同步状态
skipTo(percent) 拒绝跳到尚未加载到的位置(percent > loadedPercent 直接 return),防止浏览器卡死
loadProgress() 从 buffered.end() 计算已加载比例
trackEnded() skipTo(0) 回卷 → 未开 loop 则 pause() → 回调 settings.trackEnded
setVolume(v) 直接写 element.volume

全库最重要的扩展模式在这里:每个 API 方法都是"先干实际的活,再调用 settings 中同名回调"。用户只需覆写 settings.play = function(){...} 就能插入自己的逻辑(比如播放列表自动切歌),完全不用动核心代码——demos/test6.html 的播放列表正是建立在这个机制上的。

七、Flash 端:145 行 ActionScript 干了什么

audiojs/audiojs.as 是一个标准的 Flash Sprite,核心就四件事:

  • 注册回调(audiojs/audiojs.as#L44-L50):用 ExternalInterface.addCallback 暴露 init / load / playPause / pplay / ppause / skipTo / setVolume 七个入口给 JS
  • 握手:构造函数最后一行立刻 ExternalInterface.call(playerInstance + 'loadStarted') 告知 JS"我准备好了";JS 侧的 loadStarted(audiojs/audio.js#L390-L395)收到后按 preload / autoplay 决定下一步
  • 加载与进度:load() 用 Sound + URLRequest 拉 mp3,监听 ProgressEvent.PROGRESS 换算加载百分比与总时长,IOErrorEvent 则回调 loadError
  • 播放控制:pause 时记录 pausePoint 并停掉 Timer,play(pausePoint) 断点续播;一个 250ms 的 Timer 周期性回调 JS 的 updatePlayhead 刷新进度条

按 README.md 的说法,用 Flex SDK 的 mxmlc audiojs.as 命令即可重新编译出 swf。

八、构建与发布:Rakefile 两行搞定

打开 Rakefile,核心就一条命令:

closure --js=audiojs/audio.js --compilation_level=SIMPLE_OPTIMIZATIONS \
  --js_output_file=audiojs/audio.min.js --warning_level=QUIET
  • rake compile → 生成 audiojs/audio.min.js(开头路径正则里的 (\.min)? 正是为了 min 版也能自检测路径)
  • rake release → 按 Manifest 清单打包 5 个文件的发布 zip
  • 而 audiojs/audio.cmd.js 则是把同一套逻辑套进 define.cmd 外壳的 CMD 模块化版本,方便在 SeaJS 体系里按需加载

九、动手验证:6 个演示页

想跑起来其实只需四步(来自 README.md):audio.js、player-graphics.gif、audiojs.swf 放同一目录 → 引入脚本 → audiojs.events.ready(function(){ audiojs.createAll(); }) → 页面里随便写 <audio src="/mp3/xxx.mp3" preload="auto">。

demos/ 下的示例页正好是源码各能力的"验收单":

演示页 验证什么
demos/test1.html 远程 URL / 本地文件 / 加载失败三种 <source> 场景
demos/test2.html 自定义 markup 与 CSS 覆盖默认皮肤
demos/test3.html 多播放器 + preload / loop / autoplay 属性
demos/test5.html 完全自定义的播放器
demos/test6.html 播放列表播放器 / 音量控制

十、值得偷师的 5 个设计点

  1. Shim 而非 polyfill:能用原生就用原生,不能就 Flash 兜底,两条路径共享同一套 UI 与 API
  2. 模板字符串 + 占位符替换:UI markup、CSS、Flash <object> 全部以字符串模板注入,零硬依赖
  3. 轮询补位不可靠的事件:浏览器事件有坑时,用 setInterval 轮询兜底,并用特判照顾 iOS 等设备差异
  4. settings 回调层即扩展面:核心逻辑与用户行为彻底分离,覆写回调就能扩展出播放列表等高级玩法
  5. 自包含部署:库自动探测自身路径、自动注入 CSS,用户只需写一个 <audio> 标签

audiojs 在今天已是历史遗产(现代浏览器对 <audio> 的支持早已完善),但它示范的"双通道降级 + 统一门面 + 回调扩展"套路,至今仍是各类兼容库的通用解法。audiojs/audio.js 这 700 来行代码逻辑清晰、注释详尽,仍是一次非常划算的源码阅读练习。

登录后查看全文
audiojs