m3u8-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{m3u8_cli-0.1.0 → m3u8_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: m3u8-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: HLS 视频下载与格式转换工具
 Author: r1a
 Author-email: r1a <m@zcq100.com>
@@ -101,10 +101,16 @@ python -m m3u8_cli download "<m3u8_url>"
 python -m m3u8_cli convert movie.mp4 -o out
 ```
 
+查看版本：
+
+```bash
+m3u8-cli -v       # 或 --version
+```
+
 ### 常用示例
 
 ```bash
-# 默认输出到 output/output.mp4
+# 默认输出到当前目录的 output.mp4
 m3u8-cli download "https://example.com/playlist.m3u8"
 
 # 指定输出文件名与并发数
@@ -170,6 +176,7 @@ HLS 输出固定为 `playlist.m3u8` 加 `ts/000000.ts` 起的分片；WebM 重
 | `--cookie` | 无 | 自定义 `Cookie` 请求头 |
 | `--user-agent` | `Mozilla/5.0` | 自定义 `User-Agent` 请求头 |
 | `--overwrite` | 关闭 | 覆盖已存在的最终文件 |
+| `-k, --insecure` | 关闭 | 跳过 TLS 证书校验，仅用于自签名或内网服务 |
 
 ### 保留 HLS（不合并）
 
@@ -183,6 +190,8 @@ m3u8-cli download "<m3u8_url>" -f hls -o movie
 - 源流为 AES-128 加密时保持密文，同时把密钥下载为 `key.bin`（多个不同密钥时为 `key_000.bin`、`key_001.bin`），播放列表的 `EXT-X-KEY` URI 重写为本地文件。
 - 分片、`playlist.m3u8` 与密钥文件位于同一目录；`--overwrite` 只清理本工具生成的条目。
 
+`--insecure` 会关闭播放列表、分片与密钥请求的证书和主机名校验，只应在信任的网络上对自签名服务使用；它不会影响元数据中记录的其他信息。
+
 ### 启动下载服务
 
 ```bash
@@ -200,6 +209,7 @@ curl -X POST http://127.0.0.1:8787/api/tasks \
     "url": "https://example.com/playlist.m3u8",
     "format": "hls",
     "output": "movie",
+    "insecure": false,
     "headers": {"Referer": "https://example.com/"}
   }'
 
@@ -223,6 +233,7 @@ curl -X DELETE http://127.0.0.1:8787/api/tasks/<id> \
 `chrome-extension/` 提供一个 Manifest V3 扩展，用于识别页面中的 m3u8 链接：
 
 - 监听页面网络请求并结合 DOM 扫描，列出当前标签页的 m3u8 地址；
+- 采集页面标题（`og:title`、Twitter Card、JSON-LD、`document.title`）作为默认下载文件名，也可在设置中改用 URL 短 hash；
 - 复制链接，或生成带 `Referer`/`Cookie`/`User-Agent` 的 `m3u8-cli download` 命令；
 - 一键提交到本地 `m3u8-cli serve` 下载，并在弹窗中查看进度、取消任务。
 
@@ -245,28 +256,53 @@ uv run python scripts/build_extension.py
 
 ## 下载输出结构
 
-以 `-o movie.mp4` 为例：
+### MP4（默认，合并封装）
+
+以 `-o movie.mp4` 为例，输出目录下只有最终产物和元数据：
+
+```
+movie.mp4
+movie.mp4.meta.json     # ffprobe 的 format/streams + source 来源信息
+movie.partial.mp4       # FFmpeg 临时输出（仅在合并过程中存在）
+```
+
+分片缓存不落在输出目录，而是位于系统临时目录：
+
+```
+<TMP>/m3u8-cli-<uid>/<最终路径哈希>/
+├── state.json          # 播放列表指纹，用于缓存失效判断
+├── segment_000000.bin  # 已解密的媒体分片
+├── map_0000.bin        # fMP4 初始化片段（仅 fMP4 流）
+└── combined.ts|mp4     # 本地合并的中间文件
+```
+
+- 合并成功后整个缓存目录会被删除；失败或取消时保留，便于续传。
+- 同一 `-o` 对应同一个缓存目录；播放列表变化时 `state.json` 指纹会触发旧分片清理。
+- 元数据文件由 ffprobe 读取产物生成：顶层 `format`/`streams` 为 `ffprobe -show_format -show_streams -of json` 的输出（已去掉 `filename` 路径），`source` 记录 URL、格式、分片数、指纹、时间与是否校验 TLS；不包含 `output` 字段，也不包含 `Referer`/`Cookie`/`User-Agent`。
+- 未安装 ffprobe 时会在 stderr 打印警告，元数据仅保留 `source` 部分，下载仍继续进行。
+
+### HLS（保留分片）
+
+以 `-o movie` 为例：
 
 ```
 movie/
-├── movie.mp4              # 最终产物
-└── cache/
-    ├── state.json         # 播放列表指纹，用于缓存失效判断
-    ├── segment_000000.bin # 已解密的媒体分片
-    ├── map_0000.bin       # fMP4 初始化片段（仅 fMP4 流）
-    ├── combined.ts|mp4    # 本地合并的中间文件
-    └── movie.partial.mp4  # FFmpeg 临时输出
+├── playlist.m3u8       # 本地播放列表
+├── 000000.ts           # 分片（fMP4 为 .m4s，另有 init.mp4）
+├── key.bin             # 存在 AES-128 密钥时
+└── meta.json           # ffprobe 媒体信息 + source 来源信息
 ```
 
-- 任务目录由输出文件名自动派生；若输出路径已经是 `movie/movie.mp4` 形式，会复用该目录，不会重复嵌套。
-- 最终文件生成成功后，缓存仍会保留在任务目录中。
+- 分片先下载到系统临时目录，导出成功后清理；输出目录只保留最终产物和元数据。
+- 导出失败或取消时缓存保留，便于用相同 `-o` 续传。
 
 ## 缓存与续传
 
-- 使用相同 `-o` 且任务目录仍在时，已存在且非空的分片会被直接复用。
-- `cache/state.json` 记录播放列表原文的 SHA-256 指纹；播放列表变化时会清除旧分片。
+- 两种格式的分片缓存都位于 `<系统临时目录>/m3u8-cli-<uid>/<最终路径 SHA-256 前 16 位>/`；成功下载后删除，失败/取消时保留。
+- 使用相同 `-o` 且缓存仍在时，已存在且非空的分片会被直接复用。
+- 缓存中的 `state.json` 记录播放列表原文的 SHA-256 指纹；播放列表变化时会清除旧分片。
 - 下载时最终文件已存在且未指定 `--overwrite`，程序会直接退出。
-- 需要彻底清理时，删除整个任务目录即可。
+- 操作系统清理临时目录后，失败任务需要重新下载；需要彻底清理时删除对应的临时缓存目录即可。
 
 ## 已知限制
 
@@ -281,6 +317,7 @@ movie/
 - FFmpeg 的 HLS muxer 会写入固定 `IV=0`，所有分片共用同一密钥与 IV。
 - 不支持自定义密钥、密钥 URI 或 IV。
 - serve 不做 SSRF 内网地址屏蔽，依赖 token 与局域网部署。
+- Windows 默认 `MAX_PATH=260`：serve 会按输出目录长度截短过长的文件名（保留扩展名），任务响应中返回实际名字；CLI 的 `-o` 不做改写。
 - serve 不提供下载产物接口，文件留在服务器。
 - serve 重启后任务标记为 `interrupted`，不会自动恢复。
 - 请求头不落盘，重启后无法重放任务。

{m3u8_cli-0.1.0 → m3u8_cli-0.2.0}/README.md

@@ -88,10 +88,16 @@ python -m m3u8_cli download "<m3u8_url>"
 python -m m3u8_cli convert movie.mp4 -o out
 ```
 
+查看版本：
+
+```bash
+m3u8-cli -v       # 或 --version
+```
+
 ### 常用示例
 
 ```bash
-# 默认输出到 output/output.mp4
+# 默认输出到当前目录的 output.mp4
 m3u8-cli download "https://example.com/playlist.m3u8"
 
 # 指定输出文件名与并发数
@@ -157,6 +163,7 @@ HLS 输出固定为 `playlist.m3u8` 加 `ts/000000.ts` 起的分片；WebM 重
 | `--cookie` | 无 | 自定义 `Cookie` 请求头 |
 | `--user-agent` | `Mozilla/5.0` | 自定义 `User-Agent` 请求头 |
 | `--overwrite` | 关闭 | 覆盖已存在的最终文件 |
+| `-k, --insecure` | 关闭 | 跳过 TLS 证书校验，仅用于自签名或内网服务 |
 
 ### 保留 HLS（不合并）
 
@@ -170,6 +177,8 @@ m3u8-cli download "<m3u8_url>" -f hls -o movie
 - 源流为 AES-128 加密时保持密文，同时把密钥下载为 `key.bin`（多个不同密钥时为 `key_000.bin`、`key_001.bin`），播放列表的 `EXT-X-KEY` URI 重写为本地文件。
 - 分片、`playlist.m3u8` 与密钥文件位于同一目录；`--overwrite` 只清理本工具生成的条目。
 
+`--insecure` 会关闭播放列表、分片与密钥请求的证书和主机名校验，只应在信任的网络上对自签名服务使用；它不会影响元数据中记录的其他信息。
+
 ### 启动下载服务
 
 ```bash
@@ -187,6 +196,7 @@ curl -X POST http://127.0.0.1:8787/api/tasks \
     "url": "https://example.com/playlist.m3u8",
     "format": "hls",
     "output": "movie",
+    "insecure": false,
     "headers": {"Referer": "https://example.com/"}
   }'
 
