dsh-video2text

粘贴视频链接，得到「发布文案 + 口播逐字稿」；同时给 agent 两个工具，让它能直接读文字稿、看画面。

English · 中文

https://github.com/user-attachments/assets/b2129376-e838-494e-9b89-7041f4acf57c

17 秒 · 贴微信视频号链接 → 入列 → 转写 → 逐字稿

抖音、小红书、微信视频号、B站、YouTube 的分享链接，变成发布文案、逐字稿、字幕和章节稿。媒体先落盘，转写没跑完就能先看片子。

以前取一条视频的文案要开网页、复制简介、手动听写、自己排版；批量十条就是十次重复。插件把解析、下载、转写、对齐、排版收进侧栏，产物落在一个目录里，可以直接打开、导出，或交给 agent 继续加工。

同一条视频，agent 也能自己读：video_text 拿带时间码的文字稿窗口，video_frames 拿一张带每格时间点的画面拼图（或某一秒的高清单帧）。不需要打开面板，也不需要它理解任何内部概念。

能做什么

能力	说明
平台	抖音 / 小红书 / 微信视频号 / B站 / YouTube / 本地音视频
转写	云端 Qwen3-Omni（中文标点与专名更准）或本地 mlx-whisper / whisper.cpp
播放器	自绘控件、逐句同步高亮、字幕、倍速、画中画、全屏
时间轴	默认按标点切句 + 分片内插值；需要时一键做词级对齐
导出	发布稿（自动章节）/ 字幕 SRT / 画面速览 JPG（区间抽帧拼版）/ ZIP
账号	抖音、小红书扫码；视频号扫码 + 会话验证，缺登录时直接引导
任务	搜索、按天分组、重试复用原卡、删除、从其它目录导入；菜单里可直接在文件夹打开任务目录
交给 agent	「问 AI」新建会话、切到任务工作区、预填上下文
读视频（agent）	video_text / video_frames 两个工具：逐句文字稿窗口、带时间点的画面拼图、单帧高清；传媒体路径或 vid_xxxxxxxx，长任务自动转后台

安装

从 GUI：侧栏 Plugins → 添加插件 → 填 dsh-video2text。

从命令行：

dsh plugin --profile web add dsh-video2text
# 想跟最新提交而不是发布版：dsh plugin --profile web add "github:vlln/dsh-video2text"

两条路径都在干净环境里验证过（dsh 0.2.1-rc.1）。装完重启 dsh web —— Node half 在启动时注册，刷新页面不会出现面板。确认方法：侧栏出现「视频转文案」，贴一条 B 站链接回车，几秒内出现任务卡与封面；转写完成后「导出 → 发布稿」应下载一个 .publish.md。

运行环境：

• macOS（视频号解密与本地转写依赖 macOS 工具链；其他平台未验证）
• Python 3.9+、ffmpeg、node
• 视频号需要 playwright 与本机 Chrome：pip install playwright
• 本地转写需要 mlx-whisper（Apple Silicon）或 whisper.cpp；只用云端转写可以不装

不装插件，只要 skill

插件的 skills/video2text/ 就是完整的 video2text skill（引擎脚本 + SKILL.md），可以不装插件直接取用：

git clone --depth 1 --filter=blob:none --sparse https://github.com/vlln/dsh-video2text
cd dsh-video2text
git sparse-checkout set skills/video2text      # 只拉这一个子目录

装给别的 agent（例如 ~/.claude/skills/video2text）时，要让 SKILL.md 和 scripts/ 同级：skills/video2text/skills/video2text/scripts 是指向引擎目录的相对软链，整个拷出去会断，所以分开拷——

mkdir -p ~/.claude/skills/video2text
cp skills/video2text/skills/video2text/SKILL.md ~/.claude/skills/video2text/
cp -R skills/video2text/scripts ~/.claude/skills/video2text/

装好先自检：python3 ~/.claude/skills/video2text/scripts/video2text --status（抖音还要先 --setup-douyin 装解析组件）。

用起来

入列即转写

粘贴链接按回车（或点「开始」）直接建任务，没有「预览 → 确认 → 开始」的往返。任务名就是抓到的视频标题，封面、作者、时长随元数据补上并写进任务记录，刷新和搜索都在。本地文件用文件名兜底。

边转边看

媒体下载完立刻落盘，播放器马上可用，转写在旁边继续跑，逐字稿完成后原地出现。多个任务并行，互不阻塞。

播放器 + 逐字稿

自绘控件：播放/暂停、拖拽、倍速、字幕、跟随高亮、画中画、全屏。逐字稿按句同步高亮，点一句跳到对应时间。

键盘：空格 播放/暂停、←→ 快退快进、↑↓ 切任务、/ 搜索。

