HLS视频播放与学习进度追踪系统完整总结

// 前端技术栈
- React + Hooks (功能组件)
- HLS.js (流媒体播放)
- Ant Design (UI组件)
- Zustand (状态管理)
- CryptoJS + SparkMD5 (数据安全)
 
// 核心依赖
import Hls from 'hls.js';
import Md5 from 'js-md5';
import { decrypt, encrypt } from '@/utils/method';

用户选择视频 → 获取视频详情API → 得到m3u8 URL → 
HLS.js处理流媒体 → 片段级进度追踪 → 定时上报学习数据

#EXTM3U                                    # HLS播放列表标识
#EXT-X-VERSION:3                          # HLS版本号
#EXT-X-TARGETDURATION:10                  # 每个片段最大时长
#EXT-X-MEDIA-SEQUENCE:0                   # 媒体序列起始号

# 🔐 加密配置（重要）
#EXT-X-KEY:METHOD=AES-128,URI="/media/video/output/2025-07-31/36805a1e6de411f09a23ac1f6b6a94c5/video.key"

# 视频片段列表
#EXTINF:6.933333,                         # 片段1时长：6.933秒
36805a1e6de411f09a23ac1f6b6a94c50.ts      # 片段1文件
#EXTINF:6.200000,                         # 片段2时长：6.2秒
36805a1e6de411f09a23ac1f6b6a94c51.ts      # 片段2文件
#EXTINF:3.166667,                         # 片段3时长：3.166秒
36805a1e6de411f09a23ac1f6b6a94c52.ts      # 片段3文件

#EXT-X-ENDLIST                            # 播放列表结束标识

时间轴详细分析：

T1: 用户点击视频
T2: API请求 → /api/front/equipment/.../video/1/
T3: 响应包含 → { m3u8: "http://localhost:10001/.../playlist.m3u8" }
T4: HLS.js自动请求 → GET playlist.m3u8
T5: 解析发现加密 → GET video.key (获得: 36805a1e6de411f0)
T6: 开始下载片段 → GET 36805a1e6de411f09a23ac1f6b6a94c50.ts
T7: 解密并播放 → AES-128解密后送入video标签
T8: 预加载下一片段 → GET 36805a1e6de411f09a23ac1f6b6a94c51.ts
...循环直至播放完毕

// video.jsx 核心状态管理
const {
    videoFilter,      // 视频过滤条件
    videoList,        // 视频列表数据
    loading,          // 加载状态
    videoData,        // 当前播放视频的详细数据
    updates,          // 状态更新方法
    getVideoList,     // 获取视频列表API
    getVideoData,     // 获取视频详情API
    getVideoLog,      // 上报学习进度API
} = EquipStore(selector)
 
// 关键的useRef引用
const hlsRef = useRef(null);     // HLS播放器实例
const timesRef = useRef(null);   // 定时器引用
const videoRef = useRef();       // video DOM元素引用

// 第一步：获取视频列表
useDebounceEffect(() => {
    if (id && activeTask.id)
        getVideoList({ 
            url, id, sid: activeTask.equip_practice_subject, 
            tid: activeTask.id, filter: { nopage: 1, search: videoFilter.search } 
        })
}, [videoFilter, activeTask.id], { wait: 200 })
 
// 第二步：选中视频后获取详情
useDebounceEffect(() => {
    if (id && active.id)
        getVideoData({ 
            url, id, sid: activeTask.equip_practice_subject, 
            tid: activeTask.id, vid: active.id 
        })
}, [active.id], { wait: 100 })