@@ -210,6 +220,7 @@ curl -X DELETE http://127.0.0.1:8787/api/tasks/<id> \
 `chrome-extension/` 提供一个 Manifest V3 扩展，用于识别页面中的 m3u8 链接：
 
 - 监听页面网络请求并结合 DOM 扫描，列出当前标签页的 m3u8 地址；
+- 采集页面标题（`og:title`、Twitter Card、JSON-LD、`document.title`）作为默认下载文件名，也可在设置中改用 URL 短 hash；
 - 复制链接，或生成带 `Referer`/`Cookie`/`User-Agent` 的 `m3u8-cli download` 命令；
 - 一键提交到本地 `m3u8-cli serve` 下载，并在弹窗中查看进度、取消任务。
 
@@ -232,28 +243,53 @@ uv run python scripts/build_extension.py
 
 ## 下载输出结构
 
-以 `-o movie.mp4` 为例：
+### MP4（默认，合并封装）
+
+以 `-o movie.mp4` 为例，输出目录下只有最终产物和元数据：
+
+```
+movie.mp4
+movie.mp4.meta.json     # ffprobe 的 format/streams + source 来源信息
+movie.partial.mp4       # FFmpeg 临时输出（仅在合并过程中存在）
+```
+
+分片缓存不落在输出目录，而是位于系统临时目录：
+
+```
+<TMP>/m3u8-cli-<uid>/<最终路径哈希>/
+├── state.json          # 播放列表指纹，用于缓存失效判断
+├── segment_000000.bin  # 已解密的媒体分片
+├── map_0000.bin        # fMP4 初始化片段（仅 fMP4 流）
+└── combined.ts|mp4     # 本地合并的中间文件
+```
+
+- 合并成功后整个缓存目录会被删除；失败或取消时保留，便于续传。
+- 同一 `-o` 对应同一个缓存目录；播放列表变化时 `state.json` 指纹会触发旧分片清理。
+- 元数据文件由 ffprobe 读取产物生成：顶层 `format`/`streams` 为 `ffprobe -show_format -show_streams -of json` 的输出（已去掉 `filename` 路径），`source` 记录 URL、格式、分片数、指纹、时间与是否校验 TLS；不包含 `output` 字段，也不包含 `Referer`/`Cookie`/`User-Agent`。
+- 未安装 ffprobe 时会在 stderr 打印警告，元数据仅保留 `source` 部分，下载仍继续进行。
+
+### HLS（保留分片）
+
+以 `-o movie` 为例：
 
 ```
 movie/
-├── movie.mp4              # 最终产物
-└── cache/
-    ├── state.json         # 播放列表指纹，用于缓存失效判断
-    ├── segment_000000.bin # 已解密的媒体分片
-    ├── map_0000.bin       # fMP4 初始化片段（仅 fMP4 流）
-    ├── combined.ts|mp4    # 本地合并的中间文件
-    └── movie.partial.mp4  # FFmpeg 临时输出
+├── playlist.m3u8       # 本地播放列表
+├── 000000.ts           # 分片（fMP4 为 .m4s，另有 init.mp4）
+├── key.bin             # 存在 AES-128 密钥时
+└── meta.json           # ffprobe 媒体信息 + source 来源信息
 ```
 
