Skill: mapleshadow/faster-whisper-zh (version 1.0.5)

--- name: faster-whisper-zh description: 使用 faster-whisper 的本地语音转文字工具。支持 GPU 加速的高性能转录，包含词级时间戳和蒸馏模型。当用户要求"转录音频"、"语音转文字"或"whisper"时使用此技能。 metadata: { "openclaw": { "requires": { "bins": ["ffmpeg", "python3"], "pip": ["faster-whisper", "torch"], }, }, } --- # Faster-Whisper 中文版 基于 faster-whisper 的高性能本地语音转文字工具。 ## 安装设置 ### 1. 运行安装脚本 执行安装脚本以创建虚拟环境并安装依赖包。脚本会自动检测 NVIDIA GPU 以启用 CUDA 加速。 ```bash ./setup.sh ``` 系统要求： - Python 3.10 或更高版本 - ffmpeg（系统已安装） ## 使用方法 使用转换脚本转换音频文件。 ## 适用场景 - 会议录音转文字纪要 - 语音笔记转文字记录 - 音频文件内容提取 - 访谈录音整理 - 培训录音转文字材料 - 视频字幕生成 - 播客内容转录 - 语音转文字 - 音频转文字 ### 基本转录 ```bash export HF_HOME=/config/huggingface export HF_ENDPOINT=https://hf-mirror.com .venv/bin/python3 scripts/transcribe.py ``` ### 高级选项 - **指定模型**: `.venv/bin/python3 scripts/transcribe.py audio.mp3 --model large-v3-turbo` - **词级时间戳**: `.venv/bin/python3 scripts/transcribe.py audio.mp3 --word-timestamps` - **JSON 输出**: `.venv/bin/python3 scripts/transcribe.py audio.mp3 --json` - **语音活动检测（静音去除）**: `.venv/bin/python3 scripts/transcribe.py audio.mp3 --vad` - **指定语言**: `.venv/bin/python3 scripts/transcribe.py audio.mp3 --language zh` - **GPU 加速**: `.venv/bin/python3 scripts/transcribe.py audio.mp3 --device cuda` - **CPU 优化**: `.venv/bin/python3 scripts/transcribe.py audio.mp3 --device cpu --compute-type int8` ### 完整命令示例 ```bash # 中文转录，使用 GPU 加速 .venv/bin/python3 scripts/transcribe.py 会议录音.mp3 --language zh --device cuda --compute-type float16 # 英文转录，包含词级时间戳 .venv/bin/python3 scripts/transcribe.py interview.wav --language en --word-timestamps --json # 快速 CPU 转录，优化性能 .venv/bin/python3 scripts/transcribe.py audio.m4a --device cpu --compute-type int8 --model distil-large-v3 # 批量处理脚本 .venv/bin/python3 scripts/batch_transcribe.sh /path/to/audio/files/ ``` ## 可用模型 - `large-v3-turbo` (默认):推荐用于多语言或最高准确度任务 - `large-v3`: 原始大模型，准确度最高 - `distil-large-v3`: 速度和准确性的最佳平衡 - `medium`: 中等大小，平衡性能 - `small`: 小型模型，速度快 - `base`: 基础模型，资源需求最低 - `tiny`: 微型模型，速度最快 - `medium.en`, `small.en`: 仅支持英语的更快版本 ## 模型选择指南 | 模型 | 大小 | 推荐用途 | 硬件要求 | |------|------|----------|----------| | `large-v3-turbo` | 1.5GB | 专业级转录 | 高性能 GPU | | `medium` | 1.5GB | 平衡性能 | 普通配置 | | `distil-large-v3` | 756MB | 通用中文转录 | 中等配置 | | `small` | 500MB | 快速转录 | 低配置 | | `tiny` | 150MB | 实时转录 | 最低配置 | ## 性能优化 ### GPU 加速配置 ```bash # NVIDIA GPU (CUDA) .venv/bin/python3 scripts/transcribe.py audio.mp3 --device cuda --compute-type float16 # Apple Silicon (macOS) .venv/bin/python3 scripts/transcribe.py audio.mp3 --device mps ``` ### CPU 优化配置 ```bash # 高性能 CPU .venv/bin/python3 scripts/transcribe.py audio.mp3 --device cpu --compute-type int8 --beam-size 3 # 低资源环境 .venv/bin/python3 scripts/transcribe.py audio.mp3 --device cpu --compute-type int8 --model small --beam-size 1 ``` ## 故障排除 ### 常见问题 - **未检测到 GPU**: 确保 NVIDIA 驱动和 CUDA 正确安装。CPU 转录速度会显著变慢。 - **内存不足错误**: 使用更小的模型（如 `small` 或 `base`）或使用 `--compute-type int8` - **模型下载失败**: 设置环境变量 `HF_ENDPOINT=https://hf-mirror.com` 使用国内镜像 - **音频格式不支持**: 使用 ffmpeg 转换音频格式：`ffmpeg -i input.m4a output.wav` ### 错误解决方案 1. **CUDA 不可用** ```bash # 检查 CUDA 安装 nvidia-smi # 如果未安装，重新运行安装脚本 ./setup.sh ``` 2. **ffmpeg 未找到** ```bash # Ubuntu/Debian sudo apt install ffmpeg # macOS brew install ffmpeg # CentOS/RHEL sudo yum install ffmpeg ``` 3. **Python 版本过低** ```bash # 检查 Python 版本 python3 --version # 需要 Python 3.10+ ``` ## 环境变量配置 ```bash # 设置 HuggingFace 缓存目录（避免重复下载） export HF_HOME=/config/huggingface # 使用国内镜像加速下载 export HF_ENDPOINT=https://hf-mirror.com # 设置 PyTorch CUDA 版本（如有需要） export CUDA_VISIBLE_DEVICES=0 ``` ## 批量处理 创建 `batch_transcribe.sh` 脚本进行批量处理： ```bash #!/bin/bash # 批量转录脚本 for audio_file in *.mp3 *.wav *.m4a; do if [ -f "$audio_file" ]; then echo "处理: $audio_file" ./scripts/transcribe.py "$audio_file" --output "${audio_file%.*}.txt" fi done ``` ## 输出格式 ### 纯文本输出 ``` [00:00:00.000 --> 00:00:05.000] 欢迎使用 faster-whisper 语音转文字工具。 [00:00:05.000 --> 00:00:10.000] 这是一个高性能的本地转录解决方案。 ``` ### JSON 输出 ```json { "text": "完整的转录文本...", "segments": [ { "start": 0.0, "end": 5.0, "text": "欢迎使用 faster-whisper 语音转文字工具。", "words": [ {"word": "欢迎", "start": 0.0, "end": 0.5}, {"word": "使用", "start": 0.5, "end": 1.0} ] } ] } ``` ## 更新日志 ### v1.0.5 (2026-04-16) - 重新调整命令 - 原需激活虚拟环境更改为直接执行虚拟环境的python3 ## 技术支持 如有问题，请： 1. 查看本文档的故障排除部分 2. 检查系统要求是否满足 3. 确保网络连接正常（模型下载需要网络） 4. 查看脚本错误信息进行调试 --- **提示**: 首次运行会下载所选模型（large-v3-turbo 约 1.5GB）。请确保有足够的磁盘空间和稳定的网络连接。

