# media-kit

**Repository Path**: lieefu/media-kit

## Basic Information

- **Project Name**: media-kit
- **Description**: 下载网络视频，并支持视频和图片去水印、视频语音文案提取
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-13
- **Last Updated**: 2026-10-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 视频和图片工具箱 · 程序代码

「视频下载 + 视频/图片去水印」的本地工具。浏览器打开、本机运行、不连云端。

## 启动

```bash
cd /media/lieefu/aiwork/workbuddy/视频和图片工具箱
sh start-web.sh          # → http://127.0.0.1:8770/
```

命令行版（可选）：

```bash
.venv/bin/python -m app.cli "<链接>" --list
.venv/bin/python -m app.cli "<链接>" -q 1080 -t 8
.venv/bin/python -m app.cli "<链接>" --cookie yuanbao="<元宝 Cookie，视频号用>"
```

## 能做什么

| | 说明 |
|---|---|
| **下载** | **只下视频，不含图片**：X / YouTube / B站 / 抖音 / 小红书 / 微信视频号，以及 yt-dlp 覆盖的微博 / Instagram / 快手 / TikTok 等（**除 X / 抖音 / 视频号**外都交给 yt-dlp）。**录入框里可以直接粘一整段分享文案**（抖音/快手那种「5.89 复制打开抖音…https://v.douyin.com/xxx/ 03/02 …」），会自动把里面的网址抠出来再用（`downloaders/__init__.py::extract_urls`；解析与下载两处都抠，下载绝不会把整段文案传下去）。一段里有多条链接时**先解析第一条**，并提示「还有 N 个链接没解析」（当前一次解析一个）。**录入框还会先离线预判支持范围**：不在范围内的链接（纯文本、不认识的网站、`ftp://` 等）**直接提示、不去解析**——预判不联网、不跑 yt-dlp（`downloaders/__init__.py::probe_support`）。⛔ **推文里的图片一律忽略**（只挑视频）；一条推文如果只有图片、没有视频，会明确提示「这个推文里没有能找到的视频」，不会下任何东西（2026-10-14 用户定） |
| **去水印** | 两种算法可选：**<u>智能修补（默认）</u>**（OpenCV `inpaint`，把框外像素向内渐变扩散，小角标/小字水印几乎无痕）与 **`delogo`**（ffmpeg 框内插值，旧算法，留着可回退）。视频与图片都行；框内处理、原版永远保留、另存 `…_去水印.ext`（**成品始终只保留一份**：无论从原片再做还是从成品再做，都覆盖这同一份，不再堆 `_2`/`_3`） |
| **本地导入** | 把任意本地视频/图片拖进页面，直接去水印。**整页还支持 `Ctrl`+`V` 粘贴**：系统截屏后不用先存盘，在本页按一下就直接落进「我的视频和图片」（见下方「粘贴（Ctrl+V）」一节） |
| **批量** | 「我的视频和图片」多选 → 点「批量去水印」→ 在弹出的**记忆框库**里选一组框（可多选合并，右侧用选中的文件当样本预览框的位置），确认后套到全部选中文件；不需要的框可直接删。样本文件可在弹层里切换（默认第一个）。同一块工具条上还有**「删除所选」**（取消勾选时置灰）：一次删掉全部勾选项，与卡片上的单个「删除」走**同一条**后端删除（先弹一次确认、**真删不可恢复**、指向它的任务记录一并清走，删完清空选择并刷新三个列表） |
| **预设区域** | 同一来源的水印位置固定，框一次即可复用（含跨分辨率换算）；「记忆名」可留空，留空时按「平台+分辨率+框坐标」自动生成指纹键 |
| **界面里直接画框** | 批量弹层右侧**直接按住左键在画面上拖动**就能画一组新框（无需先点任何按钮；可撤销/清空），点**「存为记忆框」**立刻存进左侧列表并自动选中。⛔ 手画的框是样本的原生像素坐标、**不做跨分辨率缩放**，只对与样本同分辨率的文件准；尺寸不一致时界面会黄条警告 |
| **弹层翻页** | 去水印弹层（显示画面的那个）与「看图 / 看视频」弹层都支持**上一个 / 下一个**（⚠️ 文案不用「上一张 / 下一张」——列表里既有图片又有视频，用「张」是把视频当纸片了）：头部按钮组 + 画面两侧悬浮箭头，也可用 `←` / `→` 方向键。翻页范围＝该文件**所在的列表**（「我的视频和图片」或「已下载视频」），顺序与屏幕一致；只有一个文件时整组控件自动隐藏 |
| **看图 / 看视频** | 列表里点**「显示」（图片）/「播放」（视频）在弹层里打开**（不再是 `window.open` 新标签页）。**两个列表的缩略图本身就是入口**：点「已下载视频」的封面图、或点「我的视频和图片」的缩略图，都直接打开播放/看图弹层（鼠标悬停有淡蓝描边、视频卡上还有个 ▶ 角标；没缩略图/抽帧失败时那块黑底照样可点；缩略图上的勾选框和角标不抢点击）。**打开即自动播放**（点缩略图 / 点「播放」/ 按翻页箭头都是用户手势，浏览器允许带声音自动播；万一被自动播放策略拦下，视频停在那里，手动点播放键照样能播）。同样是头部按钮组 + 两侧悬浮箭头 + `←`/`→` 翻页，范围＝所在列表；图片走 `<img>`、视频走内置 `<video controls>`；附「提取文案」（判明没人声时**置灰显示「无语音」、不可点**）「去水印」「下载」「原文件 ↗」；`Esc` 关闭（关视频会顺带暂停） |
| **查重** | **「查找重复」**：把 `downloads/`+`uploads/` 的图片与视频一起扫，分出**精确重复**（字节级一致）与**近似重复**（同一张图的 不同分辨率/压缩、同一部片的 不同清晰度/编码），**去水印成品单列成「衍生」**。每组写明**是哪种重复**（含两边分辨率），成员行写 `相似 97%，640×360`；**删哪些由你在面板里勾**（本模块只读、删除有二次确认）。见下方「查找重复」一节 |
| **语音转文案** | 看视频弹层里点「提取文案」，把片中的语音转成文字（本机 CPU，约 1 倍实时）。完成**不自动弹窗**，点「看文案」即可查看全文、一键复制；同时在同目录产出 `…_文案.txt`（纯全文，**不生成字幕 srt**），视频原版不动。弹窗统计栏会标出**识别到的语种**（如「英语 · 12 段」）。**说什么语就转什么语，不做翻译**：先 `detect_language()` 判语种，只有中文/粤语才加「输出简体」的引导语（whisper 默认吐繁体），其它语种一律原样输出。**没有人声的视频不会失败**：提交时先用快速 VAD 判一次（比转写快两个数量级），判明没语音就落一份说明文案（写明"没有可提取的语音内容"）。⛔ **按钮判据（2026-10-13 用户定，列表与看图窗口同一套）**：磁盘上有 `_文案.txt` → 「看文案」；索引里**已判明没人声** → 干脆**不给「提取文案」** —— 「已下载视频」列表上只在卡片名旁标一个灰色「无语音」标签（悬停有解释），**看图窗口**（「我的视频和图片」的文案入口）里那个按钮则**置灰成同样的「无语音」、不可点**；其余（有语音 / 还没判过）→ 「提取文案」。判过的结果只用来**省一次白点**和**加速**（真点了会秒回说明文件、不重跑 VAD）。**可以中途停止**：进度条旁边就有一个「停止」（点错长片不用干等），停止后不落任何半截产物；VAD 预判放在后台线程跑，所以提交是秒回、点下去立刻就有得停。**进度条不干等**：点下按钮后前 30 秒都在抽音频/加载模型/检测语种/提特征（真实进度恒为 0%），所以进度条旁会显示**当前阶段文字**、进度条本身也从 0 开始按阶段推进到 15% 再接真实进度 |

