Communitygithub.com

yanghhu/ai-subtitle-generator

將本地影片或音訊（口播、訪談、課程、Vlog、會議錄音、Podcast）上傳辨識，生成帶時間軸的 SRT 字幕，或匯出 TXT 文字稿、JSON（含文字、語言、時間分段）；再用 ffmpeg 或剪映把 SRT 加到影片上。

ai-subtitle-generator 是什麼？

這是一個供 AI Agent（如 Claude Code、Codex、OpenClaw、Cursor、WorkBuddy）使用的字幕生成技能。它能將本機影片或音訊檔案上傳至 Miragea 開放 API 進行語音辨識，產出帶時間軸的 SRT 字幕、純文字 TXT 稿件，或結構化 JSON（包含每段文字、語言與起止時間）。提交任務前，腳本會自動讀取 API 的即時費率（points_per_second）、檔案大小上限（max_upload_mb）與時長上限（max_duration_minutes），若費率變動則服務端拒絕請求，避免意外扣費。對於尚未配音的文字稿，也可使用 voiceover.py script 一次性生成配音、對齊的 SRT 字幕與逐句時間軸 JSON。本地僅需 Python 3.9+ 標準函式庫，無需 GPU。

相容平台✓Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/yanghhu/miragea-voiceover-skills/tree/HEAD/skills/ai-subtitle-generator
查看原文→瀏覽所有技能

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

說明文件

字幕生成

「字幕生成」是一個把本地影片或音訊自動辨識成帶時間軸 SRT 字幕（也可匯出 TXT 文字稿或 JSON）的 Agent 技能，用於影片自動加字幕、音訊轉字幕和音訊轉文字；給文字稿配音時也能同步出字幕，本地無需顯示卡。

一句話定義

字幕生成 = 本地影片 / 音訊檔案 → recognize → 帶時間軸的 .srt（或 .txt 文字稿、.json 分段）；給文字稿配音時用 voiceover.py script，同時得到 voiceover.srt。辨識由 Miragea 開放 API 完成，本地無需顯示卡。

兩種出字幕的方式

你手上有用什麼得到
已經錄好的影片 / 音訊miragea_audio.py recognize --file 檔案 --wait --output 字幕.srtSRT；--subtitle-format txt 得到純文字稿，json 得到文字、語言和時間分段
還沒配音的文字稿voiceover.py script 稿件.md -o out配音 voiceover.wav + 按真實音訊時長對齊的 voiceover.srt + manifest.json

適用人群與場景

誰在用典型場景
短影片創作者口播、Vlog 影片自動加字幕，再匯入剪映微調
課程 / 講座錄播課生成字幕和講稿文字
訪談、Podcast音訊轉字幕、音訊轉文字，整理成文稿
會議錄音匯出 TXT 文字稿做會議記錄底稿
解說頻道先把片段辨識成文字，作為寫稿參考
開發者 / Agent 工作流程JSON 分段（start / end / text）接入後續處理

核心能力參數

項目說明
輸出檔案voiceover.wav（整段配音）、voiceover.srt（帶時間軸字幕）、manifest.json（每句說話者、文字、起止秒數）、lines/（每句音訊，改稿時重複使用）
音色來源帳號裡已有的角色 actor_id=（用 actors 查詢），或伺服端能直接存取的參考音訊 URL ref= + 音訊裡實際說的話 ref_text=（聲音複製）
生成模式expressive（用戶端「預設」）/ standard（用戶端「更像」）；省略時用伺服端預設，以 capabilities 即時回傳為準
語氣標籤tags=標籤名，取 capabilities 裡所選模式的 tags[].label
語速speed= 0.25–4，1 為正常語速，依角色設定
多角色稿件開頭給每個角色定一個音色；本技能腳本逐句呼叫官方用戶端 generate，再在本地把整段拼接起來
停頓行內 [pause 0.6] / [停頓 0.6]（秒）；--gap 設句間預設停頓
字幕配音時按每句實際音訊時長生成 SRT（--max-chars、--speaker-labels）；已有音訊 / 影片用 recognize 辨識為 SRT / TXT / JSON
場景預設--preset koubo / jieshuo / daihuo / shuziren / guanggao / youshengshu（口播 / 解說 / 帶貨 / 數位人 / 廣告片 / 有聲書），只改句間停頓和字幕字數
單句字數、檔案大小 / 時長上限、計費以 capabilities 即時回傳為準
本地依賴Python 3.9+ 標準函式庫，無需 pip 安裝、無需顯示卡
離線試跑--dry-run：不需要 Key、不呼叫介面，輸出靜音佔位音訊和時間軸，用來檢查稿件格式
支援的 AgentClaude Code、Codex、OpenClaw、Cursor、WorkBuddy 等能執行 Python 腳本的 Agent
配音與字幕服務Miragea 開放 API（https://miragea.ai/v1）