-- 任务目录由输出文件名自动派生；若输出路径已经是 `movie/movie.mp4` 形式，会复用该目录，不会重复嵌套。
-- 最终文件生成成功后，缓存仍会保留在任务目录中。
+- 分片先下载到系统临时目录，导出成功后清理；输出目录只保留最终产物和元数据。
+- 导出失败或取消时缓存保留，便于用相同 `-o` 续传。
 
 ## 缓存与续传
 
-- 使用相同 `-o` 且任务目录仍在时，已存在且非空的分片会被直接复用。
-- `cache/state.json` 记录播放列表原文的 SHA-256 指纹；播放列表变化时会清除旧分片。
+- 两种格式的分片缓存都位于 `<系统临时目录>/m3u8-cli-<uid>/<最终路径 SHA-256 前 16 位>/`；成功下载后删除，失败/取消时保留。
+- 使用相同 `-o` 且缓存仍在时，已存在且非空的分片会被直接复用。
+- 缓存中的 `state.json` 记录播放列表原文的 SHA-256 指纹；播放列表变化时会清除旧分片。
 - 下载时最终文件已存在且未指定 `--overwrite`，程序会直接退出。
-- 需要彻底清理时，删除整个任务目录即可。
+- 操作系统清理临时目录后，失败任务需要重新下载；需要彻底清理时删除对应的临时缓存目录即可。
 
 ## 已知限制
 