## 粘贴（Ctrl+V）—— 截屏、复制的文件直接入库

整页监听 `paste`（`web/app.js` 末尾那段），剪贴板里的图片/视频直接上传进「我的视频和图片」。
**收图片 + 视频**（2026-10-14 用户拍板放开视频）；其余类型（txt / pdf / zip）不接管。
纯文字粘贴不处理（留给以后按需加「自动填进链接框」）。

判据两条，改动时别破坏（`app/web/app.js` 与 `outputs/粘贴截图-功能演示.html` 同一套）：

| 情况 | 行为 |
|---|---|
| 剪贴板里**没有可收文件**（没图没视频） | **完全不接管**（不 `preventDefault`），文字粘贴照旧 |
| 焦点在输入框/文本框里，**且剪贴板还带文字** | **放行** —— 页面里粘链接、粘 Cookie 都靠这条 |
| 焦点在输入框里，但剪贴板**只有文件**（没文字） | 接管。浏览器本来也贴不进任何东西，接管是净收益（省得用户"先点一下空白处"） |
| 剪贴板里的 file **不是图片/视频**（txt / pdf / zip…） | 不接管 |

**两条来源都收**（2026-10-14 用户实测确认，两条都别断）：

1. **截图工具给的图片数据** —— Chrome 走 `clipboardData.items`，`kind === 'file'` + `type === 'image/png'`。
2. **在文件管理器里复制一个文件再粘** —— 这条路 Chrome 给的是 `clipboardData.files`（`items` 可能为空），
   所以 `clipboardMedia()` **必须保留 `files` 兜底**（只读 `items` 会漏掉整条路）。
   用户实测一次粘 5 个（png 与 jpg 混着）也正常，各得 `-2`…`-5` 后缀。

落盘名与扩展名：

- `粘贴图片-20261014-133057.png` / `粘贴视频-20261014-133057.mp4`；一次多个带 `-2` / `-3`。
  前缀按类型分（图片/视频）——列表里一眼分得出。**不沿用浏览器给的名字**（截图那条路给的永远是 `image.png`，
  所以名字只能前端定：`uploadPairs()` 里走 `FormData.append(name, file, filename)`）。
- ⛔ **扩展名必须落在服务端白名单里**（`core/media.py` 的 `IMAGE_EXT` / `VIDEO_EXT`），
  因为 `_api_upload` 是按**扩展名**决定收不收的。所以 `PASTE_EXT` 这张表**只覆盖白名单内的类型**：
  - 图片：png / jpeg / jpg / webp / gif / bmp / tiff → `.png .jpg .webp .gif .bmp .tif`
  - 视频：mp4 / x-m4v / quicktime / x-matroska / webm / x-msvideo / x-flv / mp2t / x-ms-wmv
    → `.mp4 .m4v .mov .mkv .webm .avi .flv .ts .wmv`
  - 表外的 **`video/*` 一律不收**（宁可提示，也别猜一个 `.ogg` 出来 —— 传上去照样被服务端丢掉，
    白跑一趟还看不到原因）。图片保留了旧的 `.png` 兜底（历史行为）。
  - 回归：`.tmp/t_paste_ext.py`（把 JS 那张表和服务端白名单对一遍，防两边各自漂移）。
- ⛔ 前端只管挑，**服务端仍自己兜一道**（`_api_upload` 按 `media.is_image/is_video` 校验，
  非图片/视频一律丢弃）—— 别把校验只放在前端。
- 同名再传**不覆盖**：`unique_path()` 自动改成 `…_2.png`。
- 服务端一个都没收（`saved` 为空）时前端要**明说**「这几个文件类型不支持，没有导入」，
  别让用户对着空列表猜。
- 只有真实剪贴板才能最终确认：`jsdom` 测试（`.tmp/t_paste.js`，73 项）验逻辑，
  真链路测试（`.tmp/t_upload_real.py`，19 项）验服务端收不收，最后"按 Ctrl+V"得用户来
  （2026-10-14 用户两轮实测均通过）。

### 收到粘贴之后给什么反馈（2026-10-14 用户两轮要求定稿）

顺序**别调换**，`acceptPasted()` 里就是这三步：

1. **一收到就先滚过去** —— 滚到 `#secUps`（「我的视频和图片」）+ 给模块一个描边脉冲
   （`#secUps.ping` → `@keyframes secping`）。
   ⛔ **不等上传结果**：几百 MB 的视频走 HTTP 传要好几秒，这几秒页面纹丝不动，
   用户会以为"没反应"、再按一次 `Ctrl`+`V`。
   ⛔ 脉冲是**无条件**加的，跟滚动成不成功无关 —— 已经在目标位置时 `scrollIntoView`
   压根不会移动，那时唯一的反馈就是这个脉冲。脉冲节流 1 秒（粘贴时一次、上传完点亮卡片又一次，
   别连闪两下）。⛔ `@keyframes secping` 的首尾帧都要带上 `var(--shadow)`，否则动画会把卡片投影抹掉。
2. **进度条**（`#upBar` / `#upFill` / `#upText`）—— **慢的时候看得见，快了看不见更好**：
   - 过了 `UP_SHOW_DELAY = 350ms` 还没传完才露面，本地秒传根本来不及显示；
   - 一旦露面至少停 `UP_MIN_SHOW = 520ms` 再收（几十毫秒一闪而过比不显示还扎眼）；
   - 收之前先填满到 100%；失败直接收掉（原因交给 toast，停在半路会让人以为"还在传"）。
   - ⛔ 上传走 **XHR** 而不是 `fetch` —— 只有 `xhr.upload.onprogress` 拿得到上传进度，
     `fetch` 没有可用的上传进度事件。
   - 这条**只给粘贴路**（`uploadPairs(pairs, tip, {progress:true})`）；拖拽 /「选择文件」那条路
     仍只有一句「正在上传 N 个文件…」（用户没要求动它，别顺手改）。
