影片技能
使用 ffmpeg、Deepgram Nova 3 以及 S3/隧道分享來處理和分享影片。
預設值：更輕量的影片，相同解析度
預設一律以原始解析度重新編碼為較小的檔案。 一個壓縮過、解析度相同的副本幾乎總是使用者想要的——上傳更快、分享更輕量、觀看體驗一致。在所有流程（靜默模式、互動模式以及 Gemini 的 dev-video 播放編碼）中將此設為預設值；僅在使用者明確要求時才偏離。具體來說：
- 預設最佳化 =
--resolution keep— 使用 libx264 + CRF 重新編碼，不套用縮放濾鏡，因此解析度不變，檔案變得更小。這是推薦的 Q1 選擇，也是靜默模式的預設值。 - 僅在來源解析度明顯大於 1080p（≥1440p / 4K）或使用者要求時才降低解析度（例如降至 1080p）。絕不進行升頻。
- 僅在使用者明確要求原始檔案時才跳過重新編碼（使用未修改的原始檔/串流複製）——例如「保留原始檔」、「不要重新編碼」。
- 安全性檢查： 編碼後，比較輸出檔案大小與來源檔案。如果沒有顯著變小（罕見情況，例如來源已為低位元率），則提高 CRF（26–28）或回退使用原始檔。螢幕錄影的壓縮效果特別好：CRF 24–26 搭配
preset slow通常可減少 70–80% 的大小，同時保持螢幕文字清晰。 - 下載按鈕： 頁面預設顯示一個**「下載影片」按鈕（指向播放影片）。僅在您實際將未修改的原始檔案上傳到輸出資料夾並使用該確切名稱時，才新增「下載原始檔」按鈕——即傳遞
render_page.py --original-filename <name>；否則按鈕會連結到一個不存在的檔案並導致 404 錯誤。預設的壓縮-保留流程不會保留單獨的原始檔，因此請勿傳遞--original-filename**。
先決條件
- 必須安裝
ffmpeg和ffprobe - 必須可使用 Python 3
- 必須可使用
awsCLI（用於 S3 上傳） - Deepgram API 金鑰——用於音訊轉錄/字幕（預設引擎）
- OpenRouter API 金鑰——用於 Gemini 分析引擎（
dev-video/transcript-cheap模式）。非必要，僅在選擇這些模式時需要。
目錄
- 腳本：
<skill_dir>/scripts/——所有 Python 腳本和 player.html 模板 - 憑證：
~/.config/video-skill/——在插件更新後仍持續存在deepgram_token——單行 Deepgram API 金鑰openrouter_token——單行 OpenRouter API 金鑰（Gemini 分析引擎）s3_credentials——key=value 格式（endpoint, bucket, access_key, secret_key）
- 偏好設定：
~/.config/video-skill/preferences.json——跨會話儲存的使用者選擇
憑證設定
當需要時憑證缺失，透過 AskUserQuestion 詢問使用者：
Deepgram： 檢查 DEEPGRAM_API_KEY 環境變數，然後檢查 ~/.config/video-skill/deepgram_token 檔案。如果兩者都不存在，詢問使用者並儲存到檔案。
OpenRouter： 檢查 OPENROUTER_TOKEN 環境變數，然後檢查 ~/.config/video-skill/openrouter_token 檔案。僅在 dev-video / transcript-cheap 分析模式時需要。如果選擇了 Gemini 模式但令牌缺失，詢問使用者並儲存到檔案。
S3： 檢查環境變數（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、S3_ENDPOINT、S3_BUCKET），然後檢查 ~/.config/video-skill/s3_credentials。如果缺失，詢問使用者 endpoint、bucket、access_key、secret_key 並儲存。
重要： 切勿將憑證作為 CLI 參數傳遞。腳本透過 --credential-dir ~/.config/video-skill 從內部檔案讀取它們。
偏好設定
{
"language": "en",
"last_folder": "/Users/example/screencasts",
"share_folder": "/Users/example/screencasts",
"sharing_method": "s3",
"optimization": "compress-keep",
"crf": 23,
"preset": "medium",
"audio": "aac-128k",
"subtitles": "track",
"subtitle_style": "modern",
"subtitle_font": "Helvetica Neue",
"target_language": "ru",
"download_button": true,
"passcode": true,
"mode": "subtitles"
}
optimization：播放影片的編碼方式。預設 compress-keep = 以來源解析度重新編碼以獲得更輕量的檔案（--resolution keep）。其他值：web-1080p（降低解析度至 1080p——適用於 ≥1440p/4K 來源）、custom、keep-original（不重新編碼——僅在使用者明確要求時）。請參閱上方**「預設值：更輕量的影片，相同解析度」**。
mode：一個決定轉錄/分析引擎的單一欄位。四個值之一（舊的 analysis_mode + developer_analysis 對組合成此）：
mode | 引擎 | 字幕 | 開發者分析 | 使用時機 |
|---|---|---|---|---|
subtitles（預設） | Deepgram | 精確 | 無 | 一般分享，只需字幕 |
dev-audio | Deepgram | 精確 | 是（來自轉錄文字） | 工具/錯誤回饋，也需要乾淨字幕 |
dev-video | Gemini 影片 | 粗略 | 是 + 螢幕截圖 | 最豐富的工具/UX 回饋（讀取螢幕內容） |
transcript-cheap | Gemini 音訊 | 粗略 | 無 | 便宜的粗略轉錄，時間不重要 |
內部：subtitles/dev-audio 執行 process_and_share.py（後者帶有 --developer-analysis）；dev-video/transcript-cheap 執行 Gemini 引擎（gemini_analyze.py）。「開發者分析」= 頁面內的區塊加上分析 Markdown 文件（請參閱該段落）。引擎建議（研究於 2026-06）：對於精確字幕保留 Deepgram；對於分析使用 Gemini-video，對於便宜的粗略轉錄使用 Gemini-audio。對於同時需要精確字幕的 dev-video，額外執行一次 Deepgram 通道以產生字幕軌道。
儲存： 每次互動式選擇後，更新 preferences.json。每次執行後務必儲存 last_folder。
載入： 啟動時讀取。使用儲存的值作為「（推薦）」預設值。在靜默模式下，直接使用。
腳本參考
所有腳本位於 <skill_dir>/scripts/。它們接受 --credential-dir 以取得憑證，並列印 [PROGRESS] 行以進行狀態追蹤。
| 腳本 | 用途 | 關鍵參數 |
|---|---|---|
process_and_share.py | 主要工作流程：最佳化 + 轉錄 + 渲染 + 上傳 | <video> --output-dir --share-folder --share s3|tunnel |
share_existing.py | 分享一個已處理的資料夾 | <folder> --share-folder --share s3|tunnel |
upload_s3.py | 將資料夾上傳至 S3 | <folder> --key <key> --credential-dir |
render_page.py | 從模板產生 index.html | --output-dir --template --metadata |
manage_registry.py | 註冊表 CRUD（新增/刪除/列出/取得/遷移） | <subcommand> --share-folder |
partial_update.py | 重新渲染 + 重新上傳一個已分享的資料夾（從註冊表解析 key，轉發密碼） | <output_folder> [--key] |
font_name.py | 列印 TTF 的內部字型家族名稱（用於 ASS Fontname） | <font.ttf> |
transcribe.py | Deepgram 轉錄 → SRT + VTT | <video> --credential-dir [--language] |
gemini_analyze.py | Gemini 引擎：音訊轉錄或影片分析 + 螢幕截圖 | <video> --mode audio|video --output-dir --credential-dir [--key] |
burn_subtitles.py | 將字幕燒錄到影片中 | <video> <srt> [--font --fontsize ...] |
share_server.py | 用於隧道分享的本地 HTTP 伺服器 | <share_root> [--port] |
工作流程
步驟 0：解析參數與偵測模式
指令：
/video→ 互動模式（步驟 1-5）/video process <path>→ 互動模式，針對特定檔案/video share→ 靜默模式：處理最新的 + 分享/video share <path>→ 靜默模式：處理特定檔案 + 分享/video share <path> "context"→ 靜默模式，附帶供中繼資料使用的額外上下文/video start→ 啟動分享伺服器 + 隧道/video stop→ 停止分享/video status→ 列出已分享的影片/video copy <key_or_name>→ 複製連結 + 密碼到剪貼簿/video remove <key_or_name>→ 從註冊表中移除
分享指令（直接處理，不執行處理程序）
分享註冊表： <share_folder>/.share_registry.json——由 manage_registry.py 管理。
start 指令：
- 讀取偏好設定 →
share_folder。如果未設定，詢問。 - 檢查
pgrep -f share_server.py。如果正在執行，顯示狀態。 - 啟動伺服器：
python3 "<scripts>/share_server.py" "<share_folder>" --port 8080 & - 啟動隧道：
ssh -p 443 -R0:localhost:<port> -o StrictHostKeyChecking=no a.pinggy.io 2>&1 & - 解析隧道 URL。顯示：「伺服器正在執行於 <base_url>」
- 列出現有影片及其完整 URL（
<base_url>/v/<key>）。
stop 指令：
pkill -f share_server.py; pkill -f "ssh.*pinggy"; pkill -f "ngrok http"
status 指令：
- 執行
python3 "<scripts>/manage_registry.py" list --share-folder "<share_folder>" - 檢查
pgrep -f share_server.py以取得隧道狀態。 - 顯示表格：key、標題、S3 URL、隧道 URL、密碼、建立時間。
copy 指令：
- 執行
python3 "<scripts>/manage_registry.py" get --share-folder "<share_folder>" --key "<query>" - 格式化：
<title>\n<url>\nPasscode: <code>→pbcopy
remove 指令：
執行 python3 "<scripts>/manage_registry.py" remove --share-folder "<share_folder>" --key "<query>"
靜默模式（/video share）
一次確認，一次腳本執行，最少互動。
流程：
-
識別影片（參數路徑或
last_folder/ CWD 中最新的） -
建立輸出資料夾
<share_folder>/<video_name>/ -
產生密碼（隨機 6 位數或儲存的偏好設定）
-
顯示確認：
快速分享：demo.mov → 相同解析度 · 已壓縮（CRF 23）· AAC 128k → 轉錄 + 字幕（軌道） → 透過 S3 分享（永久連結） → 密碼：482910 繼續？選項：繼續（推薦） / 切換至互動模式
如果
mode是dev-video或transcript-cheap，不要執行process_and_share.py——改為遵循「Gemini 分析引擎」段落（靜默地，使用儲存的偏好設定），然後仍然上傳 + 註冊分享。 -
執行主要工作流程腳本。當
mode為dev-audio時傳遞--developer-analysis：python3 "<scripts>/process_and_share.py" "<video_path>" \ --output-dir "<output_folder>" \ --share-folder "<share_folder>" \ --credential-dir ~/.config/video-skill \ --resolution keep --crf 23 --preset medium --audio aac-128k \ --subtitles track \ --share s3 \ --passcode "<passcode>" \ [--developer-analysis] \ [--context "<user_context>"]預設
--resolution keep（壓縮，相同解析度）。僅在來源為 ≥1440p/4K 時使用--resolution 1080p，或在使用者明確想要未修改的檔案時使用keep-original處理。 -
監控 stdout 中的
METADATA_READY:——當腳本列印此標記時： a. 讀取它前面的TRANSCRIPT_PREVIEW:和METADATA_INFO:。 b. 從轉錄預覽產生標題、描述和 4-8 個章節。 c. 如果mode是dev-audio（開發者分析開啟）：從完整轉錄建立分析區塊以及分析 Markdown（讀取輸出目錄中的 SRT/VTT，而不是截斷的預覽）。請參閱**「metadata.json 參考」和「分析 Markdown」**段落以了解確切形狀和合約。比對頁面語言（RU / DE / EN）。 d. 根據 metadata.json 參考將metadata.json寫入輸出目錄。 e. 腳本偵測到 metadata.json 並自動繼續。 -
腳本結束。顯示結果，如下所述...（已截斷）