const playVideo = (url) => {
    if (Hls.isSupported()) {
        var video = videoRef.current;
        
        // 🎯 关键监听器：视频元数据加载
        const levelLoaded = () => {
            video.addEventListener('loadedmetadata', function () {
                videoStatus.sum_duration = Math.floor(video.duration);
                setVideoStatus({ ...videoStatus })
            });
        }
        
        // 🎯 关键监听器：片段加载完成
        const fragLoaded = (event, data) => {
            let _data = localStorage.getItem('logData') ? 
                JSON.parse(decrypt(localStorage.getItem('logData'))) : {};
            _data[data.frag.relurl] = data.frag.duration;
            localStorage.setItem('logData', encrypt(JSON.stringify(_data)));
        }
        
        // 销毁之前的实例避免内存泄漏
        if (hlsRef.current) {
            hlsRef.current.destroy();
            hlsRef.current.off(Hls.Events.LEVEL_LOADED, levelLoaded);
            hlsRef.current.off(Hls.Events.FRAG_LOADED, fragLoaded)
        }
        
        // 🚀 创建新的HLS实例
        hlsRef.current = new Hls();
        hlsRef.current.loadSource(url);        // 加载m3u8
        hlsRef.current.attachMedia(video);     // 绑定video标签
        hlsRef.current.on(Hls.Events.LEVEL_LOADED, levelLoaded);
        hlsRef.current.on(Hls.Events.FRAG_LOADED, fragLoaded)
    }
}

// fragLoaded事件的真实含义解析
const fragLoaded = (event, data) => {
    // ⚠️  重要澄清：
    // 触发时机 = 片段下载完成（不是用户观看完成）
    // data.frag.duration = 片段文件本身时长（不是用户观看时长）
    
    let _data = localStorage.getItem('logData') ? 
        JSON.parse(decrypt(localStorage.getItem('logData'))) : {};
    
    // 记录片段信息：文件名 → 文件时长
    _data[data.frag.relurl] = data.frag.duration;
    
    // 加密存储防止篡改
    localStorage.setItem('logData', encrypt(JSON.stringify(_data)));
}
 
// 实际存储的数据格式示例
{
    "36805a1e6de411f09a23ac1f6b6a94c50.ts": 6.933333,  // 文件时长6.933秒
    "36805a1e6de411f09a23ac1f6b6a94c51.ts": 6.200000,  // 文件时长6.2秒
    "36805a1e6de411f09a23ac1f6b6a94c52.ts": 3.166667   // 文件时长3.166秒
}
// 系统假设：下载的片段 ≈ 用户观看的内容

// 定时上报：每40秒执行一次
useEffect(() => {
    if (videoData?.m3u8 && videoData?.id) {
        if (!videoData.finish) {
            timesRef.current = setInterval(() => {
                videoLog(videoData.id)  // 上报进度
            }, 1000 * 40);
        }
        playVideo(videoData?.m3u8)
    }
    
    return () => {
        clearInterval(timesRef.current);
        localStorage.removeItem('logData');
    }
}, [videoData.m3u8]);

const videoLog = async (value) => {
    let times = new Date().getTime();
    let data = { 
        timestamp: times,
        video_log: JSON.parse(decrypt(localStorage.getItem('logData'))),
        sum_duration: videoStatus.sum_duration
    };
    
    // 🔐 防篡改签名生成
    let str = `${times}&seclove|@.com|${activeTask.id}M${value}*${JSON.stringify(data.video_log).toString()}%${data.sum_duration.toString()}`;
    data.token = Md5(str);
    
    // 提交到后端验证
    const res = await getVideoLog({ url, id, tid: activeTask.id, vid: value, data });
    res && localStorage.removeItem('logData');  // 成功后清除本地数据
}

// ❌ 系统的错误假设
if (fragmentDownloaded) {
    userActuallyWatched = true;  // 这个等式不成立！
}
 
// ✅ 实际情况
fragmentDownloaded !== userActuallyWatched

// 用户恶意刷课场景
setTimeout(() => video.currentTime = video.duration * 0.25, 1000);  // 跳到25%
setTimeout(() => video.currentTime = video.duration * 0.5, 2000);   // 跳到50%  
setTimeout(() => video.currentTime = video.duration * 0.75, 3000);  // 跳到75%
setTimeout(() => video.currentTime = video.duration, 4000);         // 跳到100%
 