3. **存好之后** `focusUploads()` —— 先把页码拨回第 1 页再渲染（新文件一定落在第 1 页，
   用户停在第 3 页时只滚动不翻页会看到一整屏"什么都没变"），再给新卡片加 `.just-in`
   高亮 2.4 秒（`@keyframes justin`），最后一句 toast 说明存了什么。

⛔ 服务端「一个都没收」（`saved` 为空）只影响第 3 步（不点亮任何卡片），**不影响第 1 步** ——
**收到粘贴就回应，跟存没存成无关**（2026-10-14 第二轮把第一轮"没存成就不滚动"的口径推翻了）。

## 顶部状态条

页面标题下面那一条，从左到右（2026-10-14 三轮改造后定稿）：

| 段 | 内容 | 说明 |
| --- | --- | --- |
| ① 连接灯 | 一颗圆点 | **整条只有这一颗点**。连不上后端才变红（`setOnline(false)`，`/api/ping` 抛错时调） |
| ② ffmpeg / ffprobe | `ffmpeg ✓` / `ffprobe ✓` | 可用 `✓`、缺失 `✗` —— **文字对勾**，别再用绿/红圆点 |
| ③ yt-dlp | `yt-dlp 2026.08.19` | **版本号**，不是二进制名（原来报 basename 而它就叫 `yt-dlp`，界面上成了「yt-dlp yt-dlp」）；取不到写「未找到」 |
| ④ 下载适配器 | `下载适配器 4 个（3 专站 + 1 通用）` | 数量与分工由后端 `adapters[].fallback` 算出来；悬停 `title` 列名单并点明 `yt-dlp` 是兜底（YouTube / B站 / 小红书等都走它） |
| ⑤ 版本号 | `v0.1.0` | `/api/ping` 的 `version` |
| ⑥ 构建信息 | `build 6c3367dee3 · 2026-10-14 16:15` | 前半 = `web/app.js + style.css + index.html` 的 **md5 前 10 位**；后半 = 这三个文件的**最新 mtime**（`server.py::static_build()`） |

⛔ 两条别破坏：

1. **状态条里不许出现「预设 N 组」** —— 那是去水印框位记忆的条数，跟下载无关，放在这里只会让人误会（2026-10-14 用户问过「预设 3 组，预设的什么」后要求去掉）。要看预设数量去「批量去水印」。
2. **`build` 那串不是 git commit hash**，后面的时间**也不是提交时间**。工作区常带未提交改动，git HEAD 的时间会跟实际跑着的代码对不上；md5 跟着内容走、mtime 跟着落盘走，改了就是改了。时间**带年份**（`10-14 16:20` 跨年会有歧义）。

排障用法：把 `build` 那串和磁盘上 `md5sum web/*.js web/*.css` 对一下，就知道浏览器跑的是不是最新代码
（曾经因为"以为是缓存"浪费过排查时间，反过来也差点漏掉真 bug）。

回归：`.tmp/t_envbar.js`（40 项；含连接灯失败态、yt-dlp 当纯文本转义、构建信息缺时间/缺指纹的边界、适配器名单的引号转义）。

## 查找重复（素材查重）

入口：素材库工具条上的**「查找重复」**。把 `downloads/` 与 `uploads/` 里的图片和视频一起扫，
分成「重复组」摆出来，**每组说清是哪种重复**，**删哪些由你勾**（本模块**只读**，一个文件都不删）。

### 分两层查

| | 判据 | 组标签 |
|---|---|---|
| **精确重复** | 字节级一致（全量哈希相同） | **完全相同** |
| **近似重复** | 感知哈希（dHash-16）距离 ≤ 阈值 | **同一张图 · 仅分辨率不同** / **同一张图 · 不同压缩或格式** / **同一视频 · 不同清晰度** / **同一视频 · 不同编码** |
| **衍生** | 名字是 `X_去水印.ext` 而组里有 `X.ext` | **衍生 · 去水印成品**（单列，写清谁是谁的成品） |

组的明细里会写出两边的分辨率（`画面一致，2048×2048 ↔ 128×128、256×256`），
成员行还会单独写 `相似 97%，640×360` —— 用户要的就是"**是精确重复，还是仅仅分辨率不通**"这个区分。

### ⛔ 「组」不等于「等价类」—— 组内还要再聚一次类

并查集分出来的是**近重复组**（"画面像"就并进去），组内完全可能同时躺着几份**彼此字节完全相同**的文件。
2026-10-14 用户报的 bug 就是这个形态：一组 `画面一致，2048×2048 ↔ 1079×1079`，其中 4 份 `1079×1079 / 257.1KB`
**字节一模一样**，却全被打成「相似 85%，请自行确认」、一份都没预勾 —— 因为「完全相同」原来只跟**组里被保留的那一份**
（2048 原图）比，而这 4 份跟 2048 那份确实只是"像"。

修法：归组之后**组内再按全量哈希聚一次类**（克隆类），每个克隆类各留一份，其余预勾删除。连带三处一起改，否则还是错的：

- **`waste` / `waste_all` 要按「所有保留项」算**：组里现在可能有**多个保留**（原图 + 克隆类里留的那份）。
  原来 `waste_all = 总量 − 保留项[keep_i]` 会把克隆类留的那份也算成"可省"，虚报体积。改 `总量 − Σ所有保留项`。
  面板汇总那句也跟着从「**全部保留一份可省**」改成「**删到只剩建议保留的可省**」（`ddRenderStats()`）。
- **每份副本的原因要写清跟谁相同**：`完全相同（与「xxx.jpg」是同一份文件）`，而不是笼统的「完全相同」。
- **预勾判据改用「同克隆类」**，不再用「跟保留项的相似度」—— 否则 85% 那个门槛又把克隆挡回去了（症状就是原始 bug）。

组明细里再补一句「其中 N 份是完全相同的副本（只需留 1 份）」（纯精确组不加 —— 它的标签本来就是「完全相同」）。

实现上 `classify()` 签名没变，克隆聚类放在 `scan()` 里：辅助函数 `exact_classes(members)` 把成员按 `full` 分簇，
每簇用 `recommend_keep()` 挑一份当基准（优先无 `_去水印` 后缀的），落进 `clone_keep`（基准下标 → 簇大小）
与 `clone_of`（多余副本下标 → 基准名字），供 `m["keep"]` / `m["same"]` / `m["reason"]` 三处使用。