时间轴有两种状态，标题下的胶囊会标出来：估算（插值）和 精确（做过对齐）。

对齐（一次性动作）

默认不做词级对齐：云端转写后按标点切句、在分片内按字数插值时间，对连续口播通常只差零点几秒，而且不需要本地模型。

需要更准的边界时点「对齐」：用本地 whisper 的词级时间重算每句起止，只更新 json/srt，不重转、不改文案。对齐中会显示进度条和实时日志。

导出

三个出口，够用且不重复：

选项	产物
发布稿（带章节）	标题 / 发布文案 / 自动章节 / 正文 / 字数语速
字幕 SRT	逐句字幕
画面速览（JPG）	选中区间抽帧拼成一张图：角标带时间，页眉写区间/帧数/间隔
全部（ZIP）	上面两份 + sidecar JSON

画面速览：在播放器进度条上拖动框选区间（单击仍是跳转），任务下方会出现「已选区间 1:07 – 2:29 · 81s」，并带一张 4×3 的预览缩略图：

• 拖动选区两端的手柄微调起止；双击手柄输入精确时间（2:30）
• 预览图点开可看大图，不满意直接改区间，再点「导出速览」
• 帧数不用选——按区间长度自动定（约 48 帧；10s 的片子 0.5s 一帧，11 分钟约 14s 一帧），始终输出一张 JPG

问 AI

选中一条任务点「问 AI」：新建会话、自动切到任务目录所在的工作区，并把上下文（标题、来源、时长、输出目录、文字稿/字幕/sidecar/媒体的绝对路径）填进输入框。回车就把活交给 agent —— 压稿、重写标题、切片段、跑批量。

工作区是「所有任务的上一级目录」，agent 能一并管理其它任务的产物。插件只读选择、不创建：侧栏里没有这个工作区时，会提示你用 Add workspace… 指一次。

设置

右上角「设置」，两段：

• 登录态：抖音 / 小红书 / 视频号的状态与扫码入口，「验证会话」会给绿/红反馈
• 服务与密钥：云端转写的 provider / model / base URL / 密钥（默认隐藏）、小红书服务地址、DouK 路径、本地模型、分片长度、浏览器 Cookie、YouTube PO token

每个字段旁有 ?，悬停即显用途说明。

任务列表

按今天/昨天分组、可搜索；每条右侧 ⋯ 里有「复制链接」「删除任务（含文件）」。缺登录时任务进入「需要登录」状态，卡片上直接扫码，扫完自动重跑。

agent 直接跑脚本的结果也会出现

面板会扫描以下目录，把含 sidecar JSON 的子目录收编成任务（标 imported）：

1. $DSH_HOME/data/dsh-video2text/out
2. 环境变量 VIDEO2TEXT_IMPORT_DIRS（: 分隔）
3. 插件配置 importDirs（逗号分隔）

导入的任务是只读收编：删除只从列表移除、不删磁盘，媒体保留策略也不会碰它们。

给 Agent 用（video_text / video_frames）

装上插件后，agent 直接就能用（不用打开面板）：

「用 video_frames 看一下 ~/Movies/talk.mp4 的 3:00–4:00，告诉我画面在讲什么」

「用 video_text 读 ~/Movies/talk.mp4 第 8 分钟附近的文字稿，概括三点」

这个包同时提供一个独立于面板的插件行 dsh-video2text/inspect，给 agent 两个工具：

工具	输入	输出
video_text	媒体路径或 vid_xxxxxxxx、可选 from/to	带时间码的逐句文字稿；没转写过就起后台任务
video_frames	同上，另加 mode(shots/uniform)、size(overview/detail)、at	一张拼图（含每格时间点）或某一秒的高清单帧

要点：

• 不需要 Job ID：第一次传媒体文件路径，工具返回一个按文件指纹算的 vid_<8位hex>，之后传它即可（同一文件永远同一个 id）。
• 25 秒软超时：转写/长视频抽帧超过 25 秒就转成后台任务（v2t-video-<id>），完成时由 DSH 发会话内通知；工具调用本身立刻返回 status: running，再用同一个 vid 调一次就拿到结果。
• 同素材只跑一次：重复/并发请求复用同一个后台任务，不会重复转写。
• mode: shots 只保留画面真的变了的帧（幻灯片、界面、字幕切换），用的是 dHash 感知哈希，不是 ffmpeg 的 scene（后者对幻灯片慢过渡几乎不敏感）。
• 缓存：$DSH_HOME/data/dsh-video-inspect/<vid>/（媒体、转写、拼图、请求结果各一份），与面板的 out/ 无关。
• 关掉面板（- id: dsh-video2text + disabled: true）后，这两个工具照常工作。
• 只想隐藏侧栏入口、不想动插件行：在 DSH 的 Plugins 页找到 dsh-video2text，把配置项 showEntry 关掉，刷新页面生效——agent 工具不受影响。
• 登录态与各项设置统一在 Settings → 视频转文案；插件页只留 showEntry 一个开关。

