| name | opencode-groq-api |
| description | 用 Groq 的免費 API 做「語音轉字幕」與「逐字稿清洗」，並把整條流程包成可重複使用的技能。說「語音轉字幕」「影片上字幕」「做逐字稿」「Whisper」「Groq」「把錄音整理成講義」「把 API 變成工具」時載入。 |
把 API 變成自己的工具（Groq）
官方文件查證日期：2026-07-27
依據：https://console.groq.com/docs/speech-to-text、https://console.groq.com/docs/api-reference、https://console.groq.com/docs/rate-limits、https://console.groq.com/docs/models、https://console.groq.com/docs/your-data、https://console.groq.com/docs/billing-faqs、https://console.groq.com/docs/quickstart
🔴 先看這裡：隱私紅線（這一段是本包最重要的內容）
這一包做的每一件事，都會把你的聲音檔送到別人的伺服器上。
不是「處理完就消失」那種送，是整個音檔上傳、在美國的機器上跑完、再把文字傳回來。你電腦上的麥克風錄到什麼，就送出去什麼。
這三類錄音，一律不要上傳
| ❌ 不要上傳 | 為什麼 |
|---|
| 含學生聲音的課堂錄音 | 學生是未成年人。要不要讓孩子的聲音上傳到境外雲端，這件事你不能代替家長同意。 |
| 家長會談、親師溝通、電話錄音 | 對方通常不知道有錄音，更不知道會被上傳 |
| 輔導紀錄、個案會議、學生私下談話 | 這類內容一旦外流，受傷的是孩子，而且你會有法律責任 |
順便三條也不要：唸到學生姓名的點名錄音、學生口說測驗的作答錄音、任何你不確定裡面有誰在講話的檔案。
這些可以上傳
- 你自己一個人講課、備課、口述的錄音（只有你的聲音）
- 你自己的公開演講、研習分享
- 你自己錄的旁白、口播稿
- 公開影片（新聞、公播教材、你自己頻道的影片）
一句話的判斷標準
🔴 「這個音檔如果明天出現在網路上，會不會有人受傷？會不會需要通報？」
只要答案是「會」或「不確定」——不上傳。沒有例外，不看時間趕不趕。
⚠️ 最容易出事的地方：檔案結尾
課堂錄音最常見的意外不是內容，是「忘記按停止」。
你以為錄的是自己講課的 40 分鐘，實際上錄音一直開到下課、開到學生跑上來問問題、開到你跟隔壁老師聊完。
🔴 規矩：上傳前先跳到檔案的最後 30 秒聽一遍。
這一步花 30 秒，可以擋掉這一包 90% 的真實風險。
Groq 官方的資料政策（查證 2026-07-27）
講完紅線再講政策，順序不能反——政策再好，也不會讓紅線消失。
| 項目 | 官方說法 | 出處 |
|---|
| 推論請求的資料會保留嗎 | 預設不保留（"By default, Groq does not retain customer data for inference requests."） | Your Data in GroqCloud |
| 會拿去訓練模型嗎 | 不會。服務協議明訂：未經客戶明示同意，不得將輸入／輸出用於訓練或微調模型 | Groq Services Agreement |
| 有例外嗎 | 有。為了排除故障、調查濫用，可能暫時記錄輸入與輸出，最長保留 30 天（法律要求時可能更久） | Your Data in GroqCloud |
| 可以完全關掉嗎 | 可以。所有客戶都能在 Console 的 Data Controls 開啟 Zero Data Retention（ZDR） | Your Data in GroqCloud |
| 免費方案有比較差嗎 | 官方文件沒有為免費方案另訂較寬鬆的規定，寫的是同一套 | 同上 |
建議研習前先做一件事：登入 Console → Settings → Data Controls → 開啟 Zero Data Retention。花 10 秒，之後所有請求都適用。
🔴 但是——開了 ZDR，紅線一條都不會消失。
政策是廠商的承諾，不是「你的檔案沒有離開過你的電腦」的技術保證。
中間還有網路、還有你的電腦、還有你等一下會不會把 srt 檔傳到 LINE 群組。
真正安全的做法只有一個：那個檔案根本不要上傳。
真的非處理不可怎麼辦
有些內容就是不能上雲端，但你又真的需要逐字稿。三條路：
- 請當事人自己來：讓學生／家長自己用手機的語音輸入打字，你只收文字
- 本機跑：在自己電腦上跑離線的語音辨識模型（不連網、不上傳）。這條不在本研習範圍，也不在本包
- 不做：這是完全合理的選項。省下的 20 分鐘，遠遠比不上一次個資事件
這一包在研習裡的位置：作品⑤「把 API 變成自己的工具」
第三天上午。這一包做的是「內部工具」——只有你自己在電腦上用，還不碰網頁。
前面幾包是「把別人做好的東西接進來」（NotebookLM、Obsidian、Supabase）。這一包不一樣：
你會拿一個原始的 API，做出一個以後可以一直用的東西。
這是整套研習裡第一次「呼叫外部服務、拿回結果、包成工具」。學會這個模式，之後接任何服務都是同一套邏輯。
🔑 這一包成不成功，判斷標準只有一個
| 跑一次 | 變成工具 |
|---|
| 你做的事 | 貼一串指令，看到 srt 跑出來 | 對 OpenCode 說一句人話，它自己做完 |
| 換一份新素材 | 要回來翻講義、重貼指令 | 同一句話再說一次就好 |
| 下個月還會用嗎 | 不會，因為忘了怎麼跑 | 會，因為只要記得那句話 |
| 這一包的驗收 | ❌ 不算完成 | ✅ 這才算完成 |
所以步驟六（包成 Skill）不是加分題，是這一包的正題。
前面五個步驟都只是為了搞清楚「那句人話背後要做什麼」。
📌 下午的 10-netlify 會把這個工具再往外推一層：變成一個網頁，讓別人也能用。
今天上午先把「自己能用」做穩，下午才有東西可以搬上網。
這一包會幫你做什麼
兩條主線，都用同一把金鑰：
| 線 | 做什麼 | 輸入 → 輸出 | 用到的服務 |
|---|
| A 轉字幕 | 把聲音變成有時間碼的字幕檔 | .mp4 / .mp3 / .m4a → .srt | Groq 的 Whisper |
| B 文字清洗 | 把逐字稿整理成能發給學生看的講義 | .srt / .txt → .md | Groq 的文字模型 |
A 線的產物剛好是 B 線的原料。合起來就是：一段錄音 → 一份講義。
🚨 這一包的四個陷阱（先看完再動手）
| # | 陷阱 | 症狀 | 一句話解法 |
|---|
| ① | Groq 沒有 response_format=srt | 照 OpenAI 的教學打，回 400 | 拿 verbose_json，自己組 srt（步驟三附小程式） |
| ② | 免費方案單檔上限 25 MB | 一支 40 分鐘影片直接被打回 | 先用 ffmpeg 壓成 16k 單聲道，超過 25 MB 就切段 |
| ③ | Whisper 的中文不分繁簡 | 辛苦轉完，字幕是簡體 | language=zh 只能到「中文」；繁體要另外處理（步驟三 A5） |
| ④ | 切段後時間碼要自己加偏移 | 第二段字幕全部從 00:00 開始，整份對不上畫面 | 用每一段的實際長度累加，不要用名目的「10 分鐘」 |
陷阱 ① 是最花時間的一個——網路上 95% 的 Whisper 教學都是寫給 OpenAI 的，那邊有 srt，Groq 沒有。 你會以為自己打錯字。
免費方案（不用綁信用卡）
⚠️ 以下為 2026-07-27 查到的數字。服務商隨時會調整，以官方頁面為準（本節最後教你怎麼自己查）。
要不要綁卡
| 問題 | 答案（查證 2026-07-27） |
|---|
| 註冊要不要信用卡 | 不用。 用 Google／GitHub／Email 註冊，直接就能產金鑰 |
| 免費用量要不要信用卡 | 不用。 免費方案是「限速」不是「限時」，沒有試用到期這回事 |
| 什麼時候才需要卡 | 只有升級 Developer 方案時。官方文件寫得很清楚：升級需要「a valid payment method（credit card, US bank account, or SEPA debit account）」 |
🔴 研習現場的規矩：整個過程不會有任何畫面要你輸入卡號。
只要看到要求付款方式的畫面，代表你走進了升級流程——按上一頁退出來，不要輸入。
這一包主線完全不需要 Developer 方案。
免費額度（Whisper 語音）
| 項目 | 免費方案 | 換算成老師聽得懂的話 |
|---|
| 單檔大小上限 | 25 MB | 壓成 16k 單聲道 FLAC 後，約 25～30 分鐘的音訊 |
| 每分鐘請求數 | 20 次 | 一次跑 20 個檔沒問題 |
| 每日請求數 | 2,000 次 | 用不完 |
| 每小時音訊秒數 | 7,200 秒 | 每小時可以轉 2 小時的音訊 |
| 每日音訊秒數 | 28,800 秒 | 每天可以轉 8 小時的音訊 |
| 最短音訊 | 0.01 秒 | — |
| 最低計費長度 | 10 秒 | ⚠️ 見下方 |
⚠️ 「最低計費 10 秒」這條會咬人。
意思是：再短的檔，也至少吃掉 10 秒額度。
所以「把一堂課切成 200 個小片段各自送一次」是最浪費的做法——200 個 3 秒的檔會被算成 2,000 秒。
正確做法：切大段（10 分鐘一段），不要切小段。
（付費的 Developer 方案單檔上限是 100 MB。本包不走那條，寫在這裡只是讓你看到別人的教學寫 100 MB 時不會困惑。）
免費額度（文字模型，B 線用）
| 模型 | 每分鐘請求 | 每日請求 | 每分鐘 token | 每日 token |
|---|
llama-3.3-70b-versatile | 30 | 1,000 | 12,000 | 100,000 |
openai/gpt-oss-120b | 30 | 1,000 | 8,000 | 200,000 |
llama-3.1-8b-instant | 30 | 14,400 | 6,000 | 500,000 |
🚨 這裡有一個沒人講、但一定會撞到的坑：
「每分鐘 token」小得驚人。 一小時的中文演講逐字稿大約 9,000～12,000 字，換算下來遠遠超過 12,000 token 的每分鐘上限。
也就是說：你不可能把一整份逐字稿一次丟給它清洗。 一定會拿到 429。
解法：分段送。 步驟五的小程式已經內建分段（預設一段 1,200 字）和自動重試，照著跑就好。
怎麼自己查最新的（模型會改名、額度會變）
📌 本包刻意不寫任何價格。 免費方案用不到，而寫死的價格只會在半年後變成錯誤資訊。
模型名稱也一樣：如果下面哪個模型名在你跑的時候不存在了，先跑上面那行 /v1/models 看它改叫什麼，不要硬套本文件。
選哪個 Whisper 模型：研習主線用 whisper-large-v3
Groq 上目前有兩個（查證 2026-07-27）：
| 模型 | 官方標示的準確度 | 速度 | 語言 |
|---|
whisper-large-v3 | 錯字率 10.3% | 189 倍即時 | 多語（含中文） |
whisper-large-v3-turbo | 錯字率 12% | 216 倍即時 | 多語（含中文） |
🔴 推薦：whisper-large-v3。理由是一個很多人沒注意到的事實——
在免費方案下，這兩個模型的額度完全一樣（都是 20 次/分、7,200 音訊秒/小時、28,800 音訊秒/日）。
turbo 的賣點是「比較便宜」。但免費方案本來就不用錢，所以那個賣點在這裡等於零。
而速度差多少？189 倍 vs 216 倍。一支 30 分鐘的錄音，一個要 9.5 秒、一個要 8.3 秒。你根本感覺不到。
結論：免費用戶沒有任何理由選 turbo。用準的那個。
什麼時候才換 turbo：你要一次跑幾十個檔、而且真的坐在旁邊等；或者以後升級成付費、開始在意費用。
📌 關於繁體中文的表現：Groq 官方沒有公布任何中文專屬的準確度數字，Whisper 官方也只有整體多語數字。
本包推薦 whisper-large-v3 的依據是「整體錯字率較低」＋「免費方案額度相同」，不是任何中文的實測比較。
實際上兩個模型對台灣國語的表現都算堪用，主要問題不是聽錯字，是專有名詞（人名、地名、課本術語）和繁簡——這兩件事都靠步驟五的清洗解決，換模型幫助不大。
選哪個文字模型：主線用 llama-3.3-70b-versatile
| 模型 | 為什麼選／不選 |
|---|
llama-3.3-70b-versatile | ✅ 主線。中文品質在免費模型裡較穩，而且每分鐘 token 上限 12,000 是免費方案裡最大的——清洗逐字稿吃的就是這個 |
openai/gpt-oss-120b | 🟡 備援。主線那個掛掉或改名時用這個 |
llama-3.1-8b-instant | 🟡 量大時用。每日 500,000 token 最寬鬆，但中文品質明顯較弱，適合「整批粗清、之後自己再看過」 |
⚠️ 模型名稱會改。跑之前先用 /v1/models 確認一次（見上方「怎麼自己查最新的」）。
🤔 等一下——文字清洗為什麼不直接叫 OpenCode 做就好？
這是研習現場一定會有人問的問題，而且問得很對。
你已經在 01-connect-model 幫 OpenCode 接了模型。要清洗逐字稿，把檔案丟給它說「幫我整理成講義」，它就做完了。幹嘛還要多申請一把 Groq 金鑰、多寫一支程式？
答案是三件事：
| 理由 | 說明 |
|---|
| ① 這一包在教「模式」，不是在教「清洗」 | 呼叫 API 拿結果，這個模式之後接任何服務都通用。清洗只是拿來練手的題目 |
| ② 語音那條沒有替代方案 | OpenCode 的模型聽不懂聲音檔。A 線非走 API 不可，而 B 線用同一把金鑰、同一套寫法，順著學最省力 |
| ③ 下午要變成網頁 | 10-netlify 會把這個工具放到網路上給別人用。網頁不能呼叫你電腦裡的 OpenCode，只能呼叫 API。今天寫的這支程式，下午直接搬上去 |
💡 所以：日常自己用，直接叫 OpenCode 清洗完全 OK，不必每次都走 API。
但這一包要你走一次 API，是為了讓你手上有一個「離開 OpenCode 也能跑」的東西。
先備條件
驗證：
ffmpeg -version; ffprobe -version
兩個都印出版本 = 過。
⚠️ ffprobe 常常缺席。 如果只裝了 yt-dlp 自帶的那套 FFmpeg，ffprobe 可能不在 PATH 上。
補裝系統版：winget install --id Gyan.FFmpeg -e（沒有管理員權限就加 --scope user）。
mac：brew install ffmpeg／Linux：sudo apt install -y ffmpeg。
真的裝不起來也還有救——步驟四的小程式有備援做法，看那一節。
📁 先建一個工作資料夾，名字用英數字
New-Item -ItemType Directory -Force "$HOME\Documents\groq-subtitle"
🚨 資料夾和檔名先不要用中文。
Windows 的命令列（PowerShell 5.1）傳中文檔名給 ffmpeg、curl 時偶爾會變亂碼，你會看到「找不到檔案」但檔案明明就在。
做法：轉檔前先把來源改成 lesson01.mp4 這種名字，全部跑完再改回中文。
這一條看起來很瑣碎，但研習現場每一梯都有人卡在這裡半小時。
步驟一：申請 Groq 金鑰
🖐️ 全程在瀏覽器手動做。AI agent 不要代為註冊、不要代填任何欄位。
1-1 註冊
- 開 https://console.groq.com
- 選 Continue with Google 或 Continue with GitHub（建議用
07-github 那個 GitHub 帳號，之後好管理），也可以用 Email
- 沒有等待清單、不用審核、不會問你要信用卡
1-2 建立金鑰
左側選單 API Keys → Create API Key → 取一個看得懂的名字（例如 研習-字幕工具）→ 建立。
🔴 金鑰只會完整顯示這一次。
關掉視窗之後看不到第二次，只能刪掉重產一把。
現在就複製起來，貼到你的密碼管理器（不是貼到記事本、不是貼到 LINE 給自己）。
金鑰長得像 gsk_ 開頭的一長串。
1-3 順手開啟 Zero Data Retention
Settings → Data Controls → 開啟 Zero Data Retention。
10 秒的事，之後所有請求都適用。（再說一次：開了它，前面那些紅線一條都不會消失。）
1-4 驗證：金鑰是活的嗎
先做完步驟二設定好環境變數，再回來跑這一行（步驟二的驗證裡有）。
步驟二：金鑰要放哪裡（🚨 這一步做錯，金鑰會上 GitHub）
🔴 三條絕對規則
① 金鑰不寫進任何 .md 檔案裡 —— 包含你等一下要做的那個 Skill 檔。
② 金鑰不寫進任何會被 git add 的檔案裡。
③ 金鑰不貼進聊天視窗（包含貼給 AI agent 看）。
理由：研習的設定檔會投影在大螢幕上、會被拍照；而 GitHub 上有機器人專門在掃新推上去的金鑰，掃到的速度比你發現的速度快。
主線做法：設成環境變數（推薦，整台電腦設一次）
環境變數的好處是：金鑰不存在於任何一個檔案裡，所以永遠不可能被 commit。
Windows（PowerShell）
[System.Environment]::SetEnvironmentVariable("GROQ_API_KEY", "貼上你的金鑰", "User")
設完一定要重開終端機（連 OpenCode 也要完全關掉重開），新的環境變數才會生效。
macOS / Linux（寫進 ~/.zshrc 或 ~/.bashrc，然後 source 一次）
echo 'export GROQ_API_KEY="貼上你的金鑰"' >> ~/.zshrc
source ~/.zshrc
驗證（🔴 這行刻意不印出金鑰本身，可以安心投影）
Windows
if ($env:GROQ_API_KEY) { "KEY_SET len=" + $env:GROQ_API_KEY.Length } else { "KEY_MISSING" }
macOS / Linux
if [ -n "$GROQ_API_KEY" ]; then echo "KEY_SET len=${#GROQ_API_KEY}"; else echo "KEY_MISSING"; fi
看到 KEY_SET len=<某個數字> = 過。看到 KEY_MISSING → 沒重開終端機，或變數名打錯。
驗證金鑰是活的
curl.exe https://api.groq.com/openai/v1/models -H "Authorization: Bearer $env:GROQ_API_KEY"
- 回傳一大段 JSON（裡面看得到
whisper-large-v3）→ ✅ 金鑰可用，順便看到現在有哪些模型
- 回
invalid_api_key → 金鑰複製時少了一截，或前後有多餘的空白，重複製一次
Windows 一定要打 curl.exe（有 .exe），否則會叫到 PowerShell 內建的別名，行為完全不同。
專案做法：.env ＋ .gitignore（下午的 10-netlify 會用到）
如果你的工具要放進一個「會推上 GitHub 的專案資料夾」，用 .env：
先建 .gitignore（🔴 先建這個，再建 .env，順序不能反）
.env
*.key
credentials.*
desktop.ini
*.tmp
再建 .env
GROQ_API_KEY=貼上你的金鑰
驗證 .env 真的被擋掉了：
git status --short
🔴 輸出裡出現 .env 就是失敗——代表 git 還看得到它，下一次 git add . 就會把金鑰送上 GitHub。
回頭檢查 .gitignore 是不是拼錯、是不是放在 repo 根目錄。
更嚴格的檢查（agent 請跑這一行）：
git check-ignore -v .env
有輸出（會告訴你被 .gitignore 第幾行擋掉）= ✅ 過。沒有輸出 = ❌ 沒擋到。
📌 關於 Google 雲端硬碟：.env 放在雲端硬碟資料夾裡會被同步到你的雲端帳號——這通常可以接受（那是你自己的帳號）。
但它跟 .gitignore 是兩回事，雲端同步不會擋 git。兩件事都要做。
如果你要在 opencode.json 裡引用金鑰
本包用不到這件事（我們是自己呼叫 API，不是把 Groq 接成 OpenCode 的模型供應商）。但萬一你之後要：
"environment": { "GROQ_API_KEY": "{env:GROQ_API_KEY}" }
🔴 寫 {env:GROQ_API_KEY}，不要寫實際那串字。
這是 00-env-setup 附錄「MCP 通用守則」第 5 條的規矩，本包完全沿用。
🚨 萬一金鑰不小心外流了
刪掉檔案、刪掉訊息、清掉 git 歷史——全部沒有用。 金鑰已經在別人手上了。
唯一有效的處置：回 Console → API Keys → 把那把金鑰刪掉，重新產一把。
這件事做完之前，其他都不用做。做完之後，記得把環境變數也換成新的。
步驟三：A 線 — 把聲音變成字幕（.srt）
A1. 先把檔案壓小（🚨 這裡處理陷阱 ②）
免費方案單檔上限 25 MB。一支手機錄的 30 分鐘影片動輒好幾百 MB，直接送一定被打回。
官方建議的做法：降到 16kHz 單聲道、轉成 FLAC。 這樣做不會影響辨識準確度——Whisper 本來就只吃 16kHz，多出來的取樣率和第二個聲道，送上去也是被丟掉。
Groq 官方文件給的指令（原封不動）：
ffmpeg -i "lesson01.mp4" -ar 16000 -ac 1 -map 0:a -c:a flac "clean.flac"
| 參數 | 意思 |
|---|
-ar 16000 | 取樣率降到 16kHz（Whisper 的原生規格） |
-ac 1 | 併成單聲道 |
-map 0:a | 只要聲音，把影像整個丟掉（影片檔的體積 95% 是影像） |
-c:a flac | 轉成 FLAC（無損壓縮） |
壓完看大小：
"{0:N1} MB" -f ((Get-Item "clean.flac").Length / 1MB)
# macOS / Linux
du -h clean.flac
經驗值：16k 單聲道 FLAC 大約每分鐘 0.8～1 MB。
所以 25 MB ≈ 25～30 分鐘。超過就要切段 → 跳到步驟四。
🟡 真的不想切檔的備案：改用 mp3 低位元率，一小時大約壓到 14 MB。
ffmpeg -i "lesson01.mp4" -ar 16000 -ac 1 -map 0:a -c:a libmp3lame -b:a 32k "clean.mp3"
代價是有損壓縮，中文的準確度會略微下降。本包主線仍走 FLAC ＋ 切段，這個備案只在時間真的不夠時用。
A2. 呼叫 API
Windows（PowerShell，整段是一行，長是正常的）
curl.exe https://api.groq.com/openai/v1/audio/transcriptions -H "Authorization: Bearer $env:GROQ_API_KEY" -F "file=@clean.flac" -F "model=whisper-large-v3" -F "language=zh" -F "temperature=0" -F "response_format=verbose_json" -o "clean.json"
macOS / Linux
curl https://api.groq.com/openai/v1/audio/transcriptions \
-H "Authorization: Bearer $GROQ_API_KEY" \
-F "file=@clean.flac" \
-F "model=whisper-large-v3" \
-F "language=zh" \
-F "temperature=0" \
-F "response_format=verbose_json" \
-o "clean.json"
| 參數 | 為什麼要 |
|---|
model=whisper-large-v3 | 見前面「選哪個模型」 |
language=zh | 一定要加。官方明講：指定語言會同時提升準確度和速度。不加的話它要先花時間猜語言，中英夾雜的課堂錄音很容易猜錯 |
temperature=0 | 要它照聽到的寫，不要自由發揮 |
response_format=verbose_json | 時間碼在這裡面。用 json 或 text 拿不到時間碼 |
-o clean.json | 存成檔案。不存的話一大堆 JSON 會直接噴在螢幕上 |
🚨 A3. 陷阱 ①：不要寫 response_format=srt
OpenAI 的 Whisper API 可以直接回 .srt。Groq 不行。
官方 API 文件寫得很明確——response_format 的 Allowed values 只有 json、text、verbose_json。
打 srt 或 vtt 會拿到 400 錯誤。而網路上 95% 的 Whisper 教學都是寫給 OpenAI 的，照抄過來就會撞這一關。
🔴 請直接記這句話：
Groq 只給你「時間碼 ＋ 文字」，.srt 這個檔案要你自己組。
聽起來很麻煩，其實只是把 JSON 換個排版而已——下面那支小程式一次解決，而且以後長檔切段也是同一支。
A4. 把 verbose_json 組成 .srt
在工作資料夾建立 make_srt.py（這支程式不需要安裝任何套件，全部用 Python 內建的）：
# make_srt.py — 把 Groq 的 verbose_json 組成 .srt
# 用法：uv run python make_srt.py 輸出.srt 第1段.json 第2段.json ...
# 只有一段就只傳一個 json；多段會自動接上時間碼偏移（見步驟四）
import json, os, subprocess, sys
def fmt(t):
"""秒數 → SRT 的 00:00:00,000 格式"""
ms = int(round(t * 1000))
h, ms = divmod(ms, 3600000)
m, ms = divmod(ms, 60000)
s, ms = divmod(ms, 1000)
return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
def real_seconds(path):
"""用 ffprobe 量音訊檔的實際長度（秒）。量不到就回 None"""
try:
out = subprocess.run(
["ffprobe", "-v", "error", "-show_entries", "format=duration",
"-of", "csv=p=0", path],
capture_output=True, text=True, check=True).stdout.strip()
return float(out)
except Exception:
return None
out_path, json_files = sys.argv[1], sys.argv[2:]
if not json_files:
sys.exit("SRT_FAIL 沒有指定任何 json 檔")
offset, idx, blocks = 0.0, 1, []
for jf in json_files:
with open(jf, encoding="utf-8") as f:
data = json.load(f)
for seg in data.get("segments", []):
text = (seg.get("text") or "").strip()
if not text:
continue
blocks.append(
f"{idx}\n{fmt(seg['start'] + offset)} --> {fmt(seg['end'] + offset)}\n{text}\n")
idx += 1
# 🚨 陷阱 ④：偏移量用「這一段的實際長度」累加，不要用名目的 600 秒
audio = os.path.splitext(jf)[0] + ".flac"
dur = real_seconds(audio) if os.path.exists(audio) else None
if dur is None: # ffprobe 不在？改用 API 回傳的長度
dur = float(data.get("duration") or 0.0)
offset += dur
with open(out_path, "w", encoding="utf-8") as f:
f.write("\n".join(blocks))
print(f"SRT_OK segments={idx - 1} files={len(json_files)} out={out_path}")
跑它：
uv run python make_srt.py "lesson01.srt" "clean.json"
（uv 來自 00-env-setup。沒有 uv 就用 python make_srt.py ...，這支程式只用內建模組，任何 Python 3 都跑得動。）
成功的樣子：印出 SRT_OK segments=<某個數字> files=1 out=lesson01.srt，而且 segments 不是 0。
A5. 🚨 陷阱 ③：字幕變成簡體怎麼辦
Whisper 的語言代碼只有「中文（zh）」，沒有「繁體中文」。 它自己決定要吐繁體還是簡體，同一份檔案跑兩次結果還可能不一樣。
兩條路，建議兩條都做：
路線 A（一次搞定，但 Windows 有編碼坑）：用 prompt 參數暗示它
Whisper 的 prompt 參數是用來「示範風格」的（上限 224 token）。你用繁體字寫這個提示，它輸出繁體的機率會大幅提高。
先用記事本建立 prompt.txt（存檔時編碼選 UTF-8），內容一行：
以下是繁體中文的課堂錄音逐字稿。
然後在 A2 的指令尾巴加一個參數：
-F "prompt=<prompt.txt"
🚨 為什麼要用檔案，不直接把中文寫在指令裡？
Windows PowerShell 5.1 把中文參數傳給 curl.exe 時會用系統的 cp950 編碼，送出去常常變亂碼——而且不會報錯，你只會覺得「這個 prompt 好像沒效」。
-F "欄位名=<檔名" 是 curl 的語法，意思是「這個欄位的值從檔案讀」，直接讀原始位元組，繞過整個編碼問題。
macOS / Linux 沒有這個問題，直接寫中文也可以。
📌 這是社群通用做法，不是官方保證。 有效但不是 100%。所以還要有路線 B。
路線 B（零風險保底）：讓 OpenCode 只改字、不准動時間碼
把產出的 .srt 丟給 OpenCode，說：
幫我把這個 .srt 檔的字幕文字全部改成繁體中文（台灣用語），
順便修掉明顯的錯字。
🔴 硬規定：
- 時間碼那幾行（00:00:00,000 --> 00:00:03,120）一個字都不准改
- 字幕的行數與編號不准增減
- 不要合併或拆開任何一段
🔴 最後那三條一定要講，而且要講得像規定。
不講的話，AI 很常「順手」幫你合併太短的句子、重新分段——結果字幕跟畫面整份對不上，而且看起來完全正常，你要放完整支影片才會發現。
建議做法：路線 A 先做（省事），路線 B 當保底（順便修錯字）。
A6. ✅ A 線驗收：換一份新素材，同一句話能不能再跑一次
這才是這一包的驗收，不是「跑出一個 srt」。
| # | 做什麼 | 通過的樣子 |
|---|
| 1 | 用播放器開啟原始影片，把 .srt 拖進去 | 字幕跟嘴巴對得上（不是「有字幕就好」） |
| 2 | 跳到影片最後面看 | 最後一句字幕的時間接近影片總長（差很多 = 時間碼歪了，看步驟四） |
| 3 | 換一支完全不同的錄音，從 A1 重跑一次 | 一樣跑得完 |
| 4 | 🔴 步驟六做完之後：對 OpenCode 說「幫我把 <新檔名> 轉成字幕」 | 它自己做完全部，你沒有再貼任何指令 ← 這一項才是真的通過 |
第 4 項現在還做不到（Skill 還沒包）。先記著它，這是你等一下要達成的目標。
步驟四：長音檔怎麼切、時間碼怎麼接（🚨 這裡處理陷阱 ④）
只有超過 25 MB（約 25～30 分鐘）才需要這一步。 短檔請直接跳到步驟五。
官方建議 vs 本包做法
Groq 官方建議的是「切成有重疊的片段，各自轉，合併時處理重疊的部分」，並附了一份 Cookbook 範例。
本包不走重疊那條，理由很實際：重疊之後要判斷「這兩段重複的文字哪一份才對、接縫在哪」，這是整條流程裡最容易寫錯、也最難驗證的部分。對老師來說划不來。
本包做法：不重疊、切固定長度、用「每一段的實際長度」累加時間碼。
代價是接縫處可能斷在句子中間（少一兩個字或斷句怪怪的）。
但這件事步驟五的清洗會順手修掉，而且比起「整份時間碼歪掉」，這個代價便宜太多。
4-1 切檔（先壓再切，順序不能反）
# ① 先壓成 16k 單聲道 FLAC（跟 A1 一模一樣）
ffmpeg -i "lesson01.mp4" -ar 16000 -ac 1 -map 0:a -c:a flac "clean.flac"
# ② 再切成每段 10 分鐘（600 秒）
ffmpeg -i "clean.flac" -f segment -segment_time 600 -c:a flac "chunk_%03d.flac"
會產生 chunk_000.flac、chunk_001.flac、chunk_002.flac…
為什麼是 10 分鐘？
10 分鐘的 16k 單聲道 FLAC 約 8～10 MB，離 25 MB 上限有很大的安全邊際。
切太小反而浪費（記得「最低計費 10 秒」那條），切太大會踩到上限。10 分鐘是甜蜜點。
為什麼要先壓再切？
這樣每一段的規格完全一致，量長度、接時間碼都不會出意外。
先切再壓的話，每段會各自被 ffmpeg 處理一次，長度可能出現零點幾秒的差異。
4-2 逐段呼叫 API
Windows（PowerShell）
Get-ChildItem "chunk_*.flac" | Sort-Object Name | ForEach-Object {
$out = $_.BaseName + ".json"
Write-Host "轉換中：$($_.Name)"
curl.exe https://api.groq.com/openai/v1/audio/transcriptions -H "Authorization: Bearer $env:GROQ_API_KEY" -F "file=@$($_.Name)" -F "model=whisper-large-v3" -F "language=zh" -F "temperature=0" -F "response_format=verbose_json" -o $out
Start-Sleep -Seconds 3
}
macOS / Linux
for f in chunk_*.flac; do
echo "轉換中：$f"
curl https://api.groq.com/openai/v1/audio/transcriptions \
-H "Authorization: Bearer $GROQ_API_KEY" \
-F "file=@$f" -F "model=whisper-large-v3" -F "language=zh" \
-F "temperature=0" -F "response_format=verbose_json" \
-o "${f%.flac}.json"
sleep 3
done
💡 中間的 Start-Sleep 3 / sleep 3 是刻意的：免費方案每分鐘 20 次，這樣跑絕對不會撞到上限。
一支 1 小時的錄音會切成 6 段，全部跑完大約 1 分鐘。
檢查每一段都有回來：
Get-ChildItem "chunk_*.json" | Select-Object Name, Length
🔴 有哪個 .json 大小只有幾百 bytes → 那一段失敗了，裡面裝的是錯誤訊息不是字幕。
用記事本打開看它寫什麼，對照本文件最後的「常見卡關」。不要就這樣往下做，那一段的字幕會整段消失。
4-3 合併（🚨 這裡就是陷阱 ④）
為什麼不能直接接起來
每一段轉回來的時間碼，都是從 00:00:00 開始的。
也就是說第二段的第一句話，API 說它在 0 分 3 秒——但它實際上在整支影片的 10 分 3 秒。
直接把 6 段接起來，你會得到一份「前 10 分鐘有 6 份字幕、後面 50 分鐘全空」的檔案。
正確做法：加偏移量。但不能用「10 分鐘」硬算
🔴 這是本包最細、也最多人做錯的一條：
ffmpeg 的 -segment_time 600 是「大約 600 秒」，不是「剛好 600 秒」——實際切點會落在音訊的封包邊界上。
每段差個零點幾秒，六段累積起來就是好幾秒。
字幕一開始對得很好，越到後面越飄——而這種錯誤最難發現，因為前 10 分鐘完全正常。
正解：用 ffprobe 量每一段的實際長度，一段一段累加。
make_srt.py 已經內建這個做法（real_seconds() 那個函式），你不用自己算。
直接跑（把所有 json 按順序一次餵進去）：
Windows
$files = (Get-ChildItem "chunk_*.json" | Sort-Object Name).Name
uv run python make_srt.py "lesson01.srt" $files
macOS / Linux
uv run python make_srt.py "lesson01.srt" $(ls chunk_*.json | sort)
🔴 順序絕對不能錯。 chunk_010.json 一定要排在 chunk_002.json 後面。
上面用了 Sort-Object Name / sort，而檔名是三位數補零的（%03d），所以字母排序就是正確順序。
如果你自己手動列檔名，請務必檢查順序——順序一錯，整份字幕會亂到看不出規律。
📌 ffprobe 真的裝不起來的備援：make_srt.py 量不到長度時，會自動改用 API 回傳的 duration 欄位。
那個數字是 Groq 算的，通常也很準，只是不像 ffprobe 那樣是直接量檔案。能裝 ffprobe 還是裝。
4-4 驗證時間碼有沒有歪（🔴 這一步不要跳過）
這是唯一能抓到時間碼漂移的方法：
| # | 做什麼 | 通過的樣子 |
|---|
| 1 | 看原始影片的總長度 | 記下來，例如 58:20 |
| 2 | 用記事本打開 .srt，捲到最後一行 | 最後一個時間碼很接近 58:20（差 5 秒內算正常） |
| 3 | 把 .srt 拖進播放器，跳到影片最後 2 分鐘 | 字幕還對得上嘴巴 |
| 4 | 跳到每一個接縫處（10 分、20 分、30 分…） | 那附近的字幕沒有明顯偏移 |
🔴 只驗開頭是抓不到這個 bug 的。 時間碼漂移的特徵就是「前面完全正常」。
一定要看最後面。
歪掉了怎麼辦：
| 症狀 | 原因 |
|---|
最後一句只到 10:00 左右 | 只餵了一個 json 進去，或檔案順序被打亂 |
| 越後面偏差越大 | ffprobe 沒裝，而且 API 的 duration 也不準 → 補裝系統版 FFmpeg 再跑一次 make_srt.py（不用重轉，json 都還在） |
| 中間整段字幕消失 | 某一段的 .json 其實是錯誤訊息（回 4-2 檢查每個 json 的大小） |
步驟五：B 線 — 把逐字稿清洗成講義
5-1 先把 srt 變成純文字
字幕檔裡有編號和時間碼，那些不需要送去清洗（還會白白吃掉寶貴的 token 額度）。
uv run python -c "import re,sys;t=open('lesson01.srt',encoding='utf-8').read();lines=[l for l in t.splitlines() if l.strip() and not l.strip().isdigit() and '-->' not in l];open('lesson01.txt','w',encoding='utf-8').write('\n'.join(lines))"
或者更簡單——直接把 .srt 丟給 OpenCode 說「把時間碼和編號拿掉，只留文字，存成 lesson01.txt」。
5-2 建立清洗程式
在同一個資料夾建立 clean.py（一樣不需要安裝任何套件）：
# clean.py — 把逐字稿清洗成可讀講義（Groq Chat Completions）
# 用法：uv run python clean.py 逐字稿.txt 講義.md
import json, os, sys, time, urllib.error, urllib.request
API = "https://api.groq.com/openai/v1/chat/completions"
MODEL = "llama-3.3-70b-versatile" # 會改名！先跑 /v1/models 確認
LIMIT = 1200 # 每段送幾個字。免費方案 TPM 很小，不要調大
KEY = os.environ.get("GROQ_API_KEY")
if not KEY:
sys.exit("CLEAN_FAIL 環境變數 GROQ_API_KEY 沒設，回步驟二")
SYSTEM = (
"你是台灣國中小老師的文字編輯助理。把語音辨識出來的逐字稿，"
"整理成可以直接發給學生看的講義段落。規則："
"① 一律輸出繁體中文，用台灣的慣用詞；"
"② 刪掉贅詞、口頭禪、結巴、重複、以及講者自己更正掉的前半句；"
"③ 補上標點符號，依語意分段；"
"④ 不要新增原文沒有的內容，不要加自己的解釋；"
"⑤ 聽不出來的地方原樣保留，並在後面加上 [?]；"
"⑥ 不要寫開場白或結語，直接輸出整理後的內文。"
)
def split_text(raw, limit):
"""依行切段，盡量不切在句子中間"""
parts, buf = [], ""
def flush():
nonlocal buf
if buf.strip():
parts.append(buf)
buf = ""
for line in raw.splitlines(keepends=True):
while len(line) > limit: # 整篇沒換行的長文，只好硬切
flush()
parts.append(line[:limit])
line = line[limit:]
if len(buf) + len(line) > limit:
flush()
buf += line
flush()
return parts
def call(text):
body = json.dumps({
"model": MODEL,
"temperature": 0.2,
"messages": [{"role": "system", "content": SYSTEM},
{"role": "user", "content": text}],
}).encode("utf-8")
req = urllib.request.Request(API, data=body, headers={
"Authorization": "Bearer " + KEY,
"Content-Type": "application/json",
})
with urllib.request.urlopen(req, timeout=180) as r:
return json.load(r)["choices"][0]["message"]["content"].strip()
raw = open(sys.argv[1], encoding="utf-8").read()
parts = split_text(raw, LIMIT)
out = []
for n, p in enumerate(parts, 1):
print(f"清洗第 {n}/{len(parts)} 段…")
for attempt in range(3):
try:
out.append(call(p))
break
except urllib.error.HTTPError as e:
detail = e.read().decode("utf-8", "ignore")[:300]
if e.code == 429 and attempt < 2: # 額度滿了，等一下再試
print(" 額度滿了，等 35 秒再試")
time.sleep(35)
continue
sys.exit(f"CLEAN_FAIL http={e.code} {detail}")
time.sleep(2) # 段與段之間刻意留間隔
open(sys.argv[2], "w", encoding="utf-8").write("\n\n".join(out))
print(f"CLEAN_OK pieces={len(parts)} out={sys.argv[2]}")
跑它：
uv run python clean.py "lesson01.txt" "lesson01-講義.md"
成功的樣子：一段一段印出進度，最後印 CLEAN_OK pieces=<數字> out=lesson01-講義.md。
5-3 為什麼要分段、為什麼中間要等
| 設計 | 理由 |
|---|
LIMIT = 1200（一段 1,200 字） | 免費方案 llama-3.3-70b-versatile 每分鐘只有 12,000 token。一小時的逐字稿一次送必定 429 |
段與段之間 sleep 2 | 讓每分鐘的 token 用量攤平，不會集中在前 10 秒燒完 |
遇到 429 等 35 秒重試 | token 額度是每分鐘重置的，等一下就會恢復 |
🔴 不要把 LIMIT 調大想跑快一點。 調大只會讓你更快撞到 429，然後每次都要等 35 秒，整體反而更慢。
5-4 想要別的產出，改 SYSTEM 那段就好
clean.py 裡的 SYSTEM 字串就是「你要它做什麼」。改那一段，這支程式就變成另一個工具：
| 你想要 | SYSTEM 改成 |
|---|
| 講義（預設） | 上面那段 |
| 課堂重點摘要 | 「把逐字稿整理成 5～8 條重點，每條一行，用繁體中文…」 |
| 學生自學版（口語轉書面） | 「把逐字稿改寫成適合國中生自己閱讀的說明文…」 |
| 抽出考題素材 | 「從逐字稿裡找出可以出題的概念，列成清單…」 |
💡 這就是「把 API 變成工具」的意思——同一支程式、同一把金鑰，換一段話就換一個工具。
5-5 ✅ B 線驗收：換一份新素材，同一句話能不能再跑一次
| # | 做什麼 | 通過的樣子 |
|---|
| 1 | 打開 lesson01-講義.md | 是通順的繁體中文段落，不是一長串沒標點的字 |
| 2 | 跟原逐字稿對照 | 意思沒被改掉、沒有多出原文沒講過的內容 |
| 3 | 找一段你記得自己講錯又更正的地方 | 更正前那半句被刪掉了 |
| 4 | 換一份完全不同的逐字稿，重跑一次 | 一樣跑得完 |
| 5 | 🔴 步驟六做完之後：對 OpenCode 說「幫我把 <新檔名> 整理成講義」 | 它自己做完，你沒有再貼指令 ← 這一項才是真的通過 |
⚠️ 第 2 項要真的看。語言模型偶爾會「幫你補充」——補出來的東西看起來很專業，但你根本沒講過。
發講義前自己讀一遍，這件事不能外包。
步驟六：把整條流程包成 Skill（🔴 這是作品⑤ 的正題）
前面五步都是「跑一次」。跑一次的東西下個月一定忘記。
現在把它變成一個技能：以後在任何資料夾、對 OpenCode 說一句人話，它就會自己做完。
6-1 建立技能資料夾
Windows
New-Item -ItemType Directory -Force "$HOME\.config\opencode\skills\audio-notes"
macOS / Linux
mkdir -p ~/.config/opencode/skills/audio-notes
⚠️ 資料夾名稱要和技能的 name 一模一樣，檔名要是全大寫的 SKILL.md，OpenCode 才掃得到。（規矩同 08-workflow-skills。）
6-2 把兩支小程式搬進去
Copy-Item "$HOME\Documents\groq-subtitle\make_srt.py" "$HOME\.config\opencode\skills\audio-notes\"
Copy-Item "$HOME\Documents\groq-subtitle\clean.py" "$HOME\.config\opencode\skills\audio-notes\"
🔴 搬之前先確認這兩支檔案裡沒有金鑰。 它們讀的是 os.environ.get("GROQ_API_KEY")，本來就沒有——但如果你剛剛「為了測試方便」把金鑰貼死在裡面，現在就是把它拿掉的時候。
6-3 建立 SKILL.md
把下面整段內容原封不動寫入 ~/.config/opencode/skills/audio-notes/SKILL.md
（不要把最外層的 ``` 圍籬符號寫進檔案，檔案第一行必須是 ---）：
---
name: audio-notes
description: 把音訊或影片轉成字幕檔（.srt），以及把逐字稿清洗成可讀講義（.md）。當使用者說「轉字幕」、「上字幕」、「做逐字稿」、「這個錄音幫我轉文字」、「把逐字稿整理成講義」、「把這段錄音變成講義」時，請一定要使用此技能。走 Groq 的 Whisper 與文字模型，金鑰讀自環境變數 GROQ_API_KEY。
---
# 音訊 → 字幕 → 講義
## 🔴 執行前必問（不可跳過）
動手之前，先問使用者這一句，**等到回答再繼續**：
> 「這個音檔裡面**有沒有學生、家長的聲音**，或是輔導、個案相關的內容？
> 有的話這條流程不能用——語音會上傳到雲端。」
- 回答「有」或「不確定」 → **停止，不要呼叫任何 API**，把原因說清楚
- 回答「沒有，只有我自己的聲音」 → 繼續
順便提醒一次：**上傳前先聽檔案的最後 30 秒**，課堂錄音常常錄到下課後的對話。
## 金鑰
金鑰一律從環境變數 `GROQ_API_KEY` 讀取。
- **不准**把金鑰寫進本檔案、寫進任何 `.py`、寫進任何會被 commit 的檔案
- **不准**把金鑰印在終端機上、或複述給使用者看
- 環境變數不存在 → 停下來，請使用者依懶人包 `09-groq-api` 步驟二設定，**不要自己想辦法繞過**
## 模式 A：音訊 → 字幕（.srt）
1. **檢查工具**：`ffmpeg -version`、`ffprobe -version`。缺了就停下來告訴使用者（懶人包 `02-file-toolkit` B 段）
2. **檔名先換成英數字**（中文檔名在 Windows 命令列可能亂碼），全部跑完再改回來
3. **壓縮**：
`ffmpeg -i <來源> -ar 16000 -ac 1 -map 0:a -c:a flac clean.flac`
4. **看大小**。25 MB 以內 → 跳到第 6 步；超過 → 第 5 步
5. **切段**（每段 600 秒）：
`ffmpeg -i clean.flac -f segment -segment_time 600 -c:a flac chunk_%03d.flac`
6. **逐段呼叫 API**，每次之間停 3 秒：
端點 `https://api.groq.com/openai/v1/audio/transcriptions`
參數 `model=whisper-large-v3`、`language=zh`、`temperature=0`、`response_format=verbose_json`
輸出存成與音訊同名的 `.json`
- 🚨 **`response_format` 不可以填 `srt` 或 `vtt`**，Groq 不支援，會回 400
7. **檢查每個 `.json`**：檔案太小（幾百 bytes）代表那一段失敗了，是錯誤訊息不是字幕。**先處理再往下**
8. **組 srt**（json 一定要照檔名排序傳入）：
`uv run python <本技能資料夾>/make_srt.py <輸出>.srt chunk_000.json chunk_001.json ...`
9. **繁體化**：把產出的 srt 逐句改成繁體中文並修錯字。
🔴 **時間碼那幾行一個字都不准改，行數與編號不准增減，不准合併或拆開任何一段。**
10. **回報**：段數、輸出路徑，並提醒使用者「請拖進播放器確認**最後 2 分鐘**的字幕還對得上」
## 模式 B：逐字稿 → 講義（.md）
1. 來源是 `.srt` → 先去掉編號與時間碼，只留文字，存成 `.txt`
2. 執行：`uv run python <本技能資料夾>/clean.py <逐字稿>.txt <輸出>.md`
3. 拿到 `CLEAN_OK` 才算成功
4. 回報時**一定要加這句**：「語言模型偶爾會補充原文沒有的內容，**發給學生前請自己讀一遍**」
## 常見狀況
| 狀況 | 處理 |
|------|------|
| `400` 且訊息提到 `response_format` | 用了 `srt`／`vtt`，改成 `verbose_json` |
| `413` 或檔案太大 | 沒壓縮，或壓完仍超過 25 MB → 回去切段 |
| `429` | 額度滿了，等 35 秒再試，**不要換模型硬闖** |
| `401` / `invalid_api_key` | `GROQ_API_KEY` 沒設或設錯 → 停下來請使用者處理 |
| 模型名稱不存在 | 跑 `https://api.groq.com/openai/v1/models` 看現在有哪些，不要亂猜 |
| 字幕越後面越對不上 | `ffprobe` 沒裝，`make_srt.py` 量不到每段實際長度。補裝 FFmpeg 後**重跑 make_srt.py 就好，不用重轉** |
## 不該做的事
- ❌ 使用者沒回答隱私那一題就開始上傳
- ❌ 把金鑰寫進任何檔案或印出來
- ❌ 修改 srt 的時間碼
- ❌ 為了「快一點」把清洗的分段字數調大（只會更快撞 429）
- ❌ 一次送幾十個很短的小檔（最低計費 10 秒，額度會白白燒光）
## 注意事項
- 所有訊息使用**繁體中文**
- Windows 用 PowerShell，串指令用 `;` 不要用 `&&`
- Windows 呼叫 curl 要打 `curl.exe`（有 `.exe`）
6-4 允許這個技能
打開（或建立）~/.config/opencode/opencode.json，確認 permission.skill 裡有這一項：
{
"permission": {
"skill": {
"audio-notes": "allow"
}
}
}
⚠️ 如果 opencode.json 已經有內容（前面幾包加的 MCP 設定、08-workflow-skills 加的三個技能），不要整份覆蓋，只要把 audio-notes 這一行併進既有的 permission.skill 區塊就好。
6-5 重啟 OpenCode
OpenCode 只有啟動時才會掃描技能目錄。 剛剛新增的資料夾，要完全關掉再重開才會被認得（關視窗不算，要真的結束程序）。
6-6 ✅ 最終驗收：這一包成不成功，看這裡
| # | 做什麼 | 通過的樣子 |
|---|
| 1 | 對 OpenCode 說「列出你現在可用的技能」 | 清單裡有 audio-notes |
| 2 | 拿一份全新的、沒跑過的錄音，說「幫我把 <檔名> 轉成字幕」 | 它自己壓縮、呼叫 API、組 srt、繁體化，你沒有貼任何指令 |
| 3 | 檢查它有沒有先問隱私那一題 | 有問 ← 沒問的話回去看 SKILL.md 是不是貼漏了 |
| 4 | 拿一份全新的逐字稿，說「幫我把 <檔名> 整理成講義」 | 它自己做完 |
| 5 | 打開 SKILL.md、make_srt.py、clean.py 搜尋 gsk_ | 🔴 三個檔案裡都搜不到 ← 搜到就是失敗，回步驟二 |
🔴 第 2 項和第 4 項就是這一包的分水嶺。
做得到 = 你有了一個工具。做不到 = 你只是跑過一次。
差別在下個月：有工具的人會再用，跑過一次的人早就忘了。
常見卡關
金鑰與帳號
| 症狀 | 原因 / 解法 |
|---|
KEY_MISSING | 環境變數沒生效。重開終端機（連 OpenCode 也要完全關掉重開） |
401 / invalid_api_key | 金鑰複製時少一截，或前後多了空白。回 Console 重新產一把 |
| 金鑰畫面關掉了才發現沒複製 | 看不回來，只能刪掉重產。 這是設計，不是壞掉 |
| 註冊時要求信用卡 | 你走進升級流程了。 按上一頁退出來，免費方案不需要卡 |
| 金鑰不小心 push 上 GitHub | 刪檔案沒用。立刻回 Console 刪掉那把金鑰、重產一把。 然後更新環境變數 |
A 線（轉字幕）
| 症狀 | 原因 / 解法 |
|---|
400 提到 response_format | 🚨 陷阱 ①。填了 srt／vtt，Groq 不支援。改 verbose_json，用 make_srt.py 組 |
413 / 檔案太大 | 🚨 陷阱 ②。免費方案單檔 25 MB。回 A1 壓縮，還是太大就切段 |
| 轉出來是簡體 | 🚨 陷阱 ③。看 A5 兩條路線 |
.srt 拖進播放器沒反應 | 檔名要和影片同名（lesson01.mp4 ↔ lesson01.srt），或播放器裡手動載入 |
| 字幕全部集中在前 10 分鐘 | 🚨 陷阱 ④。只餵了一個 json，或檔案順序亂了。回 4-3 |
| 越後面偏差越大 | ffprobe 沒裝。補裝 FFmpeg，重跑 make_srt.py 就好，不用重轉（json 都還在） |
| 中間有一整段沒字幕 | 那一段的 .json 是錯誤訊息。回 4-2 檢查每個 json 的大小 |
SRT_OK segments=0 | API 回的 json 裡沒有 segments——多半是 response_format 沒填 verbose_json |
| 字幕內容整段重複 | 音檔裡有長時間靜音，Whisper 的已知行為。剪掉靜音再轉 |
ffmpeg 說找不到檔案，但檔案就在 | 中文檔名 ／ 路徑有空白。先改成英數字檔名，或整個路徑用雙引號包起來 |
| 一句一個檔跑，額度突然沒了 | 最低計費 10 秒。改成切 10 分鐘大段 |
B 線（文字清洗）
| 症狀 | 原因 / 解法 |
|---|
429 | 每分鐘 token 額度滿了。程式會自己等 35 秒重試；一直發生就把 LIMIT 調小（例如 800） |
CLEAN_FAIL http=404 | 模型改名了。跑 /v1/models 看現在叫什麼，改 clean.py 的 MODEL |
| 講義裡出現我沒講過的內容 | 語言模型「幫你補充」了。把 SYSTEM 的第 ④ 條講更重，或改用比較大的模型 |
| 輸出還是簡體 | SYSTEM 第 ① 條被忽略了。在使用者訊息開頭再寫一次「請用繁體中文（台灣）輸出」 |
| 跑很慢 | 正常。免費方案要分段＋等待。一小時的逐字稿約 10 段，大約 2～3 分鐘 |
| 專有名詞一直錯 | 語音辨識階段就聽錯了。把正確寫法列在 SYSTEM 裡，例如「本文的專有名詞：正三角形、外心、內心」 |
Skill 與環境
| 症狀 | 原因 / 解法 |
|---|
| 技能沒出現在清單 | ①檔名要全大寫 SKILL.md ②資料夾名要等於 name ③檔案第一行必須是 ---（圍籬符號不要寫進去）④沒重啟 OpenCode |
技能叫得動但找不到 .py | SKILL.md 裡要用技能資料夾的完整路徑叫程式，不是相對路徑 |
uv 說找不到 | 回 00-env-setup。或直接用 python make_srt.py ...，這兩支程式只用內建模組 |
ffprobe 找不到 | 只裝了 yt-dlp 自帶的 FFmpeg。winget install --id Gyan.FFmpeg -e（沒管理員權限加 --scope user） |
| PowerShell 串指令語法錯誤 | PowerShell 5.1 不支援 &&，改用 ; |
curl 行為很奇怪 | Windows 要打 curl.exe（有 .exe），否則叫到 PowerShell 的別名 |
| 中文參數傳給 curl 變亂碼 | PowerShell 5.1 的編碼問題。改用 -F "欄位=<檔名" 從檔案讀（見 A5） |
opencode.json 存檔後 OpenCode 起不來 | JSON 格式：大括號要成對、引號要用英文半形 "、Windows 路徑反斜線寫兩條 \\ |
✅ 成功訊號（機器可判讀）
執行完請完整輸出下面這個區塊，讓後續的 agent 可以直接判讀。
=== OPENCODE_GROQ_API ===
result=PASS # PASS | PARTIAL | FAIL
os=windows # windows | macos | linux
privacy_confirmed=yes # yes | no（使用者已確認素材不含學生/家長聲音）
key_set=yes # yes | no（環境變數 GROQ_API_KEY 存在）
key_in_files=no # no | yes（SKILL.md 與 .py 內是否搜得到 gsk_）
api_ok=yes # yes | no（/v1/models 回傳正常）
ffmpeg=ok # ok | missing
ffprobe=ok # ok | missing（缺了會退用 API 的 duration）
model_stt=whisper-large-v3 # 實際使用的語音模型
model_llm=llama-3.3-70b-versatile # 實際使用的文字模型
srt_single=OK # OK | FAIL | SKIP（單檔轉字幕）
srt_chunked=OK # OK | FAIL | SKIP（長檔切段合併）
srt_tail_aligned=yes # yes | no（影片最後 2 分鐘字幕仍對得上）
clean_ok=OK # OK | FAIL | SKIP
skill_installed=yes # yes | no（~/.config/opencode/skills/audio-notes/）
skill_listed=yes # yes | no（重啟後 OpenCode 掃得到）
skill_rerun_srt=OK # OK | FAIL（換新素材，一句話跑完 A 線）
skill_rerun_clean=OK # OK | FAIL（換新素材，一句話跑完 B 線）
=== END ===
判定規則（agent 請照這個判斷，不要自行認定）：
| 結果 | 條件 |
|---|
PASS | skill_rerun_srt=OK 且 skill_rerun_clean=OK 且 key_in_files=no |
PARTIAL | A、B 兩線手動跑得起來，但技能沒包成／換素材沒跑通 |
FAIL | api_ok=no，或 A、B 兩線都跑不起來 |
🔴 兩條會直接讓整體變成 FAIL 的：
key_in_files=yes —— 金鑰出現在任何檔案裡，不管其他項目多漂亮，一律 FAIL。
privacy_confirmed=no —— 沒跟使用者確認過素材內容就上傳，一律 FAIL，而且要在回報裡明確寫出來。
這兩條不准「先繼續、之後再補」。
完成回報格式
## Groq API 工具化結果
### 隱私確認
- 已向使用者確認素材不含學生／家長／輔導內容：是 / 否
- 已提醒「上傳前聽最後 30 秒」：是 / 否
- Zero Data Retention 已開啟：是 / 否 / 未確認
### 金鑰
- 存放方式：環境變數 / 專案 .env
- `.gitignore` 已擋住 `.env`（`git check-ignore -v .env` 有輸出）：是 / 否 / 不適用
- SKILL.md 與 .py 內搜尋 `gsk_`：查無 / ⚠️ 有（立刻撤銷重產）
- 金鑰驗證（`/v1/models`）：PASS / FAIL
### A 線：轉字幕
- 使用模型：<實際用的>
- 來源檔長度：<分鐘> ／ 壓縮後大小：<MB>
- 是否切段：否 ／ 是（<N> 段，每段 600 秒）
- 產出：`<路徑>.srt`（<N> 句）
- 時間碼驗證（看**最後 2 分鐘**）：PASS / FAIL
- 繁體化方式：prompt 參數 / OpenCode 改字 / 兩者都做
### B 線：文字清洗
- 使用模型：<實際用的>
- 分段數：<N>
- 產出：`<路徑>.md`
- 已提醒使用者「發給學生前自己讀一遍」：是 / 否
### 工具化（本包正題）
- 技能位置：`~/.config/opencode/skills/audio-notes/`
- 隨附程式：`make_srt.py`、`clean.py`
- `opencode.json` 權限已加：是 / 否
- 已重啟 OpenCode：是 / 否
- 技能出現在清單：是 / 否
- 🔴 **換新素材、一句話跑完 A 線**：PASS / FAIL
- 🔴 **換新素材、一句話跑完 B 線**：PASS / FAIL
### 待處理
- <把 FAIL 的項目與原因列在這裡；全部 PASS 就寫「無」>
如果做壞了，怎麼重來
對 OpenCode 說：「Groq 這一包做壞了，幫我清乾淨重來。」
| 想重來的東西 | 做法 |
|---|
| 只是某一段轉壞了 | 刪掉那一段的 .json，重跑那一段就好。其他段不用重轉 |
| 時間碼歪了 | 補裝 ffprobe，重跑 make_srt.py。API 不用重打，json 都還在 |
| 字幕整份要重來 | 刪掉 chunk_*.json 和 .srt，從 4-2 重跑 |
| 技能沒被掃到 | 檢查檔名是不是 SKILL.md（全大寫）、資料夾名是不是 audio-notes、第一行是不是 ---。改完完全關閉 OpenCode 再開 |
| 技能整個不要了 | 刪掉 ~/.config/opencode/skills/audio-notes/ 資料夾，並從 opencode.json 的 permission.skill 移除那一行 |
| 金鑰外洩 | 🔴 Console → API Keys → 刪掉那把、重產一把 → 更新環境變數。這件事優先於其他所有事 |
⚠️ 重跑 API 之前先想一下額度：免費方案每小時 7,200 音訊秒。
一支 1 小時的錄音重轉三次就用掉一半。先確認是哪一步壞了，不要整條重來。
下一步
🚀 下午：把這個工具變成網頁 → 10-netlify
現在你有一個「只有你的電腦能用」的工具。
下午那一包會把它放上網路——別的老師打開網址就能用，不用裝 OpenCode、不用申請金鑰。
今天早上寫的 clean.py、學到的「金鑰放環境變數不放檔案」，下午會原封不動用上。
（尤其是金鑰那條：網頁上線之後，金鑰放錯地方是全世界都看得到。這件事今天先練，下午就不會慌。）
其他方向：
- 素材從哪裡來（下載影片、抽音軌、抓現成字幕）→
02-file-toolkit 的 B 段
- 產出的講義要收進第二大腦 →
04-obsidian
- 工具要備份、換電腦也帶著走 →
07-github
- 想讓「轉字幕」也能被開工／收工流程接住 →
08-workflow-skills
📌 提醒一件事：~/.config/opencode/skills/ 底下的技能不在任何專案的 repo 裡。
換一台電腦，這個技能不會跟著過去。要帶著走，就把 audio-notes 這個資料夾也放進你的 GitHub（見 07-github）——但記得，裡面永遠不要有金鑰。