### 成本：五层，越贵的越少跑（`.tmp/dedup_probe.py` / `dedup_video.py` 量的）

| 层 | 成本 | 用途 |
|---|---|---|
| ① 比大小 | 零读取，整库 0.18ms | 预筛 |
| ② 头尾各 1MB 哈希 | ~2.3ms/个 | **只用来排除**（不同 ⇒ 必然不同） |
| ③ 全量 blake2b | 0.52GB/s（整库 1.86GB ≈3.6s） | 只对 ①② 之后的候选跑，算出的就是"完全相同" |
| ④ 图片 dHash-16 | ~39ms/张 | 图片近重复 |
| ⑤ 视频抽 5 帧 dHash | 1080p ≈1.3s / 4K ≈12.5s | **唯一贵的**，故只对"时长门"候选跑 |

实测：**只用大小预筛的结果与全量哈希完全一致**（省 60% IO）；**时长门把 406 对组合砍到 12 对（-97%）**，且零解码成本。

### 三条踩过的坑（改动时别破坏）

1. ⛔ **不要用 8×8 dHash**。实测它把 16×16 下距离 19 的两张图报成 0（太粗）。
   16×16 能把「同内容 2~19」和「不相干 116~140」干净分开（6 倍余量），阈值取 40 极安全。
2. ⛔ **「结构闸」`PHASH_MIN_BITS` 必须有**。dHash 比的是**相邻像素的大小关系**，平坦画面没有梯度：
   实测纯红、纯蓝、纯红 2048×2048、水平/垂直渐变**统统退化成全 0** —— 于是"纯红 vs 纯蓝"距离是 0，
   不设闸就会把两张毫不相干的纯色图判成重复。判据：置位数须落在 `[40, 216]`，
   否则这个哈希**不可比**（`usable_phash()` / `phash_distance(skip_flat=True)`，有效帧数为 0 就不连边）。
   真实照片实测置位数 81~140 / 256，离两端都远。
3. ⛔ **视频抽帧不能用 `-ss` 后置**（`-i` 之后再 `-ss`）——4K 60fps 上会顺次解码整片，实测把进程拖死。
   `media.grab_frame()` 用的是 `-ss` 前置，安全。**绝不整片解码**。

### 默认勾选口径（别乱替用户勾）

- 精确相同 → **预勾**。
- **组内克隆类** → 每类留一份，**其余全预勾**（判据是 `same`，即落在某个克隆类里）。这条**不受 90% 门槛约束** ——
  字节都一样了还谈相似度没意义，正是原始 bug 的成因（克隆跟保留项只有 85% 像，被门槛挡回去）。克隆类的基准那份**不勾**。
- 近重复 → 只预勾**相似度 ≥ 90%** 的（`NEAR_SUGGEST_SIM`）。分组阈值取 40（**尽量别漏**），
  预勾门槛取 90%（**别乱删**）—— 实测同一张图的裁切版 1079×1079 与 2048×2048 相似度只有 85%，
  确实该并进同一组，但替用户勾上太冒险。85% 这类**仍会列出来**，只是不勾，并注明「（近似，请自行确认）」。
- **涉及去水印衍生关系的一律两面都不勾**：原片删了没法重做、成品删了白做一趟，两面都有代价。
  这组的「可回收体积」显示 0.00MB。

删除走的是和卡片「删除」**同一条**后端接口（`/api/delete`），先弹一次确认、**真删不可恢复**。

### 指纹缓存：第二次扫描几乎零成本

`size:mtime` 当签名写进各目录的 `.vt-index.json` 的**同一条记录**里 —— 索引的键始终是**文件名**，
指纹用 `fp_*` 字段（`fp_sig` / `fp_head` / `fp_phash` / `fp_dur` / `fp_dims`）、
探测结果用 `probe*` 字段，同一条记录里各占各的字段、互不覆盖。
批量合并走 `core/util.py::index_merge` —— 逐条 `index_add` 是 load+save 每一条，O(n²) IO。
签名没变就直接复用。视频帧哈希只对候选算、也算进缓存，**每个文件一辈子最多解码一次**。

实测整库 55 个文件 / 1.78GB：**冷扫 18.6s → 热扫 0.02s**。

### 测试

- `.tmp/t_dedup.py` —— 核心离线单测（15 段 / 117 条；含"只读保证"：源码里没有任何删除调用；
  `[8b]` 专测组内克隆，**两种形态都测**——克隆在被保留项那个类里 / 克隆在另一个类里，分支不同，只测一种会漏）
- `.tmp/t_dedup_ui.js` —— 前端弹层 jsdom（62 条；`[12]` 钉"一组里出现 2 个建议保留 + 3 份预勾 + 判定配色走稳的那一档"）
- `.tmp/t_dedup_real.py` —— 真链路（31 条；自己在 8799 起服务，跑完断言 uploads 数量复原）
- `.tmp/dd_lib.py` —— 对真实素材库打一份摘要（只读，调 bug 时用）

## 目录结构

```
视频和图片工具箱/
├── app/                  ← 本仓库（git 管理）
│   ├── core/
│   │   ├── util.py       命名清洗 / 下载索引 / human / Canceled
│   │   ├── net.py        HTTP 客户端（Cookie 只发对应平台自家域）
│   │   ├── tasks.py      任务：进度 / 取消 / TTL 生命周期
│   │   ├── fetch.py      多线程分块下载 + 断点续传 + 外部进程封装
│   │   ├── media.py      ffprobe 探测 / 抽帧 / 缩略图 / 音视频合流
│   │   ├── watermark.py  delogo 管线（视频+图片，框规整，进度/取消）
│   │   ├── cookies_txt.py Cookie 解析（值 / 整行 / 整串都吃）+ 落成 Netscape cookies.txt（备用）
│   │   ├── yuanbao.py    视频号登录态（元宝 Cookie：校验 / 验活 / 脱敏）
│   │   ├── presets.py    水印预设区域记忆（键 = 平台+作者+分辨率）
│   │   └── dedup.py      素材查重：分层指纹 + 分组分类（只读，绝不删，见「查找重复」）
│   ├── downloaders/      ← 站点适配器（新增站点只加一个文件）
│   │   ├── base.py       统一模型 Content/Item/Format + Adapter 接口
│   │   ├── x.py          X：镜像三源（fxtwitter→vxtwitter→syndication）
│   │   ├── douyin.py     抖音：分享页 _ROUTER_DATA（yt-dlp 那条已被网关签名挡死）
│   │   ├── ytdlp.py      通用引擎：档位收敛 + DASH 音视频合并
│   │   └── wechat.py     视频号：元宝 Cookie 换链（已打通，见下方）
│   ├── server.py         本地网页后台（http.server，只监听 127.0.0.1）
│   ├── cli.py            命令行入口
│   └── web/              原生前端（无构建，改了刷新即生效）
├── downloads/  uploads/  成品 / 导入的本地素材（不入库）
├── data/                 预设、配置（Cookie 落盘为 0600）、缩略图缓存
└── .venv/                yt-dlp 隔离环境（不入库）
```