path: config_example.sh
content: #!/bin/bash
# faster-whisper 配置示例
# 复制此文件为 config.sh 并根据需要修改

# ========================================
# 环境变量配置
# ========================================

# HuggingFace 缓存目录（避免重复下载模型）
export HF_HOME=/config/huggingface

# 使用国内镜像加速下载（中国用户推荐）
export HF_ENDPOINT=https://hf-mirror.com

# PyTorch CUDA 设置（如有多个 GPU）
# export CUDA_VISIBLE_DEVICES=0  # 只使用第一个 GPU
# export CUDA_VISIBLE_DEVICES=0,1  # 使用前两个 GPU

# ========================================
# 默认转录参数
# ========================================

# 模型选择（根据硬件选择）
# 选项: tiny, base, small, medium, large-v3, large-v3-turbo, distil-large-v3
DEFAULT_MODEL="large-v3-turbo"

# 默认语言
# 选项: zh (中文), en (英文), ja (日文), ko (韩文), auto (自动检测)
DEFAULT_LANGUAGE="zh"

# 计算设备
# 选项: auto (自动检测), cpu, cuda
DEFAULT_DEVICE="cpu"

# 计算类型
# 选项: auto, int8 (CPU优化), float16 (GPU优化), float32 (高精度)
DEFAULT_COMPUTE_TYPE="auto"

# 束搜索大小（影响准确性和速度）
# 范围: 1-10，值越高越准确但越慢
DEFAULT_BEAM_SIZE=5

# ========================================
# 硬件特定配置
# ========================================

# 检测硬件并设置优化配置
detect_hardware() {
    echo "检测硬件配置..."
    
    # 检查 CUDA
    if command -v nvidia-smi &> /dev/null; then
        GPU_INFO=$(nvidia-smi --query-gpu=name,memory.total --format=csv,noheader 2>/dev/null | head -1)
        if [ -n "$GPU_INFO" ]; then
            echo "✓ 检测到 NVIDIA GPU: $GPU_INFO"
            DEFAULT_DEVICE="cuda"
            DEFAULT_COMPUTE_TYPE="float16"
            DEFAULT_MODEL="large-v3-turbo"
            return
        fi
    fi
    
    # 检查 Apple Silicon
    if [ "$(uname -s)" = "Darwin" ] && [ "$(uname -m)" = "arm64" ]; then
        echo "✓ 检测到 Apple Silicon"
        DEFAULT_DEVICE="cpu"
        DEFAULT_COMPUTE_TYPE="int8"
        DEFAULT_MODEL="large-v3-turbo"
        return
    fi
    
    # 检查系统内存
    if [ "$(uname -s)" = "Linux" ]; then
        MEM_GB=$(free -g | awk '/^Mem:/ {print $2}')
        if [ "$MEM_GB" -ge 16 ]; then
            echo "✓ 检测到大内存系统: ${MEM_GB}GB"
            DEFAULT_MODEL="large-v3-turbo"
        else
            echo "⚠️  检测到有限内存: ${MEM_GB}GB"
            DEFAULT_MODEL="small"
        fi
    fi
    
    echo "ℹ️  使用 CPU 模式配置"
    DEFAULT_DEVICE="cpu"
    DEFAULT_COMPUTE_TYPE="int8"
}

# ========================================
# 使用场景配置
# ========================================