@@ -268,6 +304,7 @@ movie/
 - FFmpeg 的 HLS muxer 会写入固定 `IV=0`，所有分片共用同一密钥与 IV。
 - 不支持自定义密钥、密钥 URI 或 IV。
 - serve 不做 SSRF 内网地址屏蔽，依赖 token 与局域网部署。
+- Windows 默认 `MAX_PATH=260`：serve 会按输出目录长度截短过长的文件名（保留扩展名），任务响应中返回实际名字；CLI 的 `-o` 不做改写。
 - serve 不提供下载产物接口，文件留在服务器。
 - serve 重启后任务标记为 `interrupted`，不会自动恢复。
 - 请求头不落盘，重启后无法重放任务。

{m3u8_cli-0.1.0 → m3u8_cli-0.2.0}/chrome-extension/README.md

@@ -4,6 +4,7 @@
 
 - 无构建步骤：原生 JavaScript，Chrome 直接加载目录即可。
 - 网络请求 + DOM 扫描双来源识别，支持 iframe 中的播放器。
+- 自动采集页面标题（`og:title`、Twitter Card、JSON-LD、`document.title`）作为默认下载文件名，标题缺失时回退到「host-文件名」；也可在设置中改为 URL 短 hash（12 位十六进制）。
 - 一键下载时自动携带该 m3u8 请求自己的 `Referer`、`Cookie`、`User-Agent`。
 - 弹窗内查看任务进度、取消任务；popup 关闭后仍由后台轮询。
 
@@ -49,18 +50,20 @@ uv run m3u8-cli serve --host 127.0.0.1 --port 8787 --token mytoken --output-dir
 | 服务地址 | 默认 `http://127.0.0.1:8787`，需与 `--host/--port` 一致 |
 | Token | 与 `--token` 一致；点击“测试连接”确认 |
 | 下载格式 | `mp4`（合并封装）或 `hls`（保留分片） |
+| 文件名 | `页面标题`（默认）或 `URL 短 hash`（12 位十六进制；URL 带临时 token 时每次可能不同） |
 | 覆盖已存在的文件 | 对应 serve 的 `overwrite` 字段 |
 | 发送捕获到的 Cookie | 默认开启，仅发送给上面配置的服务地址 |
 | 复制 CLI 命令时包含 Cookie | 默认关闭；开启后命令会包含 Cookie 原文，注意 shell 历史 |
+| 跳过 TLS 证书校验 | 默认关闭；开启后 serve 请求源站时不校验证书与主机名，仅用于自签名/内网服务 |
 
 ## 使用
 
 1. 打开包含视频的页面并开始播放，或等待页面加载完成。
 2. 扩展图标上的 badge 显示当前标签页识别到的 m3u8 数量。
-3. 点击扩展图标：
+3. 点击扩展图标，候选条目会显示页面标题和 m3u8 URL：
    - **复制**：复制 m3u8 URL。