## 几条硬约束（改动前必读）

1. **Cookie 域白名单**：登录态只发给对应平台自家域。X 的 Cookie 绝不发 fxtwitter/vxtwitter。
2. **外部进程的 stderr 不能挂 `subprocess.PIPE` 不读**（64KB 写满会卡死，表现为"任务不动"）——
   统一走 `core/fetch.py::run_ff`。
3. **去水印的框必须先 `normalize_regions()`**：坐标来自网页拖拽，会有越界/倒拖/太小的脏数据。
4. **前端画布必须盖住画面本身**（`.mwrap` 壳 + `canvas{position:absolute;inset:0}`），
   不能盖舞台 —— 竖屏画面被压窄后，铺满舞台会让框横向偏 3.5 倍。
   改了框选相关代码后，用技能 `kylin-headless-chrome-snapshot` 量 `dx/dy/dw/dh` 全 0。
5. **`Canceled` 继承 `BaseException`**：分片重试用 `except Exception`，用 Exception 会被吞掉。
6. **删文件要顺手收走任务记录**（`TM.drop_for_path()`），且前端两个列表都要重取。
7. 改 `web/*` 刷新即生效；**改了 `.py` 必须重启服务**（重启前确认端口没被旧进程占着）。
8. **弹层里"悬浮在画面上"的按钮，居中别用 `transform:translateY(-50%)`**：全局
   `button:active{transform:translateY(1px)}` 会在**按下瞬间**顶掉这个 transform，
   按钮直接跳半个身高（如 64px 高的按钮跳 32px），鼠标还没松手目标就跑了 → `click` 落空。
   改用 `top:calc(50% - 半个高)` 定位居中即可免疫。**这种 bug 只有真实鼠标链路
   （CDP `Input.dispatchMouseEvent`）能测出来，JS `dispatchEvent` 会"假通过"。**
9. **验证前端交互别用 `dispatchEvent`**：它绕过真实命中测试与 `:active`/布局重排。
   用 `Input.dispatchMouseEvent(mouseMoved→mousePressed→mouseReleased)`，
   且**坐标必须"现测现点"**（抽帧是异步的，图片没加载完时 `.mstage` 高度不同、按钮位置会变）。
10. **解析 yt-dlp 的 `-J` 输出必须用 `json.JSONDecoder().raw_decode()` 只解第一个 `{`**，
    不能 `json.loads(整段stdout)`。本机北信源 VRV（`/etc/ld.so.preload` 的 `libvhook.so`）
    会往**每个子进程 stdout 追加**一行 `fd = -1, last error = ...`，位置**随机**：
    在 JSON 前 → `Expecting value: line 1 column 1`；在后 → `Extra data: line 2 column 1`
    （实测就是后者）。`core/media.py` 里那段"只截掉开头脏行"的写法对"脏行在结尾"无效，
    这正是 YouTube 解析"时好时坏"的原因。见 `downloaders/ytdlp.py::_load_first_json`。
11. ⛔⛔ **YouTube 进度卡死的真因是「协议」不是「编码」，别再用编码过滤去修**：
    YouTube 对**每一档分辨率都同时给 m3u8 版和 https 版**，且 **m3u8 版码率总是更高**
    （实测 1080p：`616` vp9 m3u8=6402k ↔ `137` avc1 https=2689k；1080p60：
    `312` **avc1** m3u8=7418k ↔ `299` avc1 https=3248k）。`bv*` 按画质取最优 ⇒
    **必然**挑中 m3u8 版 ⇒ 分片流的 `progress.downloaded_bytes/total_bytes` **为空**
    ⇒ 进度条永远 0、磁盘留 0 字节 `.part` + `.part-Frag1.part`。
    ⚠️ **加 `[vcodec^=avc1]` 是无效修法**（avc1 自己也有 m3u8 版，如 `312`），
    而且会**把 4K 档砍掉**（2160p 只有 vp9/av01，没有 avc1）。
    ✅ **正确修法**：`-S proto,res`（只排序、不排除）—— 同分辨率下优先 https 直连，
    高分辨率档一个不丢。实测落点：4K 视频 2160p→`315`/`401`、1440p→`308`、
    1080p→`299`、720p→`298`，**全为 https**，4K 可下且进度正常。
    **`-f`（过滤）与 `-S`（排序）的区别是这里的关键**：过滤会丢档，排序不会。
12. ⛔ **YouTube 4K 下到一半 403：换 `player_client`，别往代码上找**。
    2026 年 YouTube 把视频流迁到自研 SABR 协议 + 强制 PO Token 校验，默认 web 客户端
    拿到的**高码率直链**会在下到 **~60–70MB** 处被 CDN 判
    `ERROR: unable to download video data: HTTP Error 403: Forbidden`。
    特征：**1080p 及以下正常，只有 4K 档稳定中招**（同命令两次分别断在 61MB / 71MB；
    手工直跑与服务侧表现**完全一致** → 不是我们的 bug）。
    ✅ 修法：`--extractor-args "youtube:player_client=tv_embedded"`（走传统 DASH 端点），
    格式表与 web 一致 —— 实测同 url 越过 403 点、2160p 正常下完。
    ⚠️ `android` 客户端也能绕过 403，但**格式表缩水**（4K 档 total 从 712MB 掉到 28MB，
    只给低清晰度），**别用**。
    该参数只对 YouTube 域名下发（`_is_youtube()`），对 B站等站点无副作用（已实测）。
13. ⛔ **去水印别再上 AI 修补（LaMa / ProPainter / lama-cleaner）**，本机跑不动且效果更差。
    实测 `Carve/LaMa-ONNX`（199MB）+ onnxruntime CPU（**兆芯 KX-7000，无 CUDA**）：
    - **单帧 8~15 秒**（onnxruntime 对该 CPU 无专门优化，调优无效：默认 10.25s、
      `ORT_ENABLE_ALL` 11.4s 反而更慢、单线程 14.4s、并行模式直接 `std::bad_alloc`）
      → 视频**不可用**（30 秒 720p 约 900 帧 ≈ 5 小时）；真正好用的视频模型还要 GPU。
    - 效果上**反而更差**：对「大面积浅色水印」LaMa 会填成**纯白色块**，比 `delogo` 的糊块更扎眼。
      （已排除用法问题：四种归一化逐一验过，`x/255` 正确、`mask` 语义正确、模型能重建纹理。）
    - ✅ 真正有效的改进是 `cv2.inpaint`（Telea/Navier-Stokes）：把框外像素**向内渐变扩散**，
      边界过渡自然，小水印基本无痕，且**毫秒级**（480×852 单帧 24ms~1.4s）。
