Communitygithub.com

sacredvoid/skillkit

處理影片/音訊錄製檔(Zoom、會議等),使用 Whisper 進行語音轉錄,並用 ffmpeg 提取視覺幀。自動偵測硬體(Apple Silicon、NVIDIA、AMD、CPU)並選擇最佳的轉錄模型。跨平台支援:macOS、Linux、Windows。

skillkit 是什麼?

此 AI 代理技能專為處理影片與音訊錄製檔而設計,能自動偵測使用者硬體(包括 Apple Silicon、NVIDIA CUDA GPU、AMD ROCm 或僅有 CPU),並據此選擇最佳的轉錄引擎與模型。它整合了 Whisper 語音轉錄(支援 `openai-whisper` 和 GPU 加速的 `faster-whisper`)以及 ffmpeg 的幀提取功能,可從會議錄影中每分鐘提取一張畫面。整個流程從硬體偵測開始,接著是檔案識別、相依性安裝、時長估算、幀提取、背景轉錄,最後將視覺幀、文字稿與聊天記錄綜合分析,產出參與者、重點內容、決策與行動項目。支援 macOS、Linux、Windows 三大平台,並內建詳細的錯誤處理與時間估算矩陣,讓使用者能根據需求調整轉錄模型的準確度與速度。

相容平台~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/sacredvoid/skillkit/tree/HEAD/skills/video-audio-processor

在你喜歡的 AI 中提問

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

說明文件

影片/音訊處理器

將影片與音訊錄製檔處理為文字稿與視覺幀畫面,以便分析。自動偵測硬體並選擇最佳的轉錄模型、裝置與設定。

第零階段:偵測運算環境

每次調用時都先執行此階段,它會決定後續所有流程。

python3 -c "
import platform, shutil, subprocess, json

info = {'os': platform.system(), 'arch': platform.machine(), 'ram_gb': 0, 'gpu': 'none', 'vram_gb': 0, 'device': 'cpu', 'dtype': 'float32'}

# RAM
try:
    if platform.system() == 'Darwin':
        import os; info['ram_gb'] = round(os.sysconf('SC_PAGE_SIZE') * os.sysconf('SC_PHYS_PAGES') / (1024**3))
    elif platform.system() == 'Linux':
        with open('/proc/meminfo') as f:
            for line in f:
                if line.startswith('MemTotal'):
                    info['ram_gb'] = round(int(line.split()[1]) / (1024**2))
                    break
    else:
        import ctypes
        mem = ctypes.c_ulonglong(0)
        ctypes.windll.kernel32.GetPhysicallyInstalledMemory(ctypes.byref(mem))
        info['ram_gb'] = round(mem.value / (1024**2))
except: pass

# GPU detection
try:
    import torch
    if torch.cuda.is_available():
        info['gpu'] = torch.cuda.get_device_name(0)
        info['vram_gb'] = round(torch.cuda.get_device_properties(0).total_mem / (1024**3))
        info['device'] = 'cuda'
        info['dtype'] = 'float16'
    elif hasattr(torch.backends, 'mps') and torch.backends.mps.is_available():
        info['gpu'] = 'Apple Silicon (MPS)'
        info['vram_gb'] = info['ram_gb']  # unified memory
        info['device'] = 'mps'
        info['dtype'] = 'float16'
    elif hasattr(torch, 'hip') or 'AMD' in str(getattr(torch, '_C', '')):
        info['gpu'] = 'AMD (ROCm)'
        info['device'] = 'cuda'  # ROCm uses cuda API
        info['dtype'] = 'float16'
except ImportError:
    pass

# ffmpeg detection
info['ffmpeg'] = shutil.which('ffmpeg') is not None
info['ffprobe'] = shutil.which('ffprobe') is not None

print(json.dumps(info))
"

解析 JSON 輸出並內部儲存為 COMPUTE。向使用者顯示結果:

偵測到的硬體:

  • 作業系統:{os} ({arch})
  • 記憶體:{ram_gb} GB
  • GPU:{gpu} ({vram_gb} GB VRAM)
  • 運算裝置:{device}
  • ffmpeg:{已安裝/未安裝}

Whisper 引擎選擇

根據硬體選擇轉錄引擎:

條件引擎原因
有 CUDA GPUfaster-whisperGPU 加速的 CTranslate2,比標準 Whisper 快 4 倍
MPS(Apple Silicon)openai-whisper標準 Whisper,在可用時使用 MPS 加速
僅有 CPUopenai-whisper標準 Whisper 在 CPU 上執行,可靠的備援方案