-   - **复制 CLI**：生成 `m3u8-cli download ...` 命令，按设置决定是否包含 `--referer`、`--cookie`、`--user-agent`。
-   - **下载**：提交到本地 serve 服务；若提示文件名冲突，可点击“换名重试”自动加时间戳。
+   - **复制 CLI**：生成 `m3u8-cli download ...` 命令，按设置决定是否包含 `--referer`、`--cookie`、`--user-agent`；`-o` 默认使用页面标题。
+   - **下载**：提交到本地 serve 服务，默认文件名同样来自页面标题；若提示文件名冲突，可点击“换名重试”自动加时间戳。
 4. “下载任务”区域显示排队中/下载中/已完成/失败/已取消/已中断等状态和分片进度；运行中的任务可以取消。
 5. “重新扫描”会请求当前页面的所有 frame 重新执行 DOM 扫描；“清空”只会清除本标签页的识别结果。
 
@@ -71,6 +74,13 @@ uv run m3u8-cli serve --host 127.0.0.1 --port 8787 --token mytoken --output-dir
 
 同一 URL 同时来自两个来源时会合并为一条，并优先保留网络请求捕获的请求头。
 
+标题采集：
+
+- content script 按 `og:title` → `twitter:title` → 视频类 JSON-LD → `document.title` 的顺序取标题；iframe 中的候选优先使用顶层标签页标题。
+- 网络请求捕获的候选通过 `chrome.tabs.get()` 取标签页标题（`<all_urls>` host permission 已覆盖，无需 `tabs` 权限）。
+- 标题会清洗控制字符、合并空白，输出名再经过非法字符替换和 200 字符截断；拿不到标题时回退到「host-文件名」。
+- 选择「URL 短 hash」时直接对 m3u8 URL 做 12 位哈希，不依赖页面标题，适合标题过长或不想在文件名中暴露标题的场景。
+
 ## 权限说明
 
 | 权限 | 用途 |
@@ -92,6 +102,7 @@ uv run m3u8-cli serve --host 127.0.0.1 --port 8787 --token mytoken --output-dir
 - Token 保存在 `storage.local`，请勿在不信任的共享 Chrome 配置中使用。
 - serve 端请求头只保留在内存，不落盘、不在任务响应中返回；详见仓库 README。
 - 扩展不会自动提交下载，必须由用户点击，避免页面借扩展触发 serve 请求。
+- 「跳过 TLS 证书校验」会关闭 serve 到源站的证书与主机名校验，可能暴露下载内容给中间人；仅在确认源站可信（如自签名内网服务）时开启。
 - CORS `*` 不是安全边界，真正的访问控制是 Bearer token。
 
 ## 排障
@@ -99,10 +110,13 @@ uv run m3u8-cli serve --host 127.0.0.1 --port 8787 --token mytoken --output-dir
 | 现象 | 处理 |
 | --- | --- |
 | 弹窗提示“未检测到 m3u8” | 确认视频已开始播放；刚安装/重载扩展后刷新页面；尝试“重新扫描” |
-| “测试连接”报 `Failed to fetch` | 确认 serve 已启动、地址与端口正确、协议为 `http/https` |
-| 401 / “未授权” | 检查 Token；serve 未指定 `--token` 时每次启动都会生成新 token |
+| 提示“未配置 Token” | 在扩展设置中填写 serve 的 `--token` |
+| “无法连接 http://...（Failed to fetch）” | serve 未启动、地址/端口错误，或协议不是 `http/https` |
+| 提示“连接 ... 超时（8 秒）” | 服务可达性差或进程卡住；确认 serve 正常运行并检查网络/防火墙 |
+| 401 / “未授权” | Token 与服务端不一致；serve 未指定 `--token` 时每次启动都会生成新 token |
 | 409 / 目标文件已存在 | 点击“换名重试”，或在设置中开启“覆盖已存在的文件” |
 | 下载失败，提示 403 | 源站可能校验 `Referer`/`Cookie`/`User-Agent`；确认候选来自“网络”且页面仍处于登录状态 |
+| 失败原因是 `CERTIFICATE_VERIFY_FAILED` / Hostname mismatch | 源站证书不匹配（自签名或内网域名）；确认可信后开启「跳过 TLS 证书校验」 |
 | 扩展重载后页面无反应 | 刷新页面，让 content script 重新注入 |
 | badge 数量未变化 | 网络识别只在页面产生新请求时更新；静态链接由 DOM 扫描或“重新扫描”补充 |
 