14. **视频走 OpenCV 路径时音轨必须单独搬**。
    喂进 ffmpeg 的是 `rawvideo` 管道，**压根没有音频流**，`-c:a copy` 会得到无声视频。
    ✅ 正确流程：`解码成 rawvideo → 逐帧 inpaint → 编码成无声文件 → 再用
    `-i 静音文件 -i 原文件 -map 0:v -map 1:a? -c copy` 搬回原音轨`（实测音轨参数逐项一致）。
    另有：rawvideo 管道 `read(n)` **会短读**，必须循环读满 `W*H*3` 才是一帧。
15. **框要比水印四周多留一圈**，框切到字的下沿就会残留半截字（实测踩过：框底到 786、
    字底到 795 → 「简」字下半截留在画面上）。弹层 `#wmTip` 已写这条提示。
16. ⛔ **`av` 必须锁 14.x，升级到 19 会直接炸**（语音转文案用 faster-whisper）。
    faster-whisper 只声明 `av>=11`，但 `faster_whisper/audio.py` 用了 `metadata_errors` 参数，
    而 **av 19 已把它移除** → `TypeError: open() got an unexpected keyword argument 'metadata_errors'`。
    装依赖时务必 `pip install "av==14.2.0"`。
17. **faster-whisper 转中文必须加 `initial_prompt` 引导简体**：
    不加会输出繁体（"上映一個月票房突破15億"）；加上
    `initial_prompt="以下是普通话视频解说的字幕，请用简体中文输出。"` 后变简体，
    **而且还更快**（实测 36.3s vs 42.3s）。
    另：`model.transcribe()` 返回的是**生成器**，必须 `list(segs)`，否则只能遍历一次。
18. **模型选 small 不要选 medium**（本机实测，60 秒中文音频）：
    `small` 加载 2.6s / 转写 37.2s（**1.61x 实时**）；`medium` 加载 208s / 转写 110.4s
    （**0.54x 实时**），慢 3 倍而质量提升不明显。模型实例按尺寸缓存，别反复加载。
    ⚠️ **`base` 虽然 7.15x 实时（快 4 倍）但不要用**：中文质量明显下降
    （同一段"你们不知道商量有多坏" → base 识别成"商量有不会"，还混进繁体"明確/邪惡"）。
    文案是拿去写公众号的，错字代价太高。
19. ⛔ **转写线程数别图省事用 `os.cpu_count()`**（`transcribe._pick_threads()`）。
    本机 8 核但**常态 load 就在 9~10**（桌面 + 微信 + Chrome + 北信源水印常驻），
    开满 8 线程会让线程互相争抢、上下文切换吃掉大量时间。
    实测同一段 256s 音频、同样高负载：8 线程 **313s**，4 线程 **114s（快 2.75 倍）**。
    诊断手法：直接读 `/proc/<pid>/stat` 的 utime+stime 差值算实际占用核数 ——
    "开了 8 线程却只跑出 4 核"就是争抢的信号（`ps` 看到的 %CPU 是生命周期平均值，没用）。
20. ⛔ **成品名会顺延，但半截分片名必须带来源 id**（`fetch._part_base`）。
    - 成品：`unique_path()` 让 `{标题}_{档位}.mp4` 顺延成 `_2`/`_3`，**绝不覆盖**。
    - 但它**只看成品**（为了断点续传），而分片名原来是 `{dest}.partN`，
      于是**同名不同来源共用同一批半截**：推文 A 下到一半中断留下 `ANIMALS_1280p.mp4.part0..N`，
      改下同名推文 B 时成品不存在 → 返回原名 → 下载器把 A 的分片当成自己的跳过 →
      产出「**A 的前半截 + B 的后半段**」的损坏 mp4，界面还显示下载完成。
    - ✅ 修法：`download_url(part_tag=content.id)`，分片名变
      `ANIMALS_1280p.mp4.<status_id>.part0`。同源重跑照旧续传，异源各下各的。
    - 验证用**受控实验 + 对照组**：伪造两个内容不同但同名的下载源，A 下到 1/4 取消，
      再完整下 B —— 修复后 B 的成品 100% 是 B；**对照组（不传 tag）约 50% 是 A 的字节**。
      没有对照组，这个「通过」不能作为依据。
    - 副作用：旧格式（不带 tag）的半截分片不再被续传，会重下一遍 —— 这是安全方向。

## 视频号

**已打通**（2026-10-09 实测），走「元宝登录态」换链，**全程不需要解密**：

1. 元宝 Cookie → `POST yuanbao.tencent.com/api/weixin/get_parse_result` → `playable_url`（自带 token + eid）；
2. token + eid → `POST channels.weixin.qq.com/finder-preview/api/feed/get_feed_info` → h264 / h265 两个直链；
3. `finder.video.qq.com/...stodownload?encfilekey=…` 直链是**明文 mp4**，带 Referer 多线程下载即成品。

⚠️ 唯一前提：**元宝（yuanbao.tencent.com）的登录 Cookie** —— 匿名调官方接口与元宝接口都是 401（实测）。
在网页版「高级设置 → 视频号 · 当前登录账号 → 粘贴 Cookie 登录」里填一次
（落 `data/config.json` 的 `cookies.yuanbao`，权限 0600）长期复用；过期表现为元宝接口 401 / `code != 0`。

取法（界面里也内置了这份四步说明）：yuanbao.tencent.com 登录后 → 在页面上**右键 → 检查**
（元宝页面 F12 常被屏蔽）→ 切 **Network（网络）** 标签 → 刷新页面或随便发一句话 →
点 `getuserinfo` / `list` / `version.json` 这类 `yuanbao.tencent.com/api/...` 请求 →
右侧 **Headers → Request Headers → Cookie** 整串复制 → 粘贴保存。多行 / 单行 / 整串都能粘，后端 `yuanbao.normalize()` 会规整，
且会校验必须含 `hy_user`/`hy_token`，否则拒绝。
卡片会显示当前是哪个微信（头像/昵称），可「删除登录态」换账号。

⛔ 不要用 console 的 `document.cookie`：`hy_user`/`hy_token` 是 HttpOnly，JS 读不到，复制出来不含登录态。

⛔ **不提供扫码登录**：纯 HTTP 复刻卡在 `cauth/login` 的设备指纹校验（需伪造 Qimei + X-ID/X-Token），
服务端拉浏览器又在实机上渲染不出窗口。两条路都试过，结论见 `../交接文档.md`「扫码登录：已放弃」。

