# HLS视频分割与加密工具

**Repository Path**: ErGeAnan/hls-video-tool

## Basic Information

- **Project Name**: HLS视频分割与加密工具
- **Description**: 该工具基于 FFmpeg 实现 MP4 视频到 HLS（m3u8+ts）格式的分割，提供普通分割和 AES-128 加密分割两种模式，内置音视频同步保障机制，适用于视频点播（VOD）场景。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-07
- **Last Updated**: 2026-01-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HLS视频分割与加密工具

该工具基于FFmpeg实现MP4视频到HLS（m3u8+ts）格式的分割，提供普通分割和AES-128加密分割两种模式，内置音视频同步保障机制，适用于视频点播（VOD）场景。

## 功能特性
- 🎬 普通HLS分割：将MP4视频分割为标准未加密的m3u8索引文件+ts分片文件
- 🔐 加密HLS分割：基于AES-128算法对HLS分片进行加密，保护视频内容
- 🎵 音视频同步：通过FFmpeg参数强制分片独立，确保音视频时序一致
- 📝 完善日志：实时输出执行日志，便于问题定位与排查
- ✅ 前置检查：自动校验FFmpeg安装状态、输入文件/密钥文件存在性

## 环境要求
1. **FFmpeg**：需安装并配置到系统环境变量
   - 下载地址：https://ffmpeg.org/download.html
   - 验证安装：执行 `ffmpeg -version` 能正常输出版本信息
2. **Python**：3.6及以上版本
3. **OpenSSL**：加密模式必备，用于生成16字节AES-128密钥
4. **依赖文件**（加密模式专用）：需手动创建16字节密钥文件和密钥信息配置文件

## 工具安装指南
### 1. FFmpeg安装
#### Windows系统
- 下载对应版本：https://github.com/BtbN/FFmpeg-Builds/releases
- 解压到指定目录（如 `D:\ffmpeg`）
- 将 `ffmpeg/bin` 路径添加到系统环境变量 `PATH`
- 验证：打开CMD执行 `ffmpeg -version`

#### Linux系统（Ubuntu/Debian）
```bash
sudo apt update
sudo apt install ffmpeg -y
```

#### MacOS系统
```bash
# 需先安装Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装FFmpeg
brew install ffmpeg
```

### 2. OpenSSL安装（加密模式必备）
#### Windows系统
- 下载地址：https://slproweb.com/products/Win32OpenSSL.html
- 选择对应版本（如 `Win64 OpenSSL v3.2.0 Light`）
- 安装时勾选 "Copy OpenSSL DLLs to the Windows System directory"
- 验证：打开CMD执行 `openssl version`

#### Linux系统（Ubuntu/Debian）
```bash
sudo apt update
sudo apt install openssl -y
```

#### MacOS系统
```bash
brew install openssl
# 配置环境变量（可选）
echo 'export PATH="/usr/local/opt/openssl/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
验证安装：执行 `openssl version` 能正常输出版本信息

## 文件说明
| 文件名 | 功能描述 |
|--------|----------|
| `main.py` | 普通HLS分割核心脚本，输出未加密的m3u8+ts文件 |
| `main encryption.py` | 加密HLS分割核心脚本，输出AES-128加密的HLS格式文件 |
| `verifykey.py` | 密钥验证脚本，校验enc.key文件是否为AES-128要求的16字节 |
| `key_info.txt` | 加密密钥信息配置文件（需手动创建），指定密钥路径、URI、IV |
| `enc.key` | AES-128加密密钥文件（需手动创建），必须为16字节二进制文件 |

## 快速开始

### 1. 通用前置准备
- 将待处理的MP4视频文件放在脚本同级目录，默认命名为`input.mp4`（也可修改脚本内配置）
- 确认FFmpeg已正确安装并配置环境变量（执行`ffmpeg -version`验证）

### 2. 普通HLS分割（无加密）
#### 执行命令
```bash
python main.py
```

#### 配置修改（可选）
在`main.py`的`__main__`区域调整参数：
```python
INPUT_VIDEO = "input.mp4"    # 输入视频文件路径
SEGMENT_TIME = 2             # 每个ts分片时长（秒）
OUTPUT_DIR = "hls"           # 输出目录名
```

#### 输出结果
执行完成后，`hls`目录下会生成：
- `output.m3u8`：HLS索引文件
- `index1.ts`、`index2.ts`...：视频分片文件

### 3. 加密HLS分割（AES-128）
#### 步骤1：创建16字节加密密钥
```bash
# Linux/Mac系统
openssl rand 16 > enc.key