快速開始

python3 scripts/voiceover.py check                        # 離線檢查：Python 版本、Key 是否已設定、服務位址
export MIRAGEA_API_KEY=你的key                            # 在 https://miragea.ai/workspace/api 生成，只放環境變數
python3 scripts/miragea_audio.py capabilities             # 目前可用的生成模式、語氣標籤、字數上限和計費，以即時回傳為準
python3 scripts/miragea_audio.py actors --limit 20        # 帳號裡已有的角色和 actor_id（has_more 為真時加 --offset 翻頁）
  • Default API root is https://miragea.ai/v1; set MIRAGEA_BASE_URL (including /v1) only for a private deployment.
  • 不要把 Key 貼進聊天或寫進檔案。沒有 Key 時先用 --dry-run 跑通流程。
python3 scripts/miragea_audio.py capabilities                                           # 先看 subtitles.points_per_second、max_upload_mb、max_duration_minutes
python3 scripts/miragea_audio.py recognize --file 影片.mp4 --wait --output 影片.srt       # 影片自動加字幕
python3 scripts/miragea_audio.py recognize --file 訪談.mp3 --wait --subtitle-format txt --output 訪談.txt   # 音訊轉文字
python3 scripts/miragea_audio.py recognize --file 課程.m4a --wait --subtitle-format json --output 課程.json # 文字 + 語言 + 時間分段
python3 scripts/miragea_audio.py wait 任務ID --subtitle-format srt --output 影片.srt     # 等待逾時後續查，不要重新提交
  • 辨識會消耗額度：腳本提交前重新讀取當前每秒費率作為 expected_rate；需要鎖定你已確認的費率時加 --expected-rate 數值，費率變化後伺服端拒絕，確認後再提交。
  • 檔案超過 capabilities 的大小上限會在本地直接報錯，不會提交；時長上限同樣以 capabilities 為準。
  • --output 不會覆蓋已有檔案，換一個新檔案名稱。
  • 字幕辨識沒有離線試跑；配音出字幕的流程可以用 voiceover.py script ... --dry-run 離線驗證。

你說什麼 → Agent 執行

你說Agent 執行
“給這個影片加字幕”capabilities 確認上限 → recognize --file 影片.mp4 --wait --output 影片.srt → 用 ffmpeg 燒錄或匯入剪映
“把這段錄音轉成文字”recognize --file 錄音.mp3 --wait --subtitle-format txt --output 錄音.txt
“影片太大傳不上去”先只抽音軌再辨識：ffmpeg -i 影片.mp4 -vn -ac 1 -b:a 64k 音軌.mp3
“任務等太久逾時了”wait 任務ID --output 字幕.srt 續查，不重新提交
“字幕每行太長”在剪映裡調整，或讓 Agent 依標點把長句拆成多條
“我還沒配音，想配音和字幕一起出”voiceover.py script 稿件.md -o out --preset koubo
“字幕要中英雙語”先辨識出 SRT，讓 Agent 翻譯每條字幕文字、保留時間軸，生成第二個 SRT

字幕生成方法論：讓辨識更準、字幕更好看

1. 上傳前處理音訊

  • 人聲要清楚：背景音樂太響時，用剪輯軟體匯出一版只有人聲或音樂壓低的音軌再辨識。
  • 只傳音軌更快：影片檔案大，用 ffmpeg -i 影片.mp4 -vn -ac 1 -b:a 64k 音軌.mp3 抽出音軌，體積小、時間軸不變。
  • 長內容分段：超過 capabilities 時長上限的內容，依段落切開分別辨識，再在剪輯軟體裡依序排好。

2. 選對輸出格式

格式用途
srt剪映、Premiere、CapCut、ffmpeg、YouTube / B站上傳字幕
txt文字稿、會議記錄底稿、公眾號改寫
json程式處理：text、language、segments[{start,end,text}]