`downloaders/wechat.py` 里另留了一套 WASM 解密兜底（`wasm/`，微信官方 ISAAC64 模块）：
只在直链不是明文 mp4 时才触发，本通路不提供 decode_key，真遇到会**明确报错**而不是给坏文件。

## 抖音（走分享页，**不走 yt-dlp**）

⛔ **结论先摆这儿：yt-dlp 下不了抖音，给多少 Cookie 都是 403**（2026-10-14 实测，别再回头试）。

抖音在边缘网关挂了 `ArgusSecurityPlugin`，`/aweme/v1/web/aweme/detail/` 现在要
`x-tt-argus` 头 + `uifid` 头 + **网页 SDK 算出来的签名**。实测三连：

| 请求 | 响应 |
|---|---|
| 什么都不带，或只带完整 Cookie | `403 Blocked by ArgusSecurityPlugin Uifid Not Found` |
| 再补 `x-tt-argus: 1` | 同上（这个头只填 `1` 已经不够了） |
| 再补真实 `uifid` 头 | `403 … Signature Not Found`（网关要真签名了） |

纯 HTTP 客户端生不出这个签名 —— yt-dlp 源码里就留着
`# TODO: Run verification challenge code to generate signature cookies`。
响应里那句 "Uifid Not Found" 是**误导文案**，和 Uifid 没关系，别去折腾它。

✅ **能走通的是分享页**（`downloaders/douyin.py`，priority 15 接管所有 `douyin.com` /
`iesdouyin.com` 链接）：iPhone UA 请求 `https://www.iesdouyin.com/share/video/<id>/`，
页面里的 `window._ROUTER_DATA` 直接含 `item_list[0].video.play_addr`：

- `/playwm/`（带水印）→ `/play/` 拿无水印直链；
- 改 `ratio` 参数取档位（540p / 720p / 1080p / 2k / 4k）。实测同一条视频
  540p=3.5MB / 720p=3.9MB / 1080p=6.0MB；**超过源分辨率的档会返回同一份文件**，
  所以只列到源短边为止（用 `video.width/height` 判断），不虚标清晰度；
- 直链 host 是 `aweme.snssdk.com`，支持 Range ⇒ 复用多线程分块下载器（带断点续传）。

⛔⛔ **分块下载必须声明 `Accept-Encoding: identity`**（2026-10-14 真实事故，
用户报「720p 下下来播不了，另两档正常」）：

抖音 CDN 对**某些档位**（实测这条视频的 720p）会**无视 Range、改用 gzip 把整段发过来**
（`Content-Encoding: gzip`，43.9MB 一次性发）。分块管道是"按字节偏移直接拼文件"、
HTTP 层不替我们解压 ⇒ 拼出来的 `.mp4` 其实是 **gzip 流**：
文件头是 `1f 8b`（不是 `ftyp`）、没有 `moov`，播放器报 `moov atom not found`。

取证（同一档位、只改一个变量）：

| 请求头 | 结果 |
|---|---|
| `Accept-Encoding: gzip, identity`（旧默认） | **ce=gzip → 损坏文件** |
| `Accept-Encoding: identity` | 206 + 正常 mp4 ✓ |
| 不发 `Accept-Encoding` | 206 + 正常 mp4 ✓ |

连带效应：`enrich()` 的 HEAD 也被误导（体积显示 0.00MB），改成 identity 后恢复 42.07MB。

**两道锁**（都别拆）：`core/net.py::Http.headers()` 默认只发 `identity`；
`core/fetch.py::_stream_to()` 再显式钉一遍（分块下载的直接责任人）。
回归测试 `.tmp/t_dy_gzip.py`（离线层断言全仓没有 `gzip` 声明 + 联网层真打 720p 档验魔数）。

**这条通道必须带 Cookie，但只需要 `ttwid` 一个字段**：实测只带它就够
（分享页 `_ROUTER_DATA` 里就有 play_addr）；一个字段都不带的匿名请求只带引擎
自带的 `__ac_nonce`，服务端回 1399 字节空壳页、没有任何视频地址。
所以「抖音 · 下载 Cookie」那张卡片是真起作用的，不是摆设。

⛔ **取法别走 Network**（用户 2026-10-14 反馈：请求列表太长、Cookie 串又大又难找）。
走 **`F12` → `Application`（应用）→ `Storage → Cookies → https://www.douyin.com`**，
在过滤框输字段名，双击那一行的 **Value** 复制即可。

界面为此给了**两个分项框 + 「拼接并保存」**（用户 2026-10-14 要求）：

- `ttwid` 一格、`sessionid` 一格，都是"只粘值、不带名字"；点按钮拼成
  `ttwid=…; sessionid=…` 再存（`app.js::joinDouyin`）。拼好的串会**回填到下面的整串框**，
  让用户看得见最终格式；分项框随后清空。
- ⛔ **为什么不再让用户"在 Application 面板里选中两行一起复制"**：用户实测**不行**
  （2026-10-14）。DevTools 复制出来的形状不稳定（可能每行只有一列、也可能分隔符不是 Tab），
  拿它当输入等于把成败交给浏览器的复制行为。分项框把字段名固定死，没有猜测空间。
- **整串输入框保留**（老路兼容）：Network 里请求头 Cookie 那一行，或手写
  `ttwid=…; sessionid=…`，都认。

`core/cookies_txt.py::parse()` 仍是**宽容解析**，顺序
`_from_app_rows` → `yuanbao.normalize` → `_from_bare_value`：

- `_from_app_rows`：Tab 分隔的整行 / 整张表按**列结构**解析，**只取前两列**。
  ⛔ 两个坑：① 不能沿用 `normalize()` 的「整行不含 `=`」判据 —— cookie 值里带 `=`
  （base64 padding、URL 编码残留）很常见，一含就会被按分号拆、名字里混进值的前半截；
  ② **不能先把空列滤掉再按位置取**（2026-10-14 修）—— 某列一空，Name/Value 的位置整体前移，
  取到的"值"会是后面某一列。
- `_from_bare_value`：只粘了**一个值**（没有名字）→ 按 `ttwid` 补上名字。
  纯数字（更像视频 ID）、网址、太短的半截串一律不收。
  ⛔ **另加一道形状拦截**：长得像 sessionid（`^[0-9a-f]{16,64}$`）的裸值**不收** ——
  否则用户把 sessionid 的裸值粘进「整串」框，会被补成 `ttwid=<sessionid>`，
  **把原本好用的 ttwid 覆盖坏**。撞上这种情况 `validate()` 明确回一句
  「请用上面的 sessionid 分项框」，而不是含糊报个格式错。

### 「当前登录账号」：抖音也有，但接口不在 www.douyin.com 上