# Windows系统（需安装OpenSSL）
openssl rand 16 -out enc.key
```

#### 步骤2：验证密钥有效性
```bash
python verifykey.py
```
- 若密钥长度不为16字节，会抛出`ValueError`异常
- 无报错则表示密钥有效

#### 步骤3：创建密钥信息文件
新建`key_info.txt`文件，内容格式如下：
```
enc.key            # 本地密钥文件路径
enc.key            # 播放器访问密钥的URI路径
<16进制IV值>       # 初始化向量（示例：1234567890abcdef1234567890abcdef）
```

#### 步骤4：执行加密分割
```bash
python "main encryption.py"
```

#### 配置修改（可选）
在`main encryption.py`的`__main__`区域调整参数：
```python
INPUT_VIDEO = "input.mp4"    # 输入视频文件路径
SEGMENT_TIME = 2             # 每个ts分片时长（秒）
OUTPUT_DIR = "hls_encryption" # 输出目录名
KEY_INFO_FILE = "key_info.txt" # 密钥信息文件路径
```

#### 输出结果
执行完成后，`hls_encryption`目录下会生成加密后的m3u8索引文件和ts分片文件。

## 核心实现说明

### 普通分割核心参数（FFmpeg）
```python
ffmpeg_cmd = [
    "ffmpeg",
    "-i", input_file,                  # 输入文件
    "-c:v", "libx264",                 # H.264视频编码
    "-c:a", "aac",                     # AAC音频编码
    "-b:a", "128k",                    # 音频码率（保证音频质量）
    "-hls_time", str(segment_time),    # 分片时长
    "-hls_list_size", "0",             # 保留所有分片（VOD场景）
    "-hls_segment_filename", os.path.join(output_dir, "index%d.ts"),  # 分片命名规则
    "-hls_flags", "independent_segments",  # 强制分片独立，保障音视频同步
    "-y",                              # 覆盖已有输出文件
    os.path.join(output_dir, "output.m3u8") # 输出m3u8文件
]
```

### 加密分割核心参数（FFmpeg）
在普通分割基础上增加加密相关配置：
```python
ffmpeg_cmd = [
    # 基础编码参数（同普通分割）
    "ffmpeg", "-i", input_file, "-c:v", "libx264", "-preset", "fast", "-crf", "23",
    "-g", "48", "-keyint_min", "48", "-sc_threshold", "0", "-c:a", "aac", "-b:a", "128k",
    # HLS分片参数
    "-hls_time", str(segment_time), "-hls_list_size", "0", 
    "-hls_segment_filename", os.path.join(output_dir, "index%d.ts"),
    "-hls_playlist_type", "vod", "-hls_flags", "independent_segments",
    # 加密核心参数
    "-hls_key_info_file", key_info_file,
    # 输出配置
    "-y", os.path.join(output_dir, "output.m3u8")
]
```

## 常见问题排查

### Q1: FFmpeg执行失败，返回码非0
- 检查FFmpeg是否正确配置到系统环境变量
- 确认输入视频文件路径正确且文件未损坏
- 查看日志输出，定位具体错误（如编码不支持、权限不足）

### Q2: 加密后播放器无法加载视频
- 校验`key_info.txt`格式是否符合要求（三行内容：密钥路径、密钥URI、IV）
- 执行`verifykey.py`确认`enc.key`为16字节
- 确保播放器支持AES-128加密的HLS格式
- 检查m3u8文件中`EXT-X-KEY`字段是否正确生成

### Q3: 音视频不同步
- 确认`-hls_flags independent_segments`参数已启用
- 加密模式下检查`-g`（GOP大小）和`-keyint_min`参数配置（默认48）
- 验证输入MP4文件本身是否存在音视频不同步问题

### Q4: OpenSSL命令执行失败
- Windows：确认OpenSSL已安装且添加到环境变量
- Linux/Mac：执行 `which openssl` 确认安装路径
- 重新安装OpenSSL并验证版本（`openssl version`）

## 自定义扩展

### 调整视频质量（加密模式）
修改`main encryption.py`中FFmpeg命令的以下参数：
```python
"-crf", "23",          # 视频质量，值越小质量越高（18-28为合理范围）
"-preset", "fast",     # 编码速度，可选：ultrafast, fast, medium, slow等
```

### 修改分片时长
调整脚本中`SEGMENT_TIME`参数，建议取值范围2-10秒（符合HLS标准推荐）。

### 自定义输出路径
将`OUTPUT_DIR`修改为绝对路径，示例：
```python
OUTPUT_DIR = "/home/user/videos/hls_output"  # Linux/Mac
# 或
OUTPUT_DIR = "D:/videos/hls_output"          # Windows
```

## 许可证
本项目仅用于学习和研究目的，使用时请遵守相关法律法规及视频版权保护规定。