# cordis.patch.yml 里两行，可分别开关
- insert:
    - id: dsh-video2text          # 面板（人）
    - id: dsh-video2text-inspect  # 工具（agent）

支持 mp4/mov/m4v/mkv/webm/avi/flv/ts/wmv；纯音频只出文字稿，抽帧会明确报 [video:no-video-stream]。

数据与权限

内容	位置
任务与产物	$DSH_HOME/data/dsh-video2text/out/<任务ID>/
任务索引	$DSH_HOME/data/dsh-video2text/jobs.json
模型缓存	~/.cache/video2text/hf（跨实例共享）
引擎配置（含密钥）	~/.config/video2text/config.json（600）
扫码会话	~/.cache/video2text/chrome-profile 等 Chrome profile

• 密钥只在本机配置文件里，界面默认隐藏；不向任何第三方上报使用数据。
• 转写选「云端」时音频分片上传到配置的 ASR 服务，选「本地」不出本机。媒体默认按 14 天 / 5 GB 清理，只删媒体，文案和字幕保留。

常见问题

症状	原因 / 处理
侧栏没有「视频转文案」	没重启 dsh web；或 boot 日志里有 plugin tree failed to load
任务一直「需要登录」	对应平台登录态失效：点卡片上的「扫码登录」，完成后会自动重跑
发布文案是空的	本地文件没有平台描述；或旧任务当时没存该字段，重跑一次即可
时间轴标着「估算」	没做过词级对齐。点「对齐」精修，只更新 json/srt，不重转
导出按钮不见了	没有逐字稿（转写失败 / 无口播）时不显示导出菜单
云端转写很慢	受服务端排队影响，与分片大小关系不大；可切「本地」后端
小红书批量失败	本地 XHS-Downloader 没起（设置里有地址），会回退 yt-dlp
模型下载卡住	缓存在 ~/.cache/video2text/hf；换 -q4 量化模型更快

YouTube 的 bot 校验

YouTube 对无登录态请求返回 Sign in to confirm you're not a bot。社区解法是 PO token（provider 造 token + yt-dlp 插件交付）。按网络环境选：

网络	该用什么
家宽 / 普通出口	PO token：起 provider + 装 bgutil-ytdlp-pot-provider 插件（详细步骤）
机房 IP / 代理出口	必须 Cookie（设置 → 浏览器 Cookie 填 chrome），PO token 不绕过 IP 级限制
临时看一条	直接 --cookies-from-browser chrome 最快

已知限制

• 平台登录态会过期：视频号（元宝）、抖音（DouK + Cookie）、小红书（本地 XHS-Downloader）。失效时任务进入「需要登录」，卡片上扫码即可。
• 抖音要先装 DouK 解析组件：video2text --setup-douyin（默认装到 ~/.local/share/video2text/DouK，幂等，坏了也能修）。别装 /tmp——会被系统清理，之后任务会报 [service:douyin]，账号卡片上会标「缺 src/」。
• 长视频的云端转写受服务端排队影响（16 分钟视频约 4 分钟），分片大小不是瓶颈。
• 一个平台一份登录态，暂不支持多账号并存。
• 只在 dsh 0.2.1-rc.1 上验证通过，其它版本未验证。

卸载：dsh plugin --profile web remove dsh-video2text，再重启 dsh web。

与 skill 的关系

插件自带 skills/video2text（完整可跑：SKILL.md + scripts + docs + examples），首次加载软链到 $DSH_HOME/skills/video2text，agent 通过常规发现路径读到它 —— 不给 agent 新增工具。

不想装插件、只想用 skill？直接取仓库里这一份即可：

git clone --depth 1 https://github.com/vlln/dsh-video2text
cd dsh-video2text/skills/video2text
cp -R skills/video2text ~/.agents/skills/video2text   # 或你自己惯用的 skills 目录
python3 scripts/video2text "https://www.bilibili.com/video/BV…" --out ./out

更新记录

见 CHANGELOG.md。

参与开发

有问题、想法或使用场景，去 Discussions 说；本地调试与发版见 docs/development.md。

许可

MIT。运行时通过 HTTP/CLI 调用上游工具，不链接其代码：yt-dlp（Unlicense）、DouK-Downloader 与 XHS-Downloader（GPL-3.0）、bgutil-ytdlp-pot-provider（MIT）。