# 会议录音配置（中文，高准确度）
conference_config() {
    DEFAULT_MODEL="large-v3-turbo"
    DEFAULT_LANGUAGE="zh"
    DEFAULT_BEAM_SIZE=5
    echo "已应用会议录音配置"
}

# 实时转录配置（快速，低延迟）
realtime_config() {
    DEFAULT_MODEL="small"
    DEFAULT_BEAM_SIZE=3
    echo "已应用实时转录配置"
}

# 专业转录配置（最高准确度）
professional_config() {
    DEFAULT_MODEL="large-v3-turbo"
    DEFAULT_BEAM_SIZE=10
    echo "已应用专业转录配置"
}

# 多语言配置
multilingual_config() {
    DEFAULT_MODEL="large-v3-turbo"
    DEFAULT_LANGUAGE="auto"
    echo "已应用多语言配置"
}

# ========================================
# 实用函数
# ========================================

# 显示当前配置
show_config() {
    echo "当前配置:"
    echo "  模型: $DEFAULT_MODEL"
    echo "  语言: $DEFAULT_LANGUAGE"
    echo "  设备: $DEFAULT_DEVICE"
    echo "  计算类型: $DEFAULT_COMPUTE_TYPE"
    echo "  束搜索大小: $DEFAULT_BEAM_SIZE"
}

# 生成转录命令
generate_command() {
    local audio_file="$1"
    local output_file="$2"
    
    local cmd=".venv/bin/python3 scripts/transcribe.py \"$audio_file\""
    cmd="$cmd --model \"$DEFAULT_MODEL\""
    cmd="$cmd --language \"$DEFAULT_LANGUAGE\""
    cmd="$cmd --device \"$DEFAULT_DEVICE\""
    cmd="$cmd --compute-type \"$DEFAULT_COMPUTE_TYPE\""
    cmd="$cmd --beam-size \"$DEFAULT_BEAM_SIZE\""

    if [ -n "$output_file" ]; then
        cmd="$cmd --output \"$output_file\""
    fi

    echo "$cmd"
}

# ========================================
# 主程序
# ========================================

# 自动检测硬件（取消注释以启用）
# detect_hardware

# 显示欢迎信息
echo "========================================"
echo "faster-whisper 配置工具"
echo "========================================"
echo ""
echo "使用方法:"
echo "1. 复制此文件为 config.sh"
echo "2. 修改配置参数"
echo "3. 在转录前运行: source config.sh"
echo ""
echo "预设配置:"
echo "  source config.sh && conference_config"
echo "  source config.sh && realtime_config"
echo "  source config.sh && professional_config"
echo ""
show_config
echo "========================================"

path: README.md
content: # Faster-Whisper 中文版

基于 faster-whisper 的高性能本地语音转文字工具的中文优化版本。音频转文字、语音转文字等需求，均可通过该技能实现。

## 版本特点

### 🎯 中文优化
- 完整的中文文档和说明
- 默认语言设置为中文（zh）
- 针对中文语音的优化配置
- 中文错误提示和帮助信息

### 🚀 性能增强
- 自动硬件检测和优化配置
- 国内镜像加速（HF_MIRROR）
- GPU/CPU 自动切换
- 智能模型选择建议

### 📚 完整文档
- 详细的使用指南
- 故障排除手册
- 性能优化建议
- 批量处理脚本

### 🔧 实用工具
- 批量转录脚本
- 配置文件示例
- 硬件检测功能
- 多种使用场景预设

## 文件结构

```
faster-whisper-zh/
├── SKILL.md                    # 技能主文档（中文）
├── setup.sh                    # 安装脚本（中文）
├── requirements.txt            # 依赖包列表
├── _meta.json                  # 元数据
├── config_example.sh           # 配置示例
├── README.md                   # 本文件
└── scripts/
    ├── transcribe.py           # 转录脚本（中文优化）
    └── batch_transcribe.sh     # 批量转录脚本
```

## 快速开始

### 1. 安装
```bash
# 进入技能目录
cd faster-whisper-zh

# 运行安装脚本
./setup.sh
```

### 2. 基本使用
```bash
# 设置环境变量（国内用户推荐）
export HF_HOME=/config/huggingface
export HF_ENDPOINT=https://hf-mirror.com

# 转录音频文件（使用的是虚拟环境内的python3，因此不需要刻意激活虚拟环境）
.venv/bin/python3 scripts/transcribe.py --model large-v3-turbo --language zh 音频文件.mp3
```

### 3. 批量处理
```bash
# 设置环境变量（国内用户推荐）
export HF_HOME=/config/huggingface
export HF_ENDPOINT=https://hf-mirror.com

# 处理目录中的所有音频文件
.venv/bin/python3 scripts/batch_transcribe.sh ./audio_files

# 使用 GPU 加速批量处理
.venv/bin/python3 scripts/batch_transcribe.sh --device cuda --model large-v3-turbo ./recordings
```

## 配置说明

### 环境变量
```bash
# 设置 HuggingFace 缓存目录
export HF_HOME=/config/huggingface

# 使用国内镜像加速
export HF_ENDPOINT=https://hf-mirror.com

# 指定 GPU 设备（多 GPU 环境）
export CUDA_VISIBLE_DEVICES=0
```