// 结果对比
实际观看时间: 4秒
系统记录时间: 可能15-20分钟（下载的片段总时长）

// HLS.js的预加载行为
用户播放进度: 0-10秒
HLS.js实际下载: 0-30秒的片段（预加载）
系统记录: 用户"学习"了30秒 ← 高估了200%

// 系统无法检测的情况
- 用户是否真的在看屏幕？
- 用户是否调整了播放速度？
- 用户是否暂停后离开？
- 用户是否在其他标签页？
- 用户是否重复播放某段？

// ✅ 推荐：上传后立即切片
管理员上传视频 → 后台异步切片 → 用户观看时直接播放
 
// ❌ 不推荐：观看时切片  
用户点击播放 → 后台开始切片 → 用户等待 → 延迟巨大

@Service
public class VideoService {
    
    @Async
    public CompletableFuture<Void> processVideo(Long videoId, String originalPath) {
        try {
            // 生成随机加密密钥
            String encryptionKey = generateEncryptionKey();
            String keyFilePath = outputDir + "/video.key";
            
            // FFmpeg HLS切片命令
            String[] ffmpegCmd = {
                "ffmpeg", "-i", originalPath,
                "-c:v", "libx264",              // H.264编码
                "-c:a", "aac",                  // AAC音频编码
                "-f", "hls",                    // HLS格式输出
                "-hls_time", "10",              // 每片10秒
                "-hls_list_size", "0",          // 保存所有片段
                "-hls_key_info_file", keyInfoFile,  // 加密配置
                "-hls_segment_filename", outputDir + "/" + videoId + "%d.ts",
                outputDir + "/playlist.m3u8"
            };
            
            // 执行FFmpeg命令
            ProcessBuilder pb = new ProcessBuilder(ffmpegCmd);
            Process process = pb.start();
            int exitCode = process.waitFor();
            
            if (exitCode == 0) {
                updateVideoStatus(videoId, "READY");
            }
        } catch (Exception e) {
            updateVideoStatus(videoId, "ERROR");
        }
    }
}

const ffmpeg = require('fluent-ffmpeg');
 
async processVideo(videoId, originalPath) {
    const outputDir = path.join(this.outputPath, videoId);
    
    return new Promise((resolve, reject) => {
        ffmpeg(originalPath)
            .videoCodec('libx264')
            .audioCodec('aac')
            .format('hls')
            .addOption('-hls_time', '10')
            .addOption('-hls_list_size', '0')
            .addOption('-hls_key_info_file', keyInfoPath)
            .output(path.join(outputDir, 'playlist.m3u8'))
            .on('end', () => {
                console.log(`视频切片完成: ${videoId}`);
                resolve();
            })
            .on('error', reject)
            .run();
    });
}

/output/video123/
├── playlist.m3u8           # HLS播放列表
├── video.key              # AES-128加密密钥  
├── key.info               # FFmpeg密钥配置文件
├── video123_0.ts          # 第1个视频片段(0-10秒)
├── video123_1.ts          # 第2个视频片段(10-20秒)
├── video123_2.ts          # 第3个视频片段(20-30秒)
└── ...                    # 更多片段

// HLS播放器实例管理
if (hlsRef.current) {
    hlsRef.current.destroy();                              // 销毁实例
    hlsRef.current.off(Hls.Events.LEVEL_LOADED, levelLoaded);  // 移除监听器
    hlsRef.current.off(Hls.Events.FRAG_LOADED, fragLoaded);    // 移除监听器
}
 
// 定时器清理
useEffect(() => {
    return () => {
        clearInterval(timesRef.current);
        localStorage.removeItem('logData');
    }
}, [videoData.m3u8]);