@@ -127,7 +141,7 @@ uv run python scripts/build_extension.py
 | 文件 | 职责 |
 | --- | --- |
 | `manifest.json` | MV3 配置、权限、content script 注入 |
-| `lib.js` | 三端共享的纯函数：URL 判断、MIME 判断、输出名清洗、shell 转义、CLI 命令 |
+| `lib.js` | 三端共享的纯函数：URL 判断、MIME 判断、页面标题清洗、输出名清洗与派生、shell 转义、CLI 命令 |
 | `lib.test.js` | `lib.js` 的单元测试 |
 | `background.js` | 网络检测、候选与会话存储、badge、serve API 调用、任务轮询、消息路由 |
 | `content.js` | DOM 扫描、MutationObserver、增量上报 |
@@ -135,18 +149,20 @@ uv run python scripts/build_extension.py
 
 ### 数据与消息
 
-- `storage.session["tab:<tabId>"]`：`{pageUrl, items:[{id,url,source,hasCookie,...}]}`，最多 30 条，标签页关闭或导航时清理。
+- `storage.session["tab:<tabId>"]`：`{pageUrl, pageTitle, items:[{id,url,source,pageTitle,hasCookie,...}]}`，最多 30 条，标签页关闭或导航时清理。
 - `storage.session["hdr:<candidateId>"]`：`{cookie, referer, userAgent}`，仅 background 读取。
-- `storage.local["settings"]`：服务地址、token、格式等设置。
+- `storage.local["settings"]`：服务地址、token、格式、`naming`（`title`/`hash`）、`insecure`（跳过源站 TLS 校验）等设置。
 - `storage.local["tasks"]`：最近的任务摘要（最多 20 条，优先保留活动任务），不含请求头。
 - popup 通过 `chrome.runtime.sendMessage` 发送 `download:submit`、`task:cancel`、`tasks:refresh`、`settings:test`、`cli:build`、`tab:clear`、`dom:rescan`。
-- content script 通过 `dom:candidates` 上报 URL，用 `sender.tab.id` 归属标签页。
+- content script 通过 `dom:candidates` 上报 URL 与 `title`（附 `frameTop` 标记是否顶层 frame），用 `sender.tab.id` 归属标签页。
 
 ## 已知限制
 
 - popup 关闭后任务轮询依赖 `chrome.alarms`，最短周期为 30 秒（旧版 Chrome 为 1 分钟）；popup 打开时每 2 秒刷新一次。
 - 只做网络请求与 DOM 扫描，不注入 MAIN world 去 hook `fetch`/`XMLHttpRequest`；缓存命中或没有实际请求的地址可能只由 DOM 扫描发现。
 - 不支持 Shadow DOM 内的元素；iframe 支持依赖 `all_frames` 和网络层。
+- 标题依赖页面元数据：SPA 或动态改写的标题可能滞后，拿不到时回退到 URL 派生名；标题超过 200 字符会被截断，标签页标题可能带站点后缀（如「- 示例站」），需要时可手动改名。
+- serve 还会按输出目录长度进一步截短文件名（Windows `MAX_PATH` 或 POSIX 255 字节限制），任务响应里的 `output` 是实际使用的名字；「换名重试」会使用较短的名字，避免时间戳被截掉。
 - SPA 路由切换不会自动清空候选，使用“清空”或刷新页面。
 - 每个标签页最多保留 30 条候选，任务历史最多 20 条。
 - 下载能力受 `m3u8-cli` 本身限制（AES-128 identity、无 DRM、不支持 BYTERANGE 等），详见根 README。

{m3u8_cli-0.1.0 → m3u8_cli-0.2.0}/chrome-extension/background.js

@@ -10,7 +10,8 @@ const {
   looksLikePlaylistUrl,
   isHlsContentType,
   normalizeCandidateUrl,
-  deriveOutputName,
+  cleanPageTitle,
+  buildOutputName,
   buildCliCommand,
 } = M3U8Lib;
 