### 转录参数
```bash
# 模型选择
--model large-v3-turbo      # （默认）最高准确度，支持多语言
--model distil-large-v3      #平衡速度与准确性
--model small                # 快速转录，资源需求低

# 语言设置
--language zh                # 中文（默认）
--language en                # 英文
--language auto              # 自动检测

# 设备配置
--device auto                # 自动检测（推荐）
--device cuda                # 强制使用 GPU
--device cpu                 # 强制使用 CPU

# 计算类型
--compute-type int8          # CPU 优化（4倍加速）
--compute-type float16       # GPU 优化
--compute-type float32       # 最高精度
```

## 使用场景

### 会议录音转录
```bash
export HF_HOME=/config/huggingface
export HF_ENDPOINT=https://hf-mirror.com
.venv/bin/python3 scripts/transcribe.py 会议录音.mp3 \
  --model large-v3-turbo \
  --language zh \
  --word-timestamps \
  --output 会议纪要.txt
```

### 访谈录音整理
```bash
export HF_HOME=/config/huggingface
export HF_ENDPOINT=https://hf-mirror.com
.venv/bin/python3 scripts/transcribe.py 访谈.wav \
  --model large-v3-turbo \
  --language zh \
  --json \
  --output 访谈记录.json
```

### 实时语音转写
```bash
export HF_HOME=/config/huggingface
export HF_ENDPOINT=https://hf-mirror.com
.venv/bin/python3 scripts/transcribe.py 实时音频.m4a \
  --model small \
  --device cpu \
  --compute-type int8 \
  --beam-size 3
```

### 批量处理会议录音
```bash
export HF_HOME=/config/huggingface
export HF_ENDPOINT=https://hf-mirror.com
.venv/bin/python3 scripts/batch_transcribe.sh ./会议录音 \
  --model large-v3-turbo \
  --language zh \
  --output ./转录结果
```

## 性能建议

### 硬件配置推荐
| 硬件配置 | 推荐模型 | 预期速度 |
|---------|---------|---------|
| 高端 GPU (RTX 4090) | large-v3-turbo | 20-30x 实时 |
| 中端 GPU (RTX 3060) | distil-large-v3 | 10-15x 实时 |
| Apple Silicon M2 | distil-large-v3 | 3-5x 实时 |
| 高性能 CPU (i7/i9) | small/distil-large-v3 | 1-3x 实时 |
| 普通 CPU | small/tiny | 0.5-1x 实时 |

### 内存要求
- `tiny`: 约 150MB
- `small`: 约 500MB  
- `distil-large-v3`: 约 756MB
- `large-v3-turbo`: 约 1.5GB

## 故障排除

### 常见问题

1. **CUDA 不可用**
   ```bash
   # 检查 CUDA 安装
   nvidia-smi
   
   # 重新运行安装脚本
   ./setup.sh
   ```

2. **内存不足**
   ```bash
   # 使用更小的模型
   --model small --compute-type int8
   
   # 减少束搜索大小
   --beam-size 3
   ```

3. **下载速度慢**
   ```bash
   # 设置国内镜像
   export HF_ENDPOINT=https://hf-mirror.com
   export HF_HOME=/config/huggingface
   ```

4. **音频格式不支持**
   ```bash
   # 使用 ffmpeg 转换格式
   ffmpeg -i input.m4a output.wav
   ```

### 错误代码
- `ERROR_CUDA_UNAVAILABLE`: CUDA 不可用，切换到 CPU 模式
- `ERROR_MODEL_DOWNLOAD`: 模型下载失败，检查网络或使用镜像
- `ERROR_AUDIO_FORMAT`: 音频格式不支持，转换为 wav/mp3 格式
- `ERROR_MEMORY`: 内存不足，使用更小的模型或 int8 量化

## 更新计划

### 近期更新
- [ ] 添加实时麦克风输入支持
- [ ] 添加 Web 界面
- [ ] 支持更多音频格式
- [ ] 添加语音翻译功能

### 长期规划
- [ ] 集成到 OpenClaw 技能市场
- [ ] 添加模型微调工具
- [ ] 支持方言识别
- [ ] 添加语音合成功能

## 贡献指南

欢迎贡献代码、文档或提出建议：

1. Fork 本仓库
2. 创建功能分支
3. 提交更改
4. 创建 Pull Request

## 许可证

本项目基于 MIT 许可证开源。

## 致谢

- 感谢 [faster-whisper](https://github.com/guillaumekln/faster-whisper) 项目
- 感谢 [OpenAI Whisper](https://github.com/openai/whisper) 团队
- 感谢所有贡献者和用户

---

**提示**: 首次使用需要下载模型文件，请确保有足够的磁盘空间（约 1-2GB）和稳定的网络连接。

path: requirements.txt
content: # 核心依赖 — PyTorch 由安装脚本单独安装（如果检测到 GPU 则安装 CUDA 版本）
faster-whisper>=1.2.0

# 注意：PyTorch 将在 setup.sh 中根据硬件环境自动安装：
# - NVIDIA GPU: 安装 CUDA 版本的 PyTorch
# - macOS: 安装标准版 PyTorch
# - 其他 CPU: 安装 CPU 版 PyTorch

path: setup.sh
content: #!/usr/bin/env bash
# faster-whisper 技能安装脚本
# 创建虚拟环境并安装依赖包（支持 GPU 加速）

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
VENV_DIR="$SCRIPT_DIR/.venv"

echo "🎙️ 正在设置 faster-whisper 技能..."

# 检测操作系统
OS="$(uname -s)"
ARCH="$(uname -m)"

case "$OS" in
    Linux*)  OS_TYPE="linux" ;;
    Darwin*) OS_TYPE="macos" ;;
    *)       OS_TYPE="unknown" ;;
