前言¶
做短視頻復盤、口播稿整理或會議錄像歸檔時，常見做法是自己聽寫，或把文件丟進第三方網頁再導出字幕。前者費時，後者對本地路徑、批量處理和 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 技能頁。
