# m3u8

**Repository Path**: clig/m3u8

## Basic Information

- **Project Name**: m3u8
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-27
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# m3u8_tool

一个简单易用的 Python 命令行工具，集三种常用 M3U8 操作于一身：

| 子命令 | 功能 |
| --- | --- |
| `download-mp4` | 下载 m3u8 视频并合并为单个 `.mp4` 文件 |
| `download-ts` | 下载 m3u8 的所有 `.ts` 切片 + 生成可本地播放的 `index.m3u8` |
| `make-hls` | 把本地视频文件切片为 `.ts` 并生成 `index.m3u8` |

---

## 1. 安装

要求 Python 3.8+，**只需一条命令**：

```powershell
pip install requests imageio-ffmpeg
```

说明：
- `requests` —— HTTP 下载切片
- `imageio-ffmpeg` —— 自动下载并管理 `ffmpeg` 二进制（首次使用时下载到用户目录，约 70MB），**无需手动安装 ffmpeg、无需配置 PATH**。

> 如果系统 PATH 里已经有 `ffmpeg`，脚本会优先用 `imageio-ffmpeg` 提供的版本；找不到时再回退系统的。两者都没有时会给出友好的安装提示。

---

## 2. 快速开始

```powershell
# 1) 下载 m3u8 直接合成 mp4
python m3u8_tool.py download-mp4 "https://example.com/video/index.m3u8" -o out.mp4

# 2) 下载所有 ts 切片，并生成本地可播放的 index.m3u8
python m3u8_tool.py download-ts "https://example.com/video/index.m3u8" -o ./segments

# 3) 把本地 mp4 切片成 ts + m3u8（HLS 流）
python m3u8_tool.py make-hls input.mp4 -o ./hls_out
```

---

## 3. 子命令详解

### 3.1 `download-mp4`
下载 m3u8 视频并合并为 `mp4`。

```
python m3u8_tool.py download-mp4 <m3u8_url> -o <out.mp4> [选项]
```

常用选项：

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `-o, --output` | 输出 mp4 路径（必填） | — |
| `-t, --threads` | 切片并发下载线程数 | `8` |
| `-H, --header` | 自定义请求头，格式 `Key: Value`，可多次 | — |
| `--keep` | 保留临时切片目录（用于排查） | 关闭 |

示例（带 Referer 和 Cookie）：

```powershell
python m3u8_tool.py download-mp4 "https://x.com/a.m3u8" -o a.mp4 `
  -H "Referer: https://x.com/" `
  -H "Cookie: sid=xxxx"
```

> 若 m3u8 是 AES-128 加密流，脚本会自动改用 `ffmpeg` 直拉合并（ffmpeg 内置解密）。

### 3.2 `download-ts`
下载所有切片并生成本地 `index.m3u8`，方便保存 HLS 原始素材或本地播放。

```
python m3u8_tool.py download-ts <m3u8_url> -o <output_dir> [选项]
```

输出目录结构：

```
output_dir/
├── index.m3u8        # 已重写为本地相对路径
├── key.bin           # 若原 m3u8 含 AES key，会一并下载
├── seg_000000.ts
├── seg_000001.ts
└── ...
```

播放：用 VLC 打开 `index.m3u8` 即可。

### 3.3 `make-hls`
把本地视频切片为 HLS。

```
python m3u8_tool.py make-hls <input_video> -o <output_dir> [选项]
```

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `-s, --segment-time` | 单切片时长（秒） | `3` |
| `--reencode` | 重新编码（兼容性更好，体积/时间略增） | 关闭，默认 `-c copy` |

示例：

```powershell
# 直接 copy 流（最快，要求源编码 HLS 兼容）
python m3u8_tool.py make-hls movie.mp4 -o hls_out -s 6

# 强制重编码为 H.264 + AAC
python m3u8_tool.py make-hls movie.mkv -o hls_out --reencode
```

输出：

```
hls_out/
├── index.m3u8
├── seg_00000.ts
├── seg_00001.ts
└── ...
```

---

## 4. 常见问题

**Q: 提示 "未检测到 ffmpeg"？**
A: 运行 `pip install imageio-ffmpeg` 即可，它会自动下载 ffmpeg 二进制，不需要手动安装或配置 PATH。

**Q: 切片下载报 403 / 401？**
A: 加 `-H "Referer: ..."`、`-H "Cookie: ..."` 等请求头。这些头信息通常可以在浏览器 DevTools → Network 中复制。

**Q: 下载下来的 mp4 有杂音 / 不同步？**
A: 试试不带 `--keep` 重新下载；或先用 `download-ts` 拉到本地，再用 `ffmpeg -i index.m3u8 -c copy out.mp4` 自行合并。

**Q: master playlist (含多码率) 如何选码率？**
A: 当前默认选第一个变体。需指定其他码率时，可先打开 m3u8 文本，把目标子链接传给本工具即可。

**Q: `imageio-ffmpeg` 下载太慢？**
A: 它首次会从 GitHub 下载二进制。可设置代理或使用国内镜像后重试，或自行安装系统 ffmpeg 加入 PATH，脚本会自动检测使用。

---

## 5. 许可

仅供学习与个人合法使用，请勿用于侵犯版权或违反目标站点服务条款的场景。使用本工具产生的一切后果由使用者自行承担。