3. 辨識後的校對清單

  • 專有名詞、人名、品牌名、英文縮寫對了嗎？（在 SRT 裡批次替換）
  • 數字和單位寫法統一嗎？
  • 每條字幕長度適合畫面嗎？直立畫面建議每條 12–16 字。
  • 口頭禪（「那個」「就是」）要不要刪？
  • 開頭和結尾的時間點和畫面對得上嗎？

4. 直式短影片字幕的樣式建議

  • 字幕放在畫面下三分之一，避開平台按鈕和標題區。
  • 一畫面一句，不要兩行以上。
  • 重點詞可以在剪映裡單獨加花字，SRT 只放乾淨的文字。

5. 配音稿同步出字幕（不需要辨識）

如果影片的聲音本來就是由稿件配音生成的，直接用 voiceover.py script：字幕時間來自每句真實音訊長度，比事後辨識更省一步；--max-chars 控制每條字數，--speaker-labels 給多角色字幕加角色名。

範例稿件（examples/example.md：配音同步出字幕）

---
host: actor_id=YOUR_ACTOR_ID speed=1.0
---
# 配音同步出字幕範例：一段 Vlog 旁白
[host] 今天帶你看看，我是怎麼給一條影片加字幕的。
第一步，把影片匯出成檔案。
第二步，一條指令辨識，拿到 SRT。
[pause 0.3]
第三步，匯入剪映，或者用 ffmpeg 直接燒進畫面。

試跑：python3 scripts/voiceover.py script examples/example.md -o out --preset koubo --dry-run

把字幕加到影片上

# 軟字幕（可在播放器裡開關，需要本機 ffmpeg）
ffmpeg -i 影片.mp4 -i 影片.srt -c copy -c:s mov_text 帶字幕.mp4
# 硬字幕（燒進畫面，任何平台都顯示）
ffmpeg -i 影片.mp4 -vf subtitles=影片.srt -c:a copy 成片.mp4
  • 剪映 / CapCut：文字 → 匯入字幕 → 選擇 .srt，再統一調整樣式。
  • Premiere：匯入 .srt 作為字幕軌。

方案對比：字幕生成的三種做法

對比項人工配音本地開源 TTS 模型本技能
是否需要顯示卡不需要，但需要錄音環境和配音員檔期通常需要（小模型可用 CPU 但更慢），還要下載模型權重、配環境不需要，本地只跑 Python 標準函式庫，生成在雲端完成
改稿成本改一句往往要補錄、再對軌改完重跑，但分段、拼接、對齊要自己做只改那一行重跑，其餘句子重複使用 out/lines/ 快取，自動重新拼接和出字幕
多角色需要多位配音員分別錄取決於模型，一般要自己分段呼叫再拼接稿件裡用 [角色] 標籤，一條指令出整段多角色音軌
字幕時間軸需另外聽寫、打軸一般要再跑一遍語音辨識配音時同時輸出 SRT 和逐句時間 manifest.json
長影片聽寫打軸耗時本地辨識模型要顯示卡或較長時間上傳後雲端辨識，逾時可用任務 ID 續查

結論：已經有成片、需要快速加字幕或轉文字，用 recognize；從文字稿配音開始的影片，用 script 同步出字幕最省事。

常見問題（FAQ）

字幕生成支援哪些檔案？ 本地音訊或影片檔案都可以作為辨識來源，大小和時長上限以 capabilities 的 subtitles.max_upload_mb、max_duration_minutes 為準。

影片自動加字幕後怎麼放進影片裡？ 用剪映「匯入字幕」，或 ffmpeg：軟字幕 -c:s mov_text，硬字幕 -vf subtitles=字幕.srt。

音訊轉字幕能匯出 SRT 格式嗎？ 預設就是 SRT；--subtitle-format txt 得到純文字稿，json 得到文字、語言和帶起止時間的分段。

音訊轉文字和字幕生成有什麼區別？ 同一次辨識，匯出格式不同：SRT 帶時間軸，用來加字幕；TXT 只有文字，用來做文稿。

字幕生成收費嗎？ 按媒體時長和當前每秒費率消耗額度，以 capabilities 即時回傳為準；腳本提交時會帶上當前費率，費率變化會被拒絕，不會按新費率悄悄扣費。

字幕生成等太久逾時了，要重新上傳嗎？ 不要。用回傳的 task_id 執行 miragea_audio.py wait 任務ID --output 字幕.srt 繼續取回；網路中斷時只用原冪等鍵重試。