2026-10-14 实测（含**真假 Cookie 对照**，方法是本技能里通用的那一套）：

| 接口 | 结果 |
|---|---|
| `www.douyin.com/aweme/v1/web/user/profile/self/` | **给 sessionid 也一律** `status_code: 8「用户未登录」` → 这条别试了（它要 web 端那一套 msToken/签名） |
| `aweme.snssdk.com/aweme/v1/user/profile/self/?aid=1128` | **认 `sessionid`**：真会话 → `status_code: 0` + 完整 `user`（nickname / avatar_thumb / uid / sec_uid / follower_count / aweme_count）|
| 同上，喂一个编的 32 位 hex | `status_code: 8` ← **对照组**，证明它真在验，不是永远回好话 |

⇒ **认账号只要 `sessionid` 一项**（`ttwid` 都不用带），与下载完全解耦：

- **下载**：`ttwid` → iesdouyin 分享页；
- **认账号**：`sessionid` → `aweme.snssdk.com`（`downloaders/douyin.py::whoami/acct_info`）。

⚠️ **别过度拿它验活**：这条能证明"有身份、能读到自己"，但**不等于**能下更高清了 ——
本项目实测这个视频 1080p 在不带 Cookie 时照样拿得到，抖音对公开视频本来就不卡登录。

实现要点：

- `sessionid_of()` 从整串挑凭据；`acct_info(check=False)` 只做本地判断（**不发请求**）；
- `server.douyin_payload(check=...)` 把 `acct` 嵌进原有状态块；`/api/ping` 走 **`check=False`**
  （那是高频轮询接口，绝不联网）；
- 卡片验活通过时，**正位换成昵称 + 头像**（视频号那张同款形态）；登录了但没 `ttwid` 会
  明确写「已登录，缺 ttwid / 还是下载不了」，不拿"已登录"糊弄过去；
- 保存时**验活失败不拦保存**（`ttwid` 单独就够下载），只在提示里说清"sessionid 没过、不影响下载"。

### 与「视频号」的 Cookie 各存各的

| | 视频号 | 抖音 |
|---|---|---|
| 归谁用 | 自家 HTTP 客户端（`core/net.py`） | 自家 HTTP 客户端（`downloaders/douyin.py`） |
| 配置键 | `cookies.yuanbao` | `cookies.douyin` |
| 磁盘 | 只在 `data/config.json`（0600） | 同上，**另**派生 `data/cookies/douyin.txt`（0600） |
| 发给谁 | `yuanbao.tencent.com` | `douyin.com` / `iesdouyin.com`（直链 CDN **不发**）；认账号那次额外发 `aweme.snssdk.com` |
| 验活 | 有接口可问（`whoami`，能识别失效） | 有（`sessionid` → `profile/self`，见上节）；没配 sessionid 就只说"认不出账号" |
| 界面 | 「视频号 · 当前登录账号」卡片 | 「抖音 · Cookie / 登录账号」卡片 |

### `core/cookies_txt.py`：解析是主用，落成 cookies.txt 是备用通路

抖音改走分享页后，`data/cookies/douyin.txt`（粘贴串 → Netscape 格式）**当前没有消费者**：
它当初是给 yt-dlp 的 `--cookies` 准备的。**保留**的理由与机制（顺带说清整条链路）：

1. 用户粘的可能是 Application 面板里**一格的值** / **一整行** / **一整张表**，
   也可能是 Network 里那串 `name=value; name=value`（`parse()` 三种都吃，见上）；
2. `to_netscape()` 把归一化串转成 Netscape cookies.txt（7 列 Tab 分隔，域固定 `.douyin.com`）；
3. `server.douyin_cookie_path()` 每次 `make_ctx()` 时重写一遍（内容小，**自愈**：被删/被改都会回到正确内容；
   未配置时顺手删掉派生文件，免得上一任 Cookie 被继续用）；
4. `Ctx.cookies` 里**任何以 `_file` 结尾**的键都会被 `ytdlp._cookie_args()` 拼成 `--cookies <路径>`
   （`ytdlp_file` / `douyin_file`）。yt-dlp 哪天把抖音签名补上了，这条通路不用改代码就能接上。
   👉 **落成文件这一步才是"备用"的部分；解析这一步抖音在用。**

⛔ **踩过的坑：`--cookies` 只认文件，不认字符串**。用户手上永远只有请求头那串，
所以要有个"串 → Netscape 文件"的转换层。yt-dlp 加载时用 `jar.load()`
（`ignore_discard=True, ignore_expires=True`），写会话 cookie（expiry 0）也不会被丢。

⛔ **`/api/config` 不许碰登录态键**（`server.LOGIN_COOKIE_KEYS`）：它的语义是"空值 = 删掉"，
而「保存设置」时那几个 Cookie 输入框本来就是空的 —— 不挡的话，点一下「保存设置」就会把已存的
登录态悄悄抹掉（2026-10-14 修掉的老坑）。

## 依赖

- Python ≥ 3.8（本机用 `.venv` 里的 3.13），标准库为主；
- `yt-dlp`（装在 `.venv`，外部命令调用，本仓库代码不 import 它）；
- `opencv-python-headless` + `numpy`（**「智能修补」去水印必需**，装在 `.venv`）；
- `rapidocr-onnxruntime`（字幕 OCR，**当前未接入界面**，只做了可行性验证）；
- `faster-whisper` + `av==14.2.0`（**语音转文案必需**，`av` 不能升到 19）；
- `ffmpeg` / `ffprobe`（系统包，去水印、抽音频与音视频合并必需）。

装依赖的命令（`.venv` 在本仓库之外，**重建环境时必须重装**，否则对应功能会静默退回/报错）：

```sh
cd /media/lieefu/aiwork/workbuddy/视频和图片工具箱
TMPDIR=$PWD/.scratch HOME=/home/lieefu ./.venv/bin/pip install \
    opencv-python-headless numpy faster-whisper "av==14.2.0"
```

⚠️ 本机 `/tmp` 是 **10MB 的 tmpfs**，pip 装包会报 `OSError: [Errno 28] 设备上没有空间`。
**必须带 `TMPDIR=` 指向工作区**，否则装不上。

⚠️ **`opencv-python` 与 `opencv-python-headless` 绝不能共存**：两者装进同一个 `cv2/` 目录，
卸载任一个会把另一个的文件一起删光（实测卸载 GUI 版后 headless 版直接 `ModuleNotFoundError`）。
`rapidocr-onnxruntime` 会带进 GUI 版，装完必须清掉并修回：

```sh
TMPDIR=$PWD/.scratch ./.venv/bin/pip uninstall -y opencv-python
TMPDIR=$PWD/.scratch ./.venv/bin/pip install --force-reinstall --no-deps opencv-python-headless
```