HLS m3u8 流媒体播放支持

什么是 HLS

HLS（HTTP Live Streaming）是苹果推出的流媒体协议。音频和视频被切分成很短的 TS 分片文件，通过一个 .m3u8 索引文件来组织播放顺序。常见的用途包括网络电台、音乐直播、音频点播等。

浏览器原生对 HLS 的支持有限：

Safari：原生支持（可以直接给 <audio> 标签一个 .m3u8 URL）
Chrome / Firefox / Edge：不原生支持，需要 hls.js

APlayer 通过配合 hls.js 来实现跨浏览器的 HLS 支持。

前置条件

必须在 APlayer 之前加载 hls.js：

<!-- 顺序很重要：hls.js → APlayer -->
<script src="hls.min.js"></script>
<script src="APlayer.min.js"></script>

如果用 npm：

import Hls from 'hls.js';
import APlayer from 'APlayer';

// 需要把 Hls 挂载到全局，APlayer 内部检测的是 window.Hls
window.Hls = Hls;

方式一：type: 'hls'（最简单）

在 audio.type 字段里声明 'hls'：

const ap = new APlayer({
    container: document.getElementById('aplayer'),
    audio: [{
        name: '网络电台',
        artist: '直播流',
        url: 'your-radio.m3u8',
        cover: 'cover.jpg',
        type: 'hls'
    }]
});

APlayer 内部会自动创建 Hls 实例、加载 m3u8、挂载到 audio 元素上。

方式二：customAudioType（最灵活）

如果你需要更精细的控制（比如自定义 HLS 配置、错误处理、多清晰度切换等），可以使用 customAudioType：

const ap = new APlayer({
    container: document.getElementById('aplayer'),
    audio: [{
        name: '网络电台',
        artist: '直播流',
        url: 'your-radio.m3u8',
        cover: 'cover.jpg',
        type: 'customHls'  // 自定义类型名
    }],
    customAudioType: {
        'customHls': function(audioElement, audio, player) {
            if (Hls.isSupported()) {
                const hls = new Hls({
                    // hls.js 的配置项
                    lowLatencyMode: true
                });
                hls.loadSource(audio.url);
                hls.attachMedia(audioElement);

                // 可选：错误处理
                hls.on(Hls.Events.ERROR, function(event, data) {
                    if (data.fatal) {
                        switch (data.type) {
                            case Hls.ErrorTypes.NETWORK_ERROR:
                                hls.startLoad();
                                break;
                            case Hls.ErrorTypes.MEDIA_ERROR:
                                hls.recoverMediaError();
                                break;
                            default:
                                hls.destroy();
                                break;
                        }
                    }
                });
            } else if (
                audioElement.canPlayType('application/x-mpegURL') ||
                audioElement.canPlayType('application/vnd.apple.mpegURL')
            ) {
                // Safari 原生支持
                audioElement.src = audio.url;
            } else {
                player.notice('错误：当前浏览器不支持 HLS 流媒体', 3000);
            }
        }
    }
});

回调函数的三个参数：

audioElement：原生 HTMLAudioElement
audio：audio 配置对象
player：APlayer 实例本身

Safari 原生支持

Safari 不需要 hls.js——它原生支持 m3u8。如果你只需要支持 Safari，可以直接给 audio.url 一个 .m3u8 地址，不用设置 type: 'hls'。

但如果你同时需要支持 Chrome / Firefox / Edge，还是应该加载 hls.js。

HLS 直播流 vs 点播流

HLS 可以做直播也可以做点播。APlayer + hls.js 两种都支持：

直播流（live）：持续不断的音频，没有结尾。播放到末尾不会触发 ended 事件，而是一直等待新分片
点播流（VOD）：完整音频被切成 TS 分片，有开头和结尾。播完后触发 ended 事件

常见问题

"Error: HLS is not supported"

这是 type: 'hls' 或你的 customAudioType 检测到当前环境不支持。检查：

hls.js 是否在 APlayer 之前加载
控制台有没有报错
Hls.isSupported() 是否返回 true

m3u8 加载失败

检查 m3u8 URL 是否能直接在浏览器打开
检查 CORS 头（跨域 m3u8 需要服务端返回正确的 Access-Control-Allow-Origin）
检查 m3u8 文件内部引用的 TS 分片 URL 是否正确

TS 分片加载超时

网络问题。hls.js 有内置的重试机制，如果持续超时会触发 Hls.ErrorTypes.NETWORK_ERROR。在 customAudioType 里监听这个错误并调用 hls.startLoad() 可以恢复。

不支持的格式

HLS 不是万能的——它只能承载浏览器原生支持的音频编码。最常见的是：

AAC（最常用）
MP3
Opus（部分浏览器）