前言¶
做短视频复盘、口播稿整理或会议录像归档时，常见做法是自己听写，或把文件丢进第三方网页再导出字幕。前者费时，后者对本地路径、批量处理和 Agent 对话里的自动化都不友好。下面介绍 SkillHub 上的社区 Skill「阿里云百炼-视频转文字」（坐标 @user_238e6fa6/aliyun-video2text，版本 1.0.0）：在 Agent 侧按通用 SKILL.md 约定触发后，用本地脚本完成抽音、上传与调用阿里百炼语音识别，把结果以结构化 JSONL 返回。
这是什么¶
一句话定位：把本地视频文件里的语音提取出来，经阿里云 OSS 临时存储后，调用阿里百炼 Paraformer-v2 转写 API，输出文字文案。
- 出品与维护：SkillHub 分类为
content-creation，来源为community，发布者为user_238e6fa6（SkillHub 页面标注作者为托利亚斯）。 - 解决的问题：在对话里用自然语言描述需求（如「视频转文案」「语音转写」）时，Agent 能按 Skill 指引走固定流程，而不是每次手写 ffmpeg 与 API 调用。
- 官方入口：SkillHub 技能页；API 元数据地址为
https://api.skillhub.cn/user_238e6fa6/aliyun-video2text。页面标注requires_api_key=true，需自行配置阿里云与 DashScope 凭证。
核心功能¶
以下能力均来自该 Skill 的 SKILL.md 与配套脚本说明，已核实：
- 本地视频抽音：依赖系统可用的
ffmpeg，将视频中的音频转为 mp3。 - OSS 中转：音频上传到配置的阿里云 OSS Bucket，生成临时 URL 供转写服务拉取。
- 百炼转写：调用 DashScope 侧转写能力（文档写明 Paraformer-v2），轮询任务直至完成。
- 输出文案：标准输出为 JSONL（每行一个 JSON），含单条
video_result与最终summary，便于流式读取与批量汇总。
触发关键词（Agent 匹配用户意图时使用）：视频转文案、提取视频文案、视频语音转文字、短视频文案提取、视频脚本提取、语音转写。
安装与启用¶
通过 SkillHub 安装¶
SkillHub 页面给出的安装提示为：参照 SkillHub 安装与优先源配置，安装坐标 @user_238e6fa6/aliyun-video2text。
若本机已有 skillhub CLI，安装时需用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 且可能不被识别。示例：
command -v skillhub && skillhub --version
未安装 CLI 时，可按官方文档执行（完整安装含 CLI 与默认 Skill）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安装本 Skill（将 <skills 目录> 换成你当前环境的路径）：
skillhub install user_238e6fa6/aliyun-video2text --dir <skills 目录>
常见 Agent 的 skills 目录（摘自 SkillHub 安装文档，以你本机为准）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
也可在对话中让 AI 按上述 install 文档完成安装；装好后需重启或刷新 Agent 对 skills 的加载策略（以你所用客户端文档为准）。
前置依赖与凭证¶
1. 安装 ffmpeg
Linux（Ubuntu/Debian）示例：
sudo apt install ffmpeg
macOS 使用 brew install ffmpeg；Windows 可用 winget install ffmpeg 等，详见 Skill 内 SKILL.md。
2. 配置环境变量或 Skill 目录下的 .env
# 阿里云 DashScope API Key（必填）
DASHSCOPE_API_KEY=your-dashscope-api-key
# 阿里云 OSS 配置（必填）
ALIYUN_ACCESS_KEY_ID=your-access-key-id
ALIYUN_ACCESS_KEY_SECRET=your-access-key-secret
ALIYUN_OSS_BUCKET=your-bucket-name
ALIYUN_OSS_ENDPOINT=oss-cn-beijing.aliyuncs.com
脚本默认从 Skill 根目录读取 .env（与 scripts/ 同级）。运行前请确认本机已安装 Python 3 及脚本依赖（如 requests），并在 Skill 根目录下执行下文命令。
典型用法¶
进入已安装的 @user_238e6fa6/aliyun-video2text 目录后，通过 scripts/video2text.py 传入 JSON 参数。
单个视频：
python3 scripts/video2text.py '{"video": "/path/to/video.mp4"}'
多个视频：
python3 scripts/video2text.py '{"videos": ["/path/video1.mp4", "/path/video2.mp4"]}'
指定输出目录：
python3 scripts/video2text.py '{"video": "/path/to/video.mp4", "output_dir": "/path/to/output"}'
输出示例（单行 JSONL）：
{"type": "video_result", "index": 0, "video_path": "/path/to/video.mp4", "status": "completed", "text": "视频文案内容...", "duration": 65000}
汇总行形态为 {"type": "summary", "status": "completed", "total": 3, "completed": 2, "failed": 1}。Agent 在对话中触发本 Skill 时，应引导用户补齐本地路径与凭证，再按上述入口执行或等价封装。
文档描述的处理顺序：校验 ffmpeg → 抽音为 mp3 → 上传 OSS → 创建转写任务 → 轮询状态 → 输出文本。
适用场景与注意¶
适合谁
- 需要在 Cursor、Claude Code、Codex 等支持 Skill 的环境里，用一句话完成「本地视频 → 中文文案」的创作者、运营或开发者。
- 已具备或可申请阿里云 OSS 与 DashScope（百炼）API 密钥的团队。
格式与规模限制（Skill 文档写明）
- 视频：mp4、avi、mov、mkv、flv、wmv；单文件最大 500MB。
- 也可直接处理音频：mp3、wav、m4a、pcm。
- 转写语言：中文普通话；时长说明为服务端处理、无硬性上限，实际以 API 与账单为准。
使用注意
- 音频经 OSS 临时存储，需保证 Bucket、Endpoint 与密钥权限正确；凭证勿提交到仓库。
- ffmpeg 不可用、凭证缺失、OSS 或转写失败时，脚本会给出错误信息；批量场景下单条失败可继续处理其余文件（见 Skill 错误处理说明）。
- SkillHub 统计（抓取资料）：评分 100000，下载 3867，安装 121；社区 Skill，行为以仓库内
SKILL.md与脚本为准，与阿里云官方产品文档若有出入请以控制台与 API 文档为准。
结尾¶
「阿里云百炼-视频转文字」把本地抽音、OSS 中转和 Paraformer-v2 转写串成一条可复现链路，并写成 Agent 可识别的 Skill，适合在对话里处理「视频转文案」类需求。安装与详情见 SkillHub 技能页。
