Communitygithub.com

sacredvoid/skillkit

处理视频/音频录制文件(Zoom、会议等),通过 Whisper 转录音频,并通过 ffmpeg 提取视觉帧。自动检测硬件(Apple Silicon、NVIDIA、AMD、CPU)并选择最佳转录模型。跨平台:macOS、Linux、Windows。

skillkit 是什么?

该 AI 技能用于自动处理视频和音频录制文件,生成文本转录和视觉帧截图,以便后续分析和摘要。它能够自动检测运行环境(包括操作系统、GPU 型号、显存和 RAM),并基于硬件配置推荐最佳的转录引擎和模型(如 faster-whisper 或 openai-whisper),从而在速度与准确性之间取得平衡。技能还负责安装所有依赖项(如 ffmpeg 和 PyTorch),并利用 ffprobe 获取文件时长以估算处理时间。在执行过程中,它会按分钟提取关键视觉帧,同时将长音频文件转写为带时间戳的 JSON 和纯文本格式。最终,通过结合视觉帧、聊天记录和转录文本,技能能够识别参与者、屏幕共享内容、关键决策和行动项,为开发者提供一个完整的会议分析工作流。该技能支持 macOS、Linux 和 Windows,适用于 Zoom、Teams 等平台。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

视频/音频处理器

将视频和音频录制处理为文本转录和视觉帧截图,供分析使用。自动检测硬件并选择最优的转录模型、设备及设置。

阶段 0:检测计算环境

每次调用开始时运行此步骤。它决定了后续的所有操作。

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'}

# 内存
尝试:
    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 检测
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']  # 统一内存
        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 使用 CUDA API
        info['dtype'] = 'float16'
except ImportError:
    pass

# ffmpeg 检测
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 GPU 可用faster-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: "我应该使用哪个转录模型?"
选项:
- [推荐模型] (推荐) - [基于其硬件的理由]
- large-v3 - 最佳准确性,需要 8+ GB VRAM 或大量 RAM
- medium - 高准确性,速度平衡
- small - 好准确性,处理较快
- base - 对大多数会议足够,最快

将所选模型存储为 WHISPER_MODEL,引擎存储为 WHISPER_ENGINE。

阶段 1:识别录音文件

查找文件。Zoom 录制通常遵循以下模式:

  • GMT{日期}-{时间}_Recording_{分辨率}.mp4(视频)
  • GMT{日期}-{时间}_Recording.m4a(仅音频)
  • GMT{日期}-{时间}_RecordingnewChat.txt(聊天记录)

检查所有三种文件。首先阅读聊天文件(它很小,能提供即时上下文)。

阶段 2:安装依赖项

根据平台检查并安装所需内容。

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

阶段 3:获取时长

使用 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 分钟/小时

阶段 4:提取视觉帧

每分钟提取一帧以获取视觉上下文。使用跨平台临时目录:

# 创建临时目录(跨平台)
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

使用“读取”工具查看每一帧。帧画面显示:

  • 屏幕共享(代码、幻灯片、UI)
  • 参与者姓名(每个视频块左下角)
  • 时间戳(如果屏幕共享中可见)

阶段 5:转录音频

运行转录引擎。根据 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'])} 个片段")

由于转录耗时较长,在后台运行。同时,可以查看提取的视觉帧。

阶段 6:综合整理

结合视觉帧、转录和聊天记录来构建理解:

  • 谁:通过视频中的名称标签和语音归属识别参与者
  • 什么:屏幕上显示了什么(演示、幻灯片、代码)
  • 说了什么:关键引述、决策、需求、反馈
  • 行动项:明确的承诺和后续跟进

模型参考

模型参数量速度准确性最佳用途
tiny39M非常快低快速扫描,检查音频是否可用
base74M快足够短/清晰会议的默认选择
small244M中等好含口音的一般会议
medium769M慢高重要会议、客户会议
large-v31.5B非常慢最佳关键录制、音频质量差的情况

提示

  • 始终在后台运行转录,同时查看视觉帧
  • 每次读取 8 帧(工具并行限制)
  • 标准 Whisper 在 CPU 和 MPS 上使用 FP32;faster-whisper 在 CUDA 上使用 CTranslate2 和 FP16
  • 对于非常长的录制(>1 小时),考虑先分割音频
  • Zoom 的聊天文件包含时间戳和共享链接,先阅读可快速获取上下文
  • 在 Windows 上,Python 中使用正斜杠或原始字符串表示文件路径

错误处理

错误原因修复
ffmpeg: command not foundffmpeg 未安装根据上方平台表安装
No module named 'whisper'Whisper 未安装pip3 install openai-whisper
No module named 'faster_whisper'faster-whisper 未安装pip3 install faster-whisper
CUDA out of memory模型过大,超出显存切换到较小的模型
RuntimeError: MPS backend旧版 macOS 的 MPS 问题更新 macOS,或通过设置 PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0 回退到 CPU
torch not foundPython 依赖缺失根据上方平台表安装 torch
转录乱码语言错误或音频质量差尝试指定 language="en" 或使用更大的模型
转录速度极慢在 CPU 上运行大模型切换到 base 或 small 模型

相关技能