@@ -41,9 +42,11 @@ const DEFAULT_SETTINGS = {
   serverUrl: "http://127.0.0.1:8787",
   token: "",
   format: "mp4",
+  naming: "title",
   overwrite: false,
   sendCookie: true,
   copyCookie: false,
+  insecure: false,
 };
 
 /** requestId -> 白名单请求头快照；service worker 休眠后丢失，可接受。 */
@@ -69,10 +72,14 @@ function headerKey(candidateId) {
   return `hdr:${candidateId}`;
 }
 
+function emptyTabState() {
+  return { pageUrl: "", pageTitle: "", updatedAt: 0, items: [] };
+}
+
 async function readTabState(tabId) {
   const key = tabKey(tabId);
   const data = await chrome.storage.session.get(key);
-  return data[key] || { pageUrl: "", updatedAt: 0, items: [] };
+  return data[key] || emptyTabState();
 }
 
 async function removeHeaders(ids) {
@@ -123,21 +130,26 @@ function addCandidate(tabId, candidate, headers) {
   return enqueueWrite(async () => {
     const key = tabKey(tabId);
     const data = await chrome.storage.session.get(key);
-    const state = data[key] || { pageUrl: "", updatedAt: 0, items: [] };
+    const state = data[key] || emptyTabState();
     const existingIndex = state.items.findIndex(
       (item) => item.url === candidate.url,
     );
+    // 空标题不覆盖已有标题：网络候选可能晚于 DOM 候选、拿不到标题。
+    const patch = { ...candidate };
+    if (!patch.pageTitle) {
+      delete patch.pageTitle;
+    }
 
     let item;
     if (existingIndex >= 0) {
       const existing = state.items[existingIndex];
       state.items.splice(existingIndex, 1);
-      item = { ...existing, ...candidate, id: existing.id };
+      item = { ...existing, ...patch, id: existing.id };
     } else {
       item = {
         id: crypto.randomUUID(),
         capturedAt: Date.now(),
-        ...candidate,
+        ...patch,
       };
     }
     item.hasCookie = Boolean(headers && headers.cookie);
@@ -150,6 +162,9 @@ function addCandidate(tabId, candidate, headers) {
     if (!state.pageUrl && candidate.pageUrl) {
       state.pageUrl = candidate.pageUrl;
     }
+    if (patch.pageTitle) {
+      state.pageTitle = patch.pageTitle;
+    }
     state.updatedAt = Date.now();
 
     const updates = { [key]: state };
@@ -202,6 +217,16 @@ function trimPendingHeaders() {
   }
 }
 
+/** 标签页标题；host permission 已覆盖所有 http/https 页面。 */
+async function getTabTitle(tabId) {
+  try {
+    const tab = await chrome.tabs.get(tabId);
+    return tab && typeof tab.title === "string" ? tab.title : "";
+  } catch (_) {
+    return "";
+  }
+}
+
 chrome.webRequest.onSendHeaders.addListener(
   (details) => {
     if (details.tabId < 0 || !TRACKED_TYPE_SET.has(details.type)) {
@@ -251,15 +276,21 @@ chrome.webRequest.onHeadersReceived.addListener(
       refererHost: referer ? safeHost(referer) : "",
       pageUrl,
     };
-    addCandidate(
-      details.tabId,
-      candidate,
-      {
-        cookie: captured.cookie || "",
-        referer,
-        userAgent: captured.userAgent || "",
-      },
-    ).catch(() => {});
+    const headers = {
+      cookie: captured.cookie || "",
+      referer,
+      userAgent: captured.userAgent || "",
+    };
+    getTabTitle(details.tabId)
+      .then((rawTitle) => {
+        const pageTitle = cleanPageTitle(rawTitle);
+        return addCandidate(
+          details.tabId,
+          pageTitle ? { ...candidate, pageTitle } : candidate,
+          headers,
+        );
+      })
+      .catch(() => {});
   },
   { urls: ["<all_urls>"], types: TRACKED_TYPES },
   ["responseHeaders"],
@@ -302,6 +333,12 @@ async function handleDomCandidates(message, sender) {
   const base = message.pageUrl || pageUrl;
   const urls = Array.isArray(message.urls) ? message.urls.slice(0, 100) : [];
   const seen = new Set();
+  const tabTitle = cleanPageTitle((sender.tab && sender.tab.title) || "");
+  // iframe 里的 document.title 往往只是播放器自己的标题，优先用顶层标签页标题。
+  const pageTitle =
+    message.frameTop === true
+      ? cleanPageTitle(message.title) || tabTitle
+      : tabTitle || cleanPageTitle(message.title);
 
   for (const raw of urls) {
     const url = normalizeCandidateUrl(raw, base);
@@ -309,17 +346,17 @@ async function handleDomCandidates(message, sender) {
       continue;
     }
     seen.add(url);
-    await addCandidate(
-      tabId,
-      {
-        url,
-        source: "dom",
-        contentType: "",
-        refererHost: "",
-        pageUrl,
-      },
-      null,
-    );
+    const candidate = {
+      url,
+      source: "dom",
+      contentType: "",
+      refererHost: "",
+      pageUrl,
+    };
+    if (pageTitle) {
+      candidate.pageTitle = pageTitle;
+    }
+    await addCandidate(tabId, candidate, null);
   }
 }
 
@@ -366,6 +403,13 @@ function resolveFormat(requested, fallback) {
   return fallback === "hls" ? "hls" : "mp4";
 }
 
+function resolveNaming(requested, fallback) {
+  if (requested === "hash" || requested === "title") {
+    return requested;
+  }
+  return fallback === "hash" ? "hash" : "title";
+}
+
 async function apiFetch(path, options) {
   const settings = await getSettings();
   const base = normalizeServerUrl(settings.serverUrl);
@@ -376,7 +420,21 @@ async function apiFetch(path, options) {
   };
   init.headers.Authorization = `Bearer ${settings.token}`;
 
-  const response = await fetch(base + path, init);
+  let response;
+  try {
+    response = await fetch(base + path, init);
+  } catch (error) {
+    const name = error && error.name;
+    if (name === "TimeoutError" || name === "AbortError") {
+      throw new Error(
+        `连接 ${base} 超时（8 秒）：请确认服务已启动且地址可达`,
+      );
+    }
+    const reason = (error && error.message) || String(error);
+    throw new Error(
+      `无法连接 ${base}（${reason}）：请确认 m3u8-cli serve 已启动、地址和端口正确`,
+    );
+  }
   let payload = null;
   try {
     payload = await response.json();
@@ -393,12 +451,29 @@ async function apiFetch(path, options) {
   return payload;
 }
 
+/** 按命名策略生成输出名；标题缺失时回退到 URL 派生名。 */
+function candidateOutputName(candidate, state, format, naming) {
+  const title = candidate.pageTitle || (state && state.pageTitle) || "";
+  return buildOutputName({
+    title,
+    url: candidate.url,
+    format,
+    naming,
+  });
+}
+
 async function submitDownload(message) {
   const tabId = message.tabId;
   if (!Number.isInteger(tabId) || tabId < 0) {
     return { ok: false, error: "无效的标签页" };
   }
   const settings = await getSettings();
+  if (!settings.token) {
+    return {
+      ok: false,
+      error: "未配置 Token：请在扩展设置中填写 serve 的 token",
+    };
+  }
   const state = await readTabState(tabId);
   const candidate = state.items.find((item) => item.id === message.candidateId);
   if (!candidate) {
@@ -408,8 +483,10 @@ async function submitDownload(message) {
   const key = headerKey(candidate.id);
   const captured = (await chrome.storage.session.get(key))[key] || {};
   const format = resolveFormat(message.format, settings.format);
+  const naming = resolveNaming(message.naming, settings.naming);
   const output =
-    message.output || deriveOutputName(candidate.url, format);
+    message.output ||
+    candidateOutputName(candidate, state, format, naming);
   const overwrite =
     message.overwrite === undefined
       ? Boolean(settings.overwrite)
@@ -435,6 +512,7 @@ async function submitDownload(message) {
       format,
       output,
       overwrite,
+      insecure: Boolean(settings.insecure),
       headers,
     }),
   });
@@ -471,7 +549,10 @@ async function buildCliMessage(message) {
   const key = headerKey(candidate.id);
   const captured = (await chrome.storage.session.get(key))[key] || {};
   const format = resolveFormat(message.format, settings.format);
-  const output = message.output || deriveOutputName(candidate.url, format);
+  const naming = resolveNaming(message.naming, settings.naming);
+  const output =
+    message.output ||
+    candidateOutputName(candidate, state, format, naming);
   const includeCookie = Boolean(message.includeCookie);
   const overwrite =
     message.overwrite === undefined