核心用法
whisnap 是 Whisnap macOS 应用的配套命令行工具，基于 OpenAI Whisper 模型实现本地音频/视频转录。用户需先在图形界面应用中启用 CLI 功能并下载模型，随后即可通过终端调用。
典型工作流：
- 基础转录：
whisnap audio.wav - 视频处理：
whisnap meeting.mp4 --json - 云端加速：
whisnap long-file.m4a --cloud - 脚本集成：
whisnap input.mp3 --json | jq '.text'
技术特性：
- 支持 9 种主流音视频格式（WAV/MP3/FLAC/M4A/OGG/MP4/MOV/MKV/WebM）
- 输出格式灵活：纯文本或结构化 JSON（含时间戳、分段、模型元数据）
- 本地优先：数据不离开设备，依赖
~/Library/Application Support/下的模型缓存 - 云端备选：
--cloud模式需应用内登录，适合低配置设备或长文件
显著优点
1. 无缝集成 macOS 生态：与桌面应用共享配置和模型，避免重复下载
2. 开发者友好：JSON 输出 + stderr 诊断信息，便于脚本化与自动化流水线
3. 隐私可控：本地模型运行无需网络，敏感内容（会议、医疗、法律）不上云
4. 格式覆盖广：原生支持容器格式，无需预先用 FFmpeg 提取音轨
潜在局限
- 平台锁定：仅支持 macOS，无 Linux/Windows 版本
- 前置依赖：必须安装 300MB+ 的 GUI 应用并手动启用 CLI，无法独立运行
- 模型管理受限：只能通过应用界面下载模型，CLI 仅支持 Whisper（不支持 Parakeet）
- 云端黑盒：
--cloud的后端实现未公开，存在数据出境与留存不确定性
适合人群
- 需要批量处理播客/访谈/会议录音的内容创作者
- 构建字幕生成流水线的视频制作团队
- 对隐私敏感、优先本地处理的法律/医疗/金融从业者
- 已使用 Whisnap 桌面版的 macOS 用户
常规风险
| 风险项 | 说明 | 缓解建议 |
|--------|------|---------|
| 供应链攻击 | 通过 GUI 应用分发的 CLI 二进制可能被篡改 | 校验应用签名（`codesign -dv /Applications/Whisnap.app`） |
| 模型文件完整性 | 下载的 GGML/GGUF 模型可能损坏导致错误结果 | 定期清理 `~/Library/Application Support/com.whisnap.desktop/models` 并重新下载 |
| 云端数据泄露 | `--cloud` 模式上传原始音频至未公开服务器 | 敏感文件禁用 `--cloud`，或使用网络监控工具验证流量目的地 |
| 路径遍历 | CLI 验证文件存在性但不限制路径，配合恶意文件名可能风险 | 始终使用绝对路径或清理后的变量输入 |
综合评估
whisnap 填补了 macOS 平台 Whisper 本地化转录的工具空白，将复杂的模型推理封装为单条命令。其设计权衡了易用性与可控性：对普通用户，GUI 兜底降低了门槛；对高级用户，JSON 输出和 stderr 分离支持自动化集成。主要扣分项在于强耦合的架构——无法脱离 300MB 应用独立运行，且云端模式透明度不足。建议优先用于本地离线场景，谨慎评估云端模式的合规性后再启用。