esac

echo "✓ 平台: $OS_TYPE ($ARCH)"

# 检查 Python 3.10+
if ! command -v python3 &> /dev/null; then
    echo "❌ 未找到 Python 3。请安装 Python 3.10 或更高版本。"
    exit 1
fi

PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
PYTHON_MAJOR=$(echo "$PYTHON_VERSION" | cut -d. -f1)
PYTHON_MINOR=$(echo "$PYTHON_VERSION" | cut -d. -f2)

if [ "$PYTHON_MAJOR" -lt 3 ] || ([ "$PYTHON_MAJOR" -eq 3 ] && [ "$PYTHON_MINOR" -lt 10 ]); then
    echo "❌ 需要 Python 3.10+ (当前版本: $PYTHON_VERSION)"
    exit 1
fi

echo "✓ Python $PYTHON_VERSION"

# 检查 ffmpeg（必需）
if ! command -v ffmpeg &> /dev/null; then
    echo "❌ 未找到 ffmpeg（音频处理必需）"
    echo ""
    echo "安装 ffmpeg:"
    if [ "$OS_TYPE" = "macos" ]; then
        echo "   brew install ffmpeg"
    else
        echo "   Ubuntu/Debian: sudo apt install ffmpeg"
        echo "   Fedora: sudo dnf install ffmpeg"
        echo "   Arch: sudo pacman -S ffmpeg"
        echo "   CentOS/RHEL: sudo yum install ffmpeg"
    fi
    echo ""
    exit 1
fi

echo "✓ 找到 ffmpeg"

# 检测 GPU/加速可用性
HAS_CUDA=false
HAS_APPLE_SILICON=false
GPU_NAME=""
NVIDIA_SMI=""