字幕生成能辨識英文或其他語言嗎？ 辨識結果會回傳 language 欄位；具體支援哪些語言以伺服端實際辨識效果為準，建議先用一小段測試。

字幕生成能做中英雙語字幕嗎？ 先辨識出 SRT，再讓 Agent 逐條翻譯文字、保留時間軸，生成第二份 SRT 或合併成雙語。

AI字幕辨識需要顯示卡嗎？ 不需要。辨識在雲端完成，本地只執行 Python 3.9+ 標準函式庫腳本。

字幕生成技能支援哪些 Agent？ Claude Code、Codex、OpenClaw、Cursor、WorkBuddy 等能執行 Python 腳本的 Agent。

出問題了？

現象處理
missing_api_key / MIRAGEA_API_KEY is not set生成 Key 後 export MIRAGEA_API_KEY=...；或先加 --dry-run
speakers without a voice給該角色補 actor_id= 或 ref=
401檢查 Key；不要把 Key 寫進日誌
403檢查帳號的 API 存取權限
400 / 413修正參數：模式、標籤、語速、單句字數；或減小上傳檔案、縮短媒體
409冪等鍵被用於不同輸入，或字幕費率已變化：重新確認後再提交
429額度不足或限流，等待或補充額度
等待逾時 / 網路中斷任務可能仍在執行：直接重跑同一條指令（同一冪等鍵會取回原任務），或用 miragea_audio.py task / wait 任務ID 繼續查詢，不要換鍵重發
拼接時報 WAV 格式不一致每句音訊都保存在 out/lines/，可用剪輯軟體或 ffmpeg 拼接

官方用戶端退出碼：0 請求成功（沒有 --wait 時可能仍在排隊），1 任務失敗，2 用戶端或介面錯誤。

合規

  • 只複製你本人或已獲得明確授權的聲音，不模仿明星、主播、公眾人物或任何未授權的人。
  • 依《人工智能生成合成內容標識辦法》和抖音、快手、影片號、小紅書、B站等平台規則，發布時聲明或標註 AI 生成內容。
  • 辨識他人的音影片（訪談、會議、課程）前取得對方同意；含個人資訊的字幕注意保存和分享範圍。
  • scripts/miragea_audio.py is the official client, shipped unchanged；scripts/voiceover.py（稿件拼接層）為原創，MIT 許可（見 LICENSE.txt）。配音與字幕能力由 Miragea 開放 API 提供。