// 三重安全保护
1. 本地存储加密: encrypt(JSON.stringify(data))
2. MD5签名验证: Md5(`${timestamp}&seclove|@.com|${taskId}M${videoId}*${logData}%${duration}`)
3. 服务端签名对比: 防止客户端数据篡改

// ✅ 适合场景
- 内部培训系统（信任度较高）
- 粗粒度进度追踪需求
- 资源有限的快速开发项目
- 防止完全不学习的基础检测
 
// ❌ 不适合场景  
- 严格的在线考试认证
- 精确计费的付费课程
- 高价值内容的版权保护
- 需要精确学习分析的教育平台

// 1. 播放进度追踪（替代下载进度）
video.addEventListener('timeupdate', () => {
    recordActualPlaybackProgress(video.currentTime);
});
 
// 2. 用户行为检测
document.addEventListener('visibilitychange', () => {
    if (document.hidden) pauseLearningRecord();
});
 
video.addEventListener('seeking', () => {
    recordSeekBehavior(video.currentTime);
});
 
// 3. 随机知识点检测
setInterval(() => {
    if (shouldShowQuiz()) showInteractiveQuiz();
}, getRandomInterval());
 
// 4. 播放速度限制
video.addEventListener('ratechange', () => {
    if (video.playbackRate > maxAllowedRate) {
        showSpeedWarning();
        video.playbackRate = maxAllowedRate;
    }
});

// 1. 多分辨率适配
ffmpeg -i input.mp4 \
  -map 0:v:0 -map 0:a:0 -s:v:0 1920x1080 -c:v:0 libx264 -b:v:0 5000k \
  -map 0:v:0 -map 0:a:0 -s:v:1 1280x720 -c:v:1 libx264 -b:v:1 2800k \
  -map 0:v:0 -map 0:a:0 -s:v:2 854x480 -c:v:2 libx264 -b:v:2 1400k \
  -f hls -var_stream_map "v:0,a:0 v:1,a:1 v:2,a:2" \
  -master_pl_name master.m3u8 \
  stream_%v/playlist.m3u8
 
// 2. 切片时长优化
普通内容: 10秒片段（平衡加载速度与seek精度）
直播内容: 2-4秒片段（降低延迟）
长视频: 15-30秒片段（减少文件数量）
 
// 3. 预切片策略
上传完成 → 立即生成480p版本 → 后台异步生成高清版本

// CDN配置
video.key        → CDN缓存1小时（安全考虑）
playlist.m3u8    → CDN缓存30秒（支持实时更新）
*.ts片段         → CDN缓存7天（长期缓存）
 
// Nginx配置示例
location ~* \.(m3u8)$ {
    expires 30s;
    add_header Cache-Control "public, no-transform";
}
 
location ~* \.(ts)$ {
    expires 7d;
    add_header Cache-Control "public, immutable";
}

// video.jsx 第104-109行：关键代码分析
const levelLoaded = () => {
    video.addEventListener('loadedmetadata', function () {
        // 🎯 关键：video.duration 是 HTML5 video 元素的原生属性
        // 表示整个视频的总时长（单位：秒）
        videoStatus.sum_duration = Math.floor(video.duration);
        setVideoStatus({ ...videoStatus })
    });
}

// HLS.js 的工作流程：
// 1. loadSource(m3u8_url) → 请求 playlist.m3u8
// 2. 解析 m3u8 文件 → 计算所有片段的总时长
// 3. 触发 LEVEL_LOADED 事件 → video.duration 被设置
// 4. 触发 loadedmetadata 事件 → sum_duration 被记录
 
// 例如 m3u8 文件内容：
#EXTINF:6.933333,    // 片段1：6.933秒
segment1.ts
#EXTINF:6.200000,    // 片段2：6.2秒  
segment2.ts
#EXTINF:3.166667,    // 片段3：3.166秒
segment3.ts
 
// HLS.js 自动计算：6.933 + 6.2 + 3.166 + ... = 总时长
// 最终 video.duration = 1800（假设30分钟的视频）

// video.jsx 第128-155行：videoLog 函数中的使用
const videoLog = async (value) => {
    let times = new Date().getTime();
    let data = JSON.parse(JSON.stringify(videoStatus));
    data.timestamp = times;
    
    // 获取已观看的片段记录
    data.video_log = localStorage.getItem('logData') ? 
        JSON.parse(decrypt(localStorage.getItem('logData'))) : {};
    
    // 🔐 生成防篡改签名（sum_duration 作为签名的一部分）
    let str = `${times}&seclove|@.com|${activeTask.id}M${value}*${JSON.stringify(data.video_log).toString()}%${data.sum_duration.toString()}`;
    data.token = Md5(str);
    
    // 发送给后端的完整数据
    const res = await getVideoLog({
        url,
        id: id,
        tid: activeTask.id,
        vid: value,
        data: {
            timestamp: times,
            video_log: { /* 片段观看记录 */ },
            sum_duration: 1800,  // ← 整个视频的总时长（秒）
            token: "abc123..."   // MD5签名
        }
    })
}

// 发送给后端的数据结构：
{
    timestamp: 1641234567890,
    
    // 🎥 用户实际观看的片段（下载完成的片段）
    video_log: {
        "36805a1e6de411f09a23ac1f6b6a94c50.ts": 6.933333,   // 片段1
        "36805a1e6de411f09a23ac1f6b6a94c51.ts": 6.200000,   // 片段2
        "36805a1e6de411f09a23ac1f6b6a94c52.ts": 3.166667,   // 片段3
        // ... 其他下载的片段
        // 总计可能：约300秒（5分钟的片段）
    },
    
    // 📏 整个视频的总长度
    sum_duration: 1800,  // 30分钟 = 1800秒（这是固定值）
    
    token: "a1b2c3d4..."  // 基于上述数据生成的MD5签名
}

// 后端的计算逻辑（伪代码）
function calculateProgress(video_log, sum_duration) {
    // 1. 计算用户"观看"的片段总时长
    const watchedDuration = Object.values(video_log)
        .reduce((total, segmentDuration) => total + segmentDuration, 0);
    
    // 2. 计算进度百分比
    const progressPercentage = (watchedDuration / sum_duration) * 100;
    
    // 示例计算：
    // watchedDuration = 300秒（5分钟的片段）
    // sum_duration = 1800秒（30分钟总长）
    // progress = (300 / 1800) * 100 = 16.67%
    
    return {
        watched_seconds: watchedDuration,    // 300
        total_seconds: sum_duration,         // 1800  
        progress_percentage: progressPercentage  // 16.67
    };
}

// 后端验证签名的逻辑
function verifyToken(data, taskId, videoId) {
    const { timestamp, video_log, sum_duration, token } = data;
    
    // 使用相同算法重新计算签名
    const expectedStr = `${timestamp}&seclove|@.com|${taskId}M${videoId}*${JSON.stringify(video_log)}%${sum_duration}`;
    const expectedToken = md5(expectedStr);
    
    // 对比签名
    if (token !== expectedToken) {
        throw new Error('数据被篡改！');
    }
    
    // sum_duration 在这里的作用：
    // 1. 作为签名的一部分，防止客户端修改视频总时长
    // 2. 用于计算准确的学习进度百分比
    // 3. 检测异常数据（如观看时长超过视频总长）
    
    return true;
}

// sum_duration 的核心价值：
 
// 1. 📊 进度计算基准
进度 = 已观看片段时长 / 视频总时长
 
// 2. 🔐 数据完整性保证  
签名包含总时长 → 防止客户端伪造视频长度
 
// 3. 🚨 异常检测依据
if (已观看时长 > 视频总时长) {
    // 检测到异常，可能存在刷课行为
}
 
// 4. 📱 前端显示支持
播放器进度条 = 当前播放位置 / sum_duration