模型選擇矩陣

根據硬體與錄製時長推薦模型:

條件推薦模型速度(1 小時錄音)準確度
CUDA >= 8 GB VRAMlarge-v3~5 分鐘最佳
CUDA 4-7 GB VRAMmedium~8 分鐘高
MPS(Apple Silicon,16+ GB)medium~15 分鐘高
MPS(Apple Silicon,8 GB)small~10 分鐘良好
CPU + RAM >= 16 GBsmall~30 分鐘良好
CPU + RAM < 16 GBbase~15 分鐘尚可

顯示推薦結果並讓使用者選擇:

AskUserQuestion: "應該使用哪個轉錄模型?"
Options:
- [推薦模型] (建議) - [根據他們硬體說明的理由]
- large-v3 - 最佳準確度,需要 8+ GB VRAM 或大量 RAM
- medium - 高準確度,速度均衡
- small - 良好準確度,處理更快
- base - 適合大多數會議,最快

將選擇的模型儲存為 WHISPER_MODEL,引擎儲存為 WHISPER_ENGINE。

第一階段:識別錄製檔

找到檔案。Zoom 錄製檔通常遵循以下模式:

  • GMT{日期}-{時間}_Recording_{解析度}.mp4(影片)
  • GMT{日期}-{時間}_Recording.m4a(僅音訊)
  • GMT{日期}-{時間}_RecordingnewChat.txt(聊天記錄)

檢查所有三個工件。先讀取聊天檔案(因為檔案小,能立即提供上下文)。

第二階段:安裝相依套件

根據平台檢查並安裝所需項目。

ffmpeg

# 檢查 ffmpeg 是否可用
ffmpeg -version 2>&1 | head -1
ffprobe -version 2>&1 | head -1

如果 ffmpeg 缺失,根據平台安裝:

平台安裝指令
macOS(Homebrew)brew install ffmpeg
macOS(無 Homebrew)引導使用者先安裝 Homebrew,再安裝 ffmpeg
Ubuntu/Debiansudo apt update && sudo apt install -y ffmpeg
Fedora/RHELsudo dnf install -y ffmpeg
Arch Linuxsudo pacman -S ffmpeg
Windows(winget)winget install Gyan.FFmpeg
Windows(choco)choco install ffmpeg
Windows(scoop)scoop install ffmpeg

Python + Whisper

python3 -c "import torch; print(torch.__version__)" 2>&1

如果 torch 缺失,根據平台安裝:

平台安裝指令
macOS(MPS)pip3 install torch torchvision torchaudio
Linux(CUDA)pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
Linux(ROCm)pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.0
Linux/Windows(CPU)pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
Windows(CUDA)pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

然後安裝轉錄引擎:

# 對於 CUDA 系統(faster-whisper 搭配 CTranslate2 加速)
pip3 install faster-whisper

# 對於 MPS / CPU 系統(標準 OpenAI Whisper)
pip3 install openai-whisper

第三階段:取得時長

使用 ffprobe(跨平台)取得檔案時長:

ffprobe -v quiet -show_entries format=duration -of csv=p=0 "/path/to/file"

回傳以秒為單位的時長。轉換為人類可讀格式並顯示給使用者。根據所選模型和硬體估算轉錄時間。

顯示處理計畫:

處理計畫:

  • 檔案:{filename}({duration})
  • 引擎:{WHISPER_ENGINE},使用 {WHISPER_MODEL} 模型,在 {device} 上執行
  • 預估轉錄時間:{estimate}
  • 幀提取:每分鐘 1 幀(共 {frame_count} 幀)

在開始前是否需要調整任何項目?

時間估算

裝置basesmallmediumlarge-v3
CUDA(RTX 3060+)~1 分鐘/小時~2 分鐘/小時~4 分鐘/小時~5 分鐘/小時
CUDA(faster-whisper)~30 秒/小時~1 分鐘/小時~2 分鐘/小時~3 分鐘/小時
MPS(M1/M2/M3/M4)~3 分鐘/小時~6 分鐘/小時~15 分鐘/小時~25 分鐘/小時
CPU(16GB+ RAM)~8 分鐘/小時~15 分鐘/小時~30 分鐘/小時~60 分鐘/小時

第四階段:提取視覺幀

每分鐘提取一幀以獲取視覺上下文。使用跨平台的暫存目錄:

# 建立暫存目錄(跨平台)
python3 -c "import tempfile, os; d = os.path.join(tempfile.gettempdir(), 'av-frames'); os.makedirs(d, exist_ok=True); print(d)"

然後提取幀:

ffmpeg -i "/path/to/video.mp4" \
  -vf "fps=1/60,scale=1280:-1" -q:v 3 {TEMP_DIR}/frame_%03d.jpg

對每個幀使用讀取工具進行檢視。幀會顯示:

  • 螢幕分享(程式碼、簡報、使用者介面)
  • 與會者姓名(每個影片區塊的左下方)
  • 時間戳記(如果螢幕分享中有顯示)

第五階段:轉錄音訊

執行轉錄引擎。根據 WHISPER_ENGINE 選擇正確的程式碼:

faster-whisper(CUDA 系統)

from faster_whisper import WhisperModel
import json

model = WhisperModel("{WHISPER_MODEL}", device="cuda", compute_type="float16")
segments, info = model.transcribe("/path/to/audio", beam_size=5, language="en")

results = []
for segment in segments:
    results.append({
        "start": segment.start,
        "end": segment.end,
        "text": segment.text.strip()
    })

# 儲存帶時間戳的文字稿
with open("{TEMP_DIR}/transcript.json", "w") as f:
    json.dump({"language": info.language, "segments": results}, f, indent=2)

with open("{TEMP_DIR}/transcript.txt", "w") as f:
    for seg in results:
        start = int(seg["start"])
        mins, secs = divmod(start, 60)
        f.write(f"[{mins:02d}:{secs:02d}] {seg['text']}\n")

print(f"已轉錄 {len(results)} 個片段")

openai-whisper(MPS / CPU 系統)

import whisper, json

model = whisper.load_model("{WHISPER_MODEL}")
result = model.transcribe("/path/to/audio", verbose=False)

# 儲存帶時間戳的文字稿
with open("{TEMP_DIR}/transcript.json", "w") as f:
    json.dump(result, f, indent=2)

with open("{TEMP_DIR}/transcript.txt", "w") as f:
    for seg in result["segments"]:
        start = int(seg["start"])
        mins, secs = divmod(start, 60)
        f.write(f"[{mins:02d}:{secs:02d}] {seg['text'].strip()}\n")

print(f"已轉錄 {len(result['segments'])} 個片段")

由於轉錄需要較長時間,請在背景執行。同時檢視已提取的視覺幀。

第六階段:綜合分析

結合視覺幀 + 文字稿 + 聊天記錄來建立理解:

  • 誰:從影片姓名標籤和語音歸因識別與會者
  • 什麼:螢幕上顯示的內容(展示、簡報、程式碼)
  • 說了什麼:關鍵引述、決策、需求、回饋
  • 行動項目:明確的承諾與後續事項

模型參考

模型參數量速度準確度最佳用途
tiny39M非常快低快速掃描、檢查音訊是否可用
base74M快尚可簡短/清晰的會議預設選項
small244M中良好一般會議(含口音)
medium769M慢高重要會議、客戶對接
large-v31.5B非常慢最佳關鍵錄音、音訊品質差的情況

提示

  • 務必在背景進行轉錄,同時檢視視覺幀
  • 以 8 幀為一批進行讀取(工具並行限制)
  • 標準 Whisper 在 CPU 和 MPS 上使用 FP32;faster-whisper 在 CUDA 上使用 CTranslate2 與 FP16
  • 對於非常長的錄音(>1 小時),建議先分割音訊
  • Zoom 的聊天記錄檔案包含時間戳和共用連結,先讀取可快速獲取上下文
  • 在 Windows 上,Python 檔案路徑請使用正斜線或原始字串

錯誤處理

錯誤原因修正方式
ffmpeg: command not found未安裝 ffmpeg根據上方平台表格安裝
No module named 'whisper'未安裝 Whisperpip3 install openai-whisper
No module named 'faster_whisper'未安裝 faster-whisperpip3 install faster-whisper
CUDA out of memory模型過大,VRAM 不足切換至較小模型
RuntimeError: MPS backend較舊 macOS 上的 MPS 問題更新 macOS,或使用 PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0 改用 CPU
torch not foundPython 相依套件缺失根據上方平台表格安裝 torch
文字稿混亂語言錯誤或音訊品質差嘗試指定 language="en" 或使用更大的模型
轉錄非常慢在 CPU 上執行大型模型切換至 base 或 small 模型

相關技能