M3U8Merge SDK 使用文档

一个高性能的 M3U8 视频流下载和合并工具，支持加密解密、并发下载和自动重试功能。

特性

• 🚀 高性能并发下载
• 🔐 支持 AES-128 加密视频解密
• 🛡️ 智能重试机制
• 📊 实时下载进度监控
• 🔄 自动选择最优下载方法
• 💾 支持本地文件和网络 URL

安装

作为依赖安装

1yarn add m3u8merge
2# 或
3npm install m3u8merge

快捷使用（无需安装）

1npx m3u8merge -f your_file.m3u8 -o output.mp4

前置要求

确保系统已安装 FFmpeg：

macOS:

1brew install ffmpeg

Windows: 下载 FFmpeg 并添加到系统 PATH

Linux:

1# Ubuntu/Debian
2sudo apt update && sudo apt install ffmpeg
3
4# CentOS/RHEL
5sudo yum install ffmpeg

命令行使用

基本语法

1npx m3u8merge -f <输入文件> -o <输出文件>

使用本地 M3U8 文件

1npx m3u8merge -f ./video.m3u8 -o merged_video.mp4

使用网络 URL

1npx m3u8merge -f "https://example.com/video.m3u8" -o output.mp4

参数说明

• -f, --file: 输入的 M3U8 文件路径或 URL（必需）
• -o, --output: 输出视频文件路径（可选，默认使用输入文件名）

SDK 编程接口

导入模块

1import M3U8Parser from 'm3u8merge';
2
3// 创建解析器实例
4const parser = new M3U8Parser();

核心接口

1. 解析 M3U8 文件

1// 从本地文件解析
2const links = parser.parseFromFile('./video.m3u8');
3
4// 从字符串内容解析
5const m3u8Content = `#EXTM3U
6#EXT-X-VERSION:3
7#EXTINF:10.0,
8segment1.ts
9#EXTINF:10.0,
10segment2.ts`;
11const links = parser.parseFromString(m3u8Content);

2. 处理本地文件到视频

1const success = await parser.processFileToVideo(
2  './video.m3u8',           // M3U8 文件路径
3  './output.mp4',           // 输出视频路径
4  './temp_segments',        // 临时目录（可选）
5  {                         // 配置选项（可选）
6    keepTempFiles: false,
7    videoCodec: 'copy',
8    audioCodec: 'copy',
9    maxConcurrent: 20,
10    retryCount: 3
11  }
12);

3. 处理网络 URL 到视频

1const success = await parser.processUrlToVideo(
2  'https://example.com/video.m3u8',  // M3U8 URL
3  './output.mp4',                    // 输出视频路径
4  './temp_segments',                 // 临时目录（可选）
5  {                                  // 配置选项（可选）
6    maxConcurrent: 15,
7    retryCount: 5,
8    downloadMethod: 'auto'
9  }
10);

配置选项

MergeOptions 接口

1interface MergeOptions {
2  outputPath: string;         // 输出文件路径
3  tempDir: string;           // 临时目录
4  keepTempFiles: boolean;    // 是否保留临时文件
5  videoCodec?: string;       // 视频编码器 ('copy', 'libx264', 等)
6  audioCodec?: string;       // 音频编码器 ('copy', 'aac', 等)
7  quality?: string;          // 视频质量 (CRF值，如 '23')
8  maxConcurrent?: number;    // 最大并发数 (5-30)
9  retryCount?: number;       // 重试次数 (1-10)
10  downloadMethod?: 'undici' | 'curl' | 'auto'; // 下载方法
11}

实用方法

显示统计信息

1parser.showStatistics();
2// 输出：
3// 📊 解析统计信息
4// ================
5// 总片段数量: 100
6// 总时长: 16:40
7// 平均片段时长: 10.00 秒

导出链接列表

1parser.exportLinks('./links.txt');

打印所有链接

1// 简单列表
2parser.printAllLinks();
3
4// 详细信息
5parser.printAllLinks(true);

高级用法

自定义下载配置

1const parser = new M3U8Parser();
2
3// 高质量转码配置
4const success = await parser.processFileToVideo(
5  './video.m3u8',
6  './output_hq.mp4',
7  './temp',
8  {
9    keepTempFiles: false,
10    videoCodec: 'libx264',      // 重新编码
11    audioCodec: 'aac',          // 音频转码
12    quality: '18',              // 高质量 (CRF)
13    maxConcurrent: 10,          // 保守的并发数
14    retryCount: 5
15  }
16);

处理加密视频

1// SDK 会自动检测和处理 AES-128 加密
2const success = await parser.processUrlToVideo(
3  'https://encrypted-stream.com/video.m3u8',
4  './decrypted_video.mp4'
5);
6// 自动下载密钥并解密片段

并发下载调优

1// 高速网络配置
2const highSpeedConfig = {
3  maxConcurrent: 30,          // 高并发
4  retryCount: 3,
5  downloadMethod: 'undici'    // 高性能方法
6};
7
8// 稳定性优先配置
9const stableConfig = {
10  maxConcurrent: 8,           // 低并发
11  retryCount: 10,
12  downloadMethod: 'curl'      // 稳定方法
13};

错误处理

1try {
2  const success = await parser.processUrlToVideo(
3    'https://example.com/video.m3u8',
4    './output.mp4'
5  );
6
7  if (success) {
8    console.log('✅ 视频处理成功');
9  } else {
10    console.log('❌ 视频处理失败');
11  }
12} catch (error) {
13  console.error('处理过程中发生错误:', error.message);
14}

性能优化建议

1. 并发数调优

• 高速网络: maxConcurrent: 20-30
• 普通网络: maxConcurrent: 10-15
• 不稳定网络: maxConcurrent: 5-10

2. 下载方法选择

• auto: 自动选择最优方法（推荐）
• undici: Node.js 原生，高性能
• curl: 系统工具，稳定性好

3. 编码设置

• 快速合并: videoCodec: 'copy', audioCodec: 'copy'
• 质量优化: videoCodec: 'libx264', quality: '18-23'
• 文件大小优化: quality: '28-32'

常见问题

Q: 下载失败率很高怎么办？

A: 尝试降低并发数或更换下载方法：

1{
2  maxConcurrent: 5,
3  retryCount: 10,
4  downloadMethod: 'curl'
5}

Q: 如何处理需要特殊请求头的 M3U8？

A: 目前 SDK 内置了常用的请求头，如需自定义，请提交 Issue。

Q: 支持哪些视频格式？

A: 支持所有 FFmpeg 支持的格式，输出推荐使用 .mp4。

许可证

MIT License

---

注意: 请确保遵守相关版权法律，仅下载和使用您有权访问的内容。