if [ "$OS_TYPE" = "linux" ]; then
    # 检查 NVIDIA GPU (Linux/WSL)
    # 首先在 PATH 中查找 nvidia-smi
    if command -v nvidia-smi &> /dev/null; then
        NVIDIA_SMI="nvidia-smi"
    else
        # WSL2: nvidia-smi 在 /usr/lib/wsl/lib/ 中（默认不在 PATH）
        # 检查是否在 WSL2 中并在相应目录查找
        if grep -qi microsoft /proc/version 2>/dev/null; then
            # 在 WSL2 中 - 在 WSL 库目录中搜索 nvidia-smi
            for wsl_smi in /usr/lib/wsl/lib/nvidia-smi /usr/lib/wsl/drivers/*/nvidia-smi; do
                if [ -f "$wsl_smi" ]; then
                    NVIDIA_SMI="$wsl_smi"
                    echo "✓ 检测到 WSL2"
                    break
                fi
            done
        fi
    fi
    
    # 如果找到 nvidia-smi，获取 GPU 信息
    if [ -n "$NVIDIA_SMI" ]; then
        GPU_NAME=$($NVIDIA_SMI --query-gpu=name --format=csv,noheader 2>/dev/null | head -1)
        if [ -n "$GPU_NAME" ]; then
            HAS_CUDA=true
        fi
    fi
elif [ "$OS_TYPE" = "macos" ]; then
    # 检查 Apple Silicon
    if [ "$ARCH" = "arm64" ]; then
        HAS_APPLE_SILICON=true
        GPU_NAME="Apple Silicon"
        echo "✓ 检测到 Apple Silicon"
    fi
fi

if [ "$HAS_CUDA" = true ]; then
    echo "✓ 检测到 GPU: $GPU_NAME"
fi

# 创建虚拟环境
if [ -d "$VENV_DIR" ]; then
    echo "✓ 虚拟环境已存在"
else
    echo "正在创建虚拟环境..."
    if command -v uv &> /dev/null; then
        uv venv "$VENV_DIR" --python python3
    else
        python3 -m venv "$VENV_DIR"
    fi
    echo "✓ 虚拟环境创建完成"
fi

# 安装依赖包
echo "正在安装 faster-whisper..."
if command -v uv &> /dev/null; then
    uv pip install --python "$VENV_DIR/bin/python" -r "$SCRIPT_DIR/requirements.txt"
else
    "$VENV_DIR/bin/pip" install --upgrade pip
    "$VENV_DIR/bin/pip" install -r "$SCRIPT_DIR/requirements.txt"
fi

# 根据平台安装 PyTorch
if [ "$HAS_CUDA" = true ]; then
    echo ""
    echo "🚀 正在安装支持 CUDA 的 PyTorch..."
    echo "   这将使您的 GPU 转录速度提升约 10-20 倍。"
    echo ""
    if command -v uv &> /dev/null; then
        uv pip install --python "$VENV_DIR/bin/python" torch --index-url https://download.pytorch.org/whl/cu121
    else
        "$VENV_DIR/bin/pip" install torch --index-url https://download.pytorch.org/whl/cu121
    fi
    echo "✓ PyTorch with CUDA 安装完成"
elif [ "$OS_TYPE" = "macos" ]; then
    echo ""
    echo "🍎 正在安装 macOS 版 PyTorch..."
    if command -v uv &> /dev/null; then
        uv pip install --python "$VENV_DIR/bin/python" torch
    else
        "$VENV_DIR/bin/pip" install torch
    fi
    echo "✓ PyTorch 安装完成"
    if [ "$HAS_APPLE_SILICON" = true ]; then
        echo "ℹ️  注意：faster-whisper 在 macOS 上使用 CPU（Apple Silicon 仍然很快！）"
    fi
else
    echo ""
    echo "ℹ️  未检测到 NVIDIA GPU。使用 CPU 模式。"
    echo "   如果您有 GPU，请确保已安装 CUDA 驱动程序。"
fi

# 使脚本可执行
chmod +x "$SCRIPT_DIR/scripts/"*

echo ""
echo "✅ 安装完成！"
echo ""
if [ "$HAS_CUDA" = true ]; then
    echo "🚀 GPU 加速已启用 — 预计速度约为实时 20 倍"
elif [ "$HAS_APPLE_SILICON" = true ]; then
    echo "🍎 Apple Silicon — 预计 CPU 速度约为实时 3-5 倍"
else
    echo "💻 CPU 模式 — 转录速度较慢但功能正常"
fi
echo ""
echo "使用方法："
echo "  $SCRIPT_DIR/.venv/bin/python3 $SCRIPT_DIR/scripts/transcribe.py 音频文件.mp3"
echo ""
echo "首次运行将下载模型（distil-large-v3 约 756MB）。"
echo ""
echo "环境变量建议设置："
echo "  export HF_HOME=/config/huggingface"
echo "  export HF_ENDPOINT=https://hf-mirror.com  # 国内镜像加速"
echo ""
echo "中文转录示例："
echo "  .venv/bin/python3 scripts/transcribe.py 会议录音.mp3 --language zh --device auto"
echo ""
echo "如需帮助，请查看 SKILL.md 文档。"

path: _meta.json
content: {
  "ownerId": "system",
  "slug": "faster-whisper-zh",
  "version": "1.0.5",
  "description": "faster-whisper 中文版 - 高性能本地语音转文字工具",
  "tags": ["语音识别", "语音转文字", "whisper", "中文", "转录"],
  "language": "zh-CN"
}

path: scripts/batch_transcribe.sh
content: #!/bin/bash
# 批量转录脚本
# 自动处理目录中的所有音频文件

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
VENV_DIR="$SCRIPT_DIR/../.venv"

# 默认参数
MODEL="large-v3-turbo"
LANGUAGE="zh"
DEVICE="cpu"
COMPUTE_TYPE="auto"
OUTPUT_DIR="./transcripts"
FORMATS="mp3 wav m4a flac ogg webm"

# 显示帮助信息
show_help() {
    echo "批量转录脚本"
    echo ""
    echo "用法: $0 [选项] [音频目录]"
    echo ""
    echo "选项:"
    echo "  -h, --help            显示此帮助信息"
    echo "  -m, --model MODEL     指定模型 (默认: large-v3-turbo)"
    echo "  -l, --language LANG   指定语言代码 (默认: zh)"
    echo "  -d, --device DEVICE   计算设备: auto, cpu, cuda (默认: cpu)"
    echo "  -c, --compute TYPE    计算类型: auto, int8, float16, float32 (默认: auto)"
    echo "  -o, --output DIR      输出目录 (默认: ./transcripts)"
    echo "  --word-timestamps     包含词级时间戳"
    echo "  --json                输出 JSON 格式"
    echo "  --vad                 启用语音活动检测"
    echo ""
    echo "示例:"
    echo "  $0 ./audio_files"
    echo "  $0 -m large-v3-turbo -l en --device cuda ./recordings"
    echo "  $0 --model small --device cpu --compute-type int8 ./interviews"
    echo ""
    exit 0
}

# 解析命令行参数
POSITIONAL_ARGS=()
while [[ $# -gt 0 ]]; do
    case $1 in
        -h|--help)
            show_help
            ;;
        -m|--model)
            MODEL="$2"
            shift 2
            ;;
        -l|--language)
            LANGUAGE="$2"
            shift 2
            ;;
        -d|--device)
            DEVICE="$2"
            shift 2
            ;;
        -c|--compute)
            COMPUTE_TYPE="$2"
            shift 2
            ;;
        -o|--output)
            OUTPUT_DIR="$2"
            shift 2
            ;;
        --word-timestamps)
            WORD_TIMESTAMPS="--word-timestamps"
            shift
            ;;
        --json)
            JSON_OUTPUT="--json"
            shift
            ;;
        --vad)
            VAD="--vad"
            shift
            ;;
        -*|--*)
            echo "错误: 未知选项 $1"
            exit 1
            ;;
        *)
            POSITIONAL_ARGS+=("$1")
            shift
            ;;
    esac
done

# 设置位置参数
set -- "${POSITIONAL_ARGS[@]}"

# 检查输入目录
if [ $# -eq 0 ]; then
    INPUT_DIR="."
else
    INPUT_DIR="$1"
fi

if [ ! -d "$INPUT_DIR" ]; then
    echo "错误: 输入目录不存在: $INPUT_DIR"
    exit 1
fi

# 创建输出目录
mkdir -p "$OUTPUT_DIR"

# 激活虚拟环境
if [ -f "$VENV_DIR/bin/activate" ]; then
    source "$VENV_DIR/bin/activate"
else
    echo "警告: 未找到虚拟环境，尝试直接使用 Python"
fi

# 设置环境变量（国内镜像加速）
export HF_HOME=/config/huggingface
export HF_ENDPOINT=https://hf-mirror.com

echo "========================================"
echo "批量转录开始"
echo "输入目录: $INPUT_DIR"
echo "输出目录: $OUTPUT_DIR"
echo "模型: $MODEL"
echo "语言: $LANGUAGE"
echo "设备: $DEVICE"
echo "计算类型: $COMPUTE_TYPE"
echo "========================================"
echo ""

# 统计变量
TOTAL_FILES=0
SUCCESS_COUNT=0
FAIL_COUNT=0

# 处理音频文件
for format in $FORMATS; do
    for audio_file in "$INPUT_DIR"/*."$format" "$INPUT_DIR"/*."${format^^}"; do
        if [ -f "$audio_file" ]; then
            TOTAL_FILES=$((TOTAL_FILES + 1))
            
            filename=$(basename "$audio_file")
            base_name="${filename%.*}"
            output_file="$OUTPUT_DIR/$base_name.txt"
            
            echo "处理 [$TOTAL_FILES]: $filename"
            
            # 构建命令
            cmd="python3 $SCRIPT_DIR/transcribe.py \"$audio_file\" \
                --model \"$MODEL\" \
                --language \"$LANGUAGE\" \
                --device \"$DEVICE\" \
                --compute-type \"$COMPUTE_TYPE\" \
                --output \"$output_file\""
            
            # 添加可选参数
            [ -n "$WORD_TIMESTAMPS" ] && cmd="$cmd $WORD_TIMESTAMPS"
            [ -n "$JSON_OUTPUT" ] && cmd="$cmd $JSON_OUTPUT"
            [ -n "$VAD" ] && cmd="$cmd $VAD"
            
            # 执行转录
            if eval "$cmd" 2>/dev/null; then
                echo "  ✓ 完成: $output_file"
                SUCCESS_COUNT=$((SUCCESS_COUNT + 1))
            else
                echo "  ✗ 失败: $filename"
                FAIL_COUNT=$((FAIL_COUNT + 1))
            fi
            
            echo ""
        fi
    done
done

# 处理完成
echo "========================================"
echo "批量转录完成"
echo "总计文件: $TOTAL_FILES"
echo "成功: $SUCCESS_COUNT"
echo "失败: $FAIL_COUNT"
echo "输出目录: $OUTPUT_DIR"
echo "========================================"

# 生成摘要文件
if [ $SUCCESS_COUNT -gt 0 ]; then
    SUMMARY_FILE="$OUTPUT_DIR/转录摘要.txt"
    {
        echo "批量转录摘要"
        echo "生成时间: $(date)"
        echo "输入目录: $INPUT_DIR"
        echo "输出目录: $OUTPUT_DIR"
        echo "模型: $MODEL"
        echo "语言: $LANGUAGE"
        echo "设备: $DEVICE"
        echo "计算类型: $COMPUTE_TYPE"
        echo ""
        echo "文件统计:"
        echo "- 总计文件: $TOTAL_FILES"
        echo "- 成功转录: $SUCCESS_COUNT"
        echo "- 失败: $FAIL_COUNT"
        echo ""
        echo "转录文件列表:"
        find "$OUTPUT_DIR" -name "*.txt" -type f | while read file; do
            echo "- $(basename "$file")"
        done
    } > "$SUMMARY_FILE"
    
    echo "摘要已保存到: $SUMMARY_FILE"
fi

# 停用虚拟环境（如果激活了）
if type deactivate >/dev/null 2>&1; then
    deactivate
fi

path: scripts/transcribe.py
content: #!/usr/bin/env python3
"""
faster-whisper 转录命令行工具
基于 CTranslate2 后端的高性能语音转文字
"""

import sys
import json
import argparse
from pathlib import Path

try:
    from faster_whisper import WhisperModel
except ImportError:
    print("错误: 未安装 faster-whisper", file=sys.stderr)
    print("请运行安装脚本: ./setup.sh", file=sys.stderr)
    sys.exit(1)


def check_cuda_available():
    """检查 CUDA 是否可用并返回设备信息。"""
    try:
        import torch
        if torch.cuda.is_available():
            return True, torch.cuda.get_device_name(0)
        return False, None
    except ImportError:
        return False, None


def main():
    parser = argparse.ArgumentParser(
        description="使用 faster-whisper 转录音频文件",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
使用示例:
  # 基本中文转录
  %(prog)s 音频文件.mp3 --language zh
  
  # 使用 GPU 加速
  %(prog)s 音频文件.mp3 --device cuda --compute-type float16
  
  # 英文转录，包含词级时间戳
  %(prog)s 音频文件.mp3 --language en --word-timestamps
  
  # 快速 CPU 转录
  %(prog)s 音频文件.mp3 --device cpu --compute-type int8 --model distil-large-v3
  
  # 输出到文件
  %(prog)s 音频文件.mp3 --output 转录结果.txt

支持格式: mp3, wav, m4a, flac, ogg, webm
        """
    )
    parser.add_argument(
        "audio",
        metavar="音频文件",
        help="音频文件路径 (支持 mp3, wav, m4a, flac, ogg, webm)"
    )
    parser.add_argument(
        "-m", "--model",
        default="large-v3-turbo",
        metavar="模型名称",
        help="使用的 Whisper 模型 (默认: large-v3-turbo)。选项: tiny, base, small, medium, large-v3, large-v3-turbo, distil-large-v3, distil-medium.en"
    )
    parser.add_argument(
        "-l", "--language",
        default="zh",
        metavar="语言代码",
        help="语言代码，如 zh, en, es, fr (如果省略则自动检测)"
    )
    parser.add_argument(
        "--word-timestamps",
        action="store_true",
        help="在输出中包含词级时间戳"
    )
    parser.add_argument(
        "--beam-size",
        type=int,
        default=5,
        metavar="N",
        help="束搜索大小；值越高越准确但越慢 (默认: 5)"
    )
    parser.add_argument(
        "--vad",
        action="store_true",
        help="启用语音活动检测以跳过静音部分"
    )
    parser.add_argument(
        "-j", "--json",
        action="store_true",
        help="以 JSON 格式输出完整转录结果，包含分段和元数据"
    )
    parser.add_argument(
        "-o", "--output",
        metavar="输出文件",
        help="将转录结果写入文件而不是标准输出"
    )
    parser.add_argument(
        "--device",
        default="cpu",
        choices=["auto", "cpu", "cuda"],
        help="计算设备: auto (自动检测GPU), cpu, 或 cuda (默认: cpu)"
    )
    parser.add_argument(
        "--compute-type",
        default="auto",
        choices=["auto", "int8", "float16", "float32"],
        help="量化类型: auto, int8 (快速CPU), float16 (GPU), float32 (默认: auto)"
    )
    parser.add_argument(
        "-q", "--quiet",
        action="store_true",
        help="抑制进度和状态消息"
    )

    args = parser.parse_args()

    # 验证音频文件
    audio_path = Path(args.audio)
    if not audio_path.exists():
        print(f"错误: 未找到音频文件: {args.audio}", file=sys.stderr)
        sys.exit(1)

    # 自动检测设备和计算类型
    device = args.device
    compute_type = args.compute_type

    cuda_available, gpu_name = check_cuda_available()

    if device == "auto":
        if cuda_available:
            device = "cuda"
        else:
            device = "cpu"
            # 如果没有 CUDA 但未明确请求 CPU，则发出警告
            if not args.quiet:
                print("⚠️  未检测到 CUDA — 使用 CPU（速度会较慢！）", file=sys.stderr)
                print("   要启用 GPU: pip install torch --index-url https://download.pytorch.org/whl/cu121", file=sys.stderr)
                print("   或重新运行: ./setup.sh", file=sys.stderr)
                print("", file=sys.stderr)

    if compute_type == "auto":
        # 根据设备优化
        if device == "cuda":
            compute_type = "float16"  # GPU 最佳选择
        else:
            compute_type = "int8"  # CPU 最佳选择（4倍加速）

    if not args.quiet:
        if device == "cuda" and gpu_name:
            print(f"正在加载模型: {args.model} ({device}, {compute_type}) 在 {gpu_name} 上", file=sys.stderr)
        else:
            print(f"正在加载模型: {args.model} ({device}, {compute_type})", file=sys.stderr)

    # 加载模型
    try:
        model = WhisperModel(
            args.model,
            device=device,
            compute_type=compute_type
        )
    except Exception as e:
        print(f"加载模型时出错: {e}", file=sys.stderr)
        sys.exit(1)

    # 转录
    try:
        if not args.quiet:
            print(f"正在转录: {audio_path.name}", file=sys.stderr)

        segments, info = model.transcribe(
            str(audio_path),
            language=args.language if args.language != "auto" else None,
            beam_size=args.beam_size,
            word_timestamps=args.word_timestamps,
            vad_filter=args.vad
        )

        if not args.quiet:
            print(f"检测到语言: {info.language} (概率: {info.language_probability:.2f})", file=sys.stderr)

        # 收集结果
        full_text = ""
        segments_list = []

        for segment in segments:
            segment_text = segment.text.strip()
            full_text += segment_text + " "
            
            segment_dict = {
                "start": segment.start,
                "end": segment.end,
                "text": segment_text
            }
            
            if args.word_timestamps and segment.words:
                segment_dict["words"] = [
                    {
                        "word": word.word,
                        "start": word.start,
                        "end": word.end
                    }
                    for word in segment.words
                ]
            
            segments_list.append(segment_dict)
            
            # 如果不是 JSON 输出，则实时显示
            if not args.json and not args.quiet:
                print(f"[{segment.start:.2f} --> {segment.end:.2f}] {segment_text}")

        full_text = full_text.strip()

        # 输出结果
        if args.json:
            result = {
                "text": full_text,
                "language": info.language,
                "language_probability": info.language_probability,
                "duration": info.duration,
                "segments": segments_list,
                "model": args.model,
                "device": device,
                "compute_type": compute_type
            }
            output_text = json.dumps(result, ensure_ascii=False, indent=2)
        else:
            output_text = full_text

        # 写入文件或输出到控制台
        if args.output:
            with open(args.output, 'w', encoding='utf-8') as f:
                f.write(output_text)
            if not args.quiet:
                print(f"✓ 转录结果已保存到: {args.output}", file=sys.stderr)
        else:
            print(output_text)

        if not args.quiet:
            print(f"✓ 转录完成！时长: {info.duration:.1f}秒", file=sys.stderr)

    except KeyboardInterrupt:
        print("\n✗ 转录被用户中断", file=sys.stderr)
        sys.exit(130)
    except Exception as e:
        print(f"转录时出错: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()

Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)