播放器参数配置

本文档详细列出HLS流媒体播放器的所有可配置参数，包括初始化参数、URL参数、播放控制方法和事件监听，帮助你定制播放器行为。

初始化参数

播放器初始化时可配置的参数，通过TCPlayer构造函数传入：

// 完整初始化示例
var hlsPlayer = TCPlayer('hls-player', {
    sources: [{
        src: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8',
        type: 'application/x-mpegURL'
    }],
    autoplay: false,
    controls: true,
    width: '100%',
    height: '480px',
    preload: 'metadata',
    poster: 'https://example.com/poster.jpg',
    muted: false,
    loop: false,
    live: false,
    playbackRate: [0.5, 1, 1.5, 2],
    volume: 0.8,
    playbackQuality: 'auto'
});

核心参数列表

参数名	类型	默认值	说明
sources	Array	[]	播放源配置，包含src（地址）和type（类型）
autoplay	Boolean	false	是否自动播放，移动端需配合muted=true
controls	Boolean	true	是否显示控制栏
width	String/Number	'100%'	播放器宽度，支持百分比或像素值
height	String/Number	'480px'	播放器高度，支持百分比或像素值
preload	String	'metadata'	预加载策略：none/metadata/auto
poster	String	''	封面图地址，播放前显示
muted	Boolean	false	是否静音播放
loop	Boolean	false	是否循环播放
live	Boolean	false	是否为直播流
volume	Number	0.8	初始音量，0-1之间
playbackRate	Array	[0.5,1,1.5,2]	倍速播放选项

URL参数

嵌入播放器时可通过URL参数配置，适用于iframe嵌入场景：

// 示例：https://hls-vedio.pages.dev/?url=https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8&autoplay=1&muted=1

参数名	取值	说明
url	M3U8地址	必填，流媒体播放地址
autoplay	1/0	是否自动播放，默认0
controls	1/0	是否显示控制栏，默认1
muted	1/0	是否静音，默认0
loop	1/0	是否循环播放，默认0
poster	图片URL	封面图地址

播放控制方法

播放器实例提供的控制方法，可动态控制播放行为：

基础控制

// 播放/暂停
hlsPlayer.play();      // 播放
hlsPlayer.pause();     // 暂停
hlsPlayer.togglePlay();// 切换播放/暂停

// 音量控制
hlsPlayer.setVolume(0.5); // 设置音量（0-1）
hlsPlayer.getVolume();    // 获取当前音量
hlsPlayer.mute();         // 静音
hlsPlayer.unmute();       // 取消静音
hlsPlayer.toggleMute();   // 切换静音状态

// 进度控制
hlsPlayer.setCurrentTime(60); // 设置播放位置（秒）
hlsPlayer.getCurrentTime();   // 获取当前播放位置
hlsPlayer.duration();         // 获取视频总时长

// 倍速控制
hlsPlayer.setPlaybackRate(1.5); // 设置倍速
hlsPlayer.getPlaybackRate();    // 获取当前倍速

// 全屏控制
hlsPlayer.requestFullscreen(); // 进入全屏
hlsPlayer.exitFullscreen();    // 退出全屏
hlsPlayer.isFullscreen();      // 判断是否全屏

// 源切换
hlsPlayer.src('https://new-stream-url.m3u8'); // 切换播放源
hlsPlayer.load();                             // 重新加载

事件监听

监听播放器事件，实现自定义业务逻辑：

// 事件监听示例
// 播放事件
hlsPlayer.on('play', function() {
    console.log('开始播放');
});

// 暂停事件
hlsPlayer.on('pause', function() {
    console.log('暂停播放');
});

// 播放结束
hlsPlayer.on('ended', function() {
    console.log('播放结束');
});

// 进度更新
hlsPlayer.on('timeupdate', function() {
    var currentTime = hlsPlayer.getCurrentTime();
    console.log('当前播放位置：', currentTime);
});

// 错误监听
hlsPlayer.on('error', function(e) {
    console.error('播放错误：', e);
    alert('播放出错，请检查地址是否正确');
});

// 加载完成
hlsPlayer.on('loadedmetadata', function() {
    console.log('元数据加载完成，时长：', hlsPlayer.duration());
});

// 全屏切换
hlsPlayer.on('fullscreenchange', function(isFullscreen) {
    console.log('全屏状态：', isFullscreen);
});

配置示例

示例1：直播流配置

// 直播流专用配置
var livePlayer = TCPlayer('hls-player', {
    sources: [{ src: 'https://live-stream-url.m3u8', type: 'application/x-mpegURL' }],
    autoplay: true,
    muted: true,
    controls: true,
    live: true,
    width: '100%',
    height: '480px',
    liveSyncDuration: 3, // 直播同步时长
    preload: 'auto'
});

示例2：自定义控制栏

// 隐藏默认控制栏，自定义控制逻辑
var customPlayer = TCPlayer('hls-player', {
    sources: [{ src: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8', type: 'application/x-mpegURL' }],
    autoplay: false,
    controls: false, // 隐藏默认控制栏
    width: '100%',
    height: '480px'
});

// 自定义播放按钮
$('#custom-play-btn').click(function() {
    customPlayer.play();
});

// 自定义暂停按钮
$('#custom-pause-btn').click(function() {
    customPlayer.pause();
});

// 自定义音量控制
$('#volume-slider').on('input', function() {
    customPlayer.setVolume(parseFloat($(this).val()));
});

示例3：错误处理和自动重试

// 带自动重试的播放器配置
var retryCount = 0;
var maxRetries = 3;

function initPlayer() {
    var player = TCPlayer('hls-player', {
        sources: [{ src: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8', type: 'application/x-mpegURL' }],
        autoplay: false,
        controls: true
    });

    // 错误处理和自动重试
    player.on('error', function(e) {
        console.error('播放错误：', e);
        if (retryCount < maxRetries) {
            retryCount++;
            alert('播放出错，正在重试（' + retryCount + '/' + maxRetries + '）');
            setTimeout(function() {
                player.src(player.currentSrc());
                player.load();
                player.play();
            }, 2000);
        } else {
            alert('多次重试失败，请检查网络或播放地址');
        }
    });

    return player;
}

// 初始化播放器
var hlsPlayer = initPlayer();