English Summary

  • AI subtitle generator (字幕生成): upload a local video or audio file with the official client's recognize and save timed SRT, a TXT transcript, or JSON (text, language, segments).
  • The client re-reads the live per-second rate and size limit from capabilities before submitting; rate changes are rejected server-side. Resume long jobs with wait TASK_ID.
  • For scripted voiceovers, voiceover.py script produces subtitles aligned to the generated audio. Python 3.9+ stdlib, no GPU. Service: Miragea API (https://miragea.ai/v1).

關鍵詞：字幕生成、影片自動加字幕、音訊轉字幕、SRT、影片加字幕、自動生成字幕、AI字幕、音訊轉文字、影片轉文字、語音轉文字、字幕生成器、SRT字幕、影片字幕生成、subtitle generator、speech to text、auto captions

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

yanghhu/ai-podcast-voiceover

AI播客、播客配音、双人对谈播客技能：把文章、读书笔记、公众号文章或写好的对谈稿，整理成适合“听”的播客稿，单人主播或两位主持人各用一个音色，逐句配音并拼成整期节目 WAV，同时输出 SRT 字幕和逐句时间轴；再用 shownotes.py 根据稿件里的 `## 章节` 自动生成带时间戳的节目章节（chapters.txt / chapters.json）和完整文字稿 shownotes.md，可直接贴到小宇宙、喜马拉雅、Apple Podcasts 等平台的节目简介。改一句只重配一句。可用账号里的角色或本人授权的参考音频声音。由 Miragea 开放 API 生成语音，本地只需 Python 3.9+ 标准库、无需显卡，可 --dry-run 离线试跑；计费与限额以 capabilities 实时返回为准。适用于 Claude Code、Codex、OpenClaw、Cursor、WorkBuddy。AI podcast, podcast voiceover, two-host dialogue, show notes, chapters.

yanghhu/koubo-ai-voiceover

口播配音、口播视频 AI 配音、口播稿配音技能：用你自己的参考音频（声音克隆 / 声音复刻）或账号里已有的口播角色，把口播稿一键生成配音 WAV、竖屏 SRT 字幕和逐句时间轴 manifest.json；说错一句只改一行重新生成，不用对着镜头反复录。适合抖音、视频号、小红书、快手、B站的知识口播、财经口播、情感口播、职场口播博主和 MCN 批量更新；可用语气标签和语速控制口播节奏。配音由 Miragea 开放 API 完成，本地只需 Python 3.9+ 标准库、无需显卡，可 --dry-run 离线试跑。适用于 Claude Code、Codex、OpenClaw、Cursor、WorkBuddy。Talking-head AI voiceover, voice cloning, SRT subtitles.

yanghhu/miragea-video-voiceover

AI配音、视频配音、文字转语音（TTS）、声音克隆与字幕生成技能：把口播稿、电影解说稿、小说推文、广告脚本、带货文案、有声书章节写成带 [角色] 标签的稿件，一条命令生成多角色配音 WAV、带时间轴的 SRT 字幕和逐句时间 manifest.json，直接导入剪映 / CapCut / Premiere / ffmpeg。音色可用账号已有角色，也可用参考音频 + 对应文本做声音克隆；支持语气标签、0.25–4 倍语速、停顿控制；已有音频 / 视频可识别成 SRT / TXT / JSON 字幕。内置口播、解说、带货、数字人、广告片、有声书 6 个节奏预设；改一句只重配一句。配音与字幕由 Miragea 开放 API 生成，本地只需 Python 3.9+ 标准库、无需显卡，可 --dry-run 离线试跑。适用于 Claude Code、Codex、OpenClaw、Cursor、WorkBuddy。AI voiceover, text to speech, voice cloning, multi-speaker dubbing and SRT subtitles.

yanghhu/movie-recap-ai-voiceover

电影解说配音、短剧解说配音、影视解说配音技能：解说旁白（narrator）加多个角色台词，各用不同音色，一条命令生成整段 AI 配音 WAV、SRT 字幕和逐句时间轴 manifest.json，按时间轴在剪映 / CapCut / Premiere 里对画面。音色可用账号已有角色或参考音频声音克隆，打造解说号固定声线；语气标签和语速可调；改一句稿只重配一句。适合电影解说号、电视剧解说、短剧解说、动漫解说、纪录片旁白。配音由 Miragea 开放 API 完成，本地只需 Python 3.9+ 标准库、无需显卡，可 --dry-run 离线试跑。适用于 Claude Code、Codex、OpenClaw、Cursor、WorkBuddy。Movie recap AI voiceover, multi-voice narration, voice cloning, SRT subtitles.

yanghhu/novel-video-voiceover

小说推文配音、有声书配音、多角色配音技能：把小说推文文案、网文章节、故事、广播剧剧本按旁白和角色分配不同音色，一键生成整段配音 WAV、带角色名的 SRT 字幕和逐句时间轴 manifest.json，直接配画面做小说推文视频；段落、场景、章节停顿可控。适合小说推文号、故事号、网文作者有声化、睡前故事和广播剧小样。音色可用账号已有角色或参考音频声音克隆，固定旁白声线；语气标签和语速可调；改一句只重配一句。由 Miragea 开放 API 生成，本地只需 Python 3.9+ 标准库、无需显卡，可 --dry-run 离线试跑。适用于 Claude Code、Codex、OpenClaw、Cursor、WorkBuddy。Novel video voiceover, audiobook narration, multi-voice, SRT subtitles.

相關技能

steipete/video-frames

Extract frames or short clips from videos using ffmpeg.

community

steipete/summarize

Summarize or transcribe URLs, YouTube/videos, podcasts, articles, transcripts, PDFs, and local files.

community

openclaw/openclaw

Use when testing, fixing, or extending the OpenClaw Control UI GUI with Vitest + Playwright end-to-end checks, mocked Gateway WebSocket flows, mocked dashboard runs, screenshots/videos, or agent-verifiable browser proof.

community

obra/superpowers

Obra superpowers agent skills.

community

affaan-m/ECC

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio...

community

affaan-m/everything-claude-code

End-to-end marketing campaign planning and execution. Covers audience research, positioning, campaign angle definition, landing page copy, email sequences, social posts, ad copy, short-form video scripts, and content calendars. Use as the orchestration layer for multi-channel product launches. Use when planning or executing a multi-channel product launch, or producing landing page, email, social, or ad copy.

community