# whisperSync

**Repository Path**: web/whisper-sync

## Basic Information

- **Project Name**: whisperSync
- **Description**: 实时语音转文字
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Whisper Sync 🎙️

基于 **whisper.cpp** 的实时语音转文字服务，支持 HTTP 和 WebSocket 接口，具备智能反幻觉处理和高质量音频预处理能力。

## ✨ 功能特性

| 功能 | 状态 | 描述 |
|------|------|------|
| 动态模型选择 | ✅ | 通过参数选择不同的 whisper.cpp 模型 |
| HTTP 语音转写 | ✅ | 支持音频文件上传进行转写 |
| WebSocket 实时转写 | ✅ | 支持实时流式语音转写 |
| 跨平台支持 | ✅ | Windows / Linux / macOS / Web |
| 智能反幻觉 | ✅ | 15+ 种幻觉检测模式，自动过滤低质量结果 |
| 音频预处理 | ✅ | 静音检测、噪声过滤、归一化处理 |
| 参数动态调整 | ✅ | 通过 API 实时调整转写参数 |
| 配置持久化 | ✅ | 参数保存到文件，重启后保持不变 |
| API Key 认证 | ✅ | 可选 API Key 认证，支持 HTTP Header 和 WebSocket |

## 🚀 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 准备模型

将 whisper.cpp 的 GGML 格式模型文件放入 `./models` 目录。

**推荐模型下载地址：**
- [Hugging Face - whisper.cpp models](https://huggingface.co/ggerganov/whisper.cpp/tree/main)

https://down.nigx.cn/huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.bin?download=true
https://down.nigx.cn/huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin?download=true
https://down.nigx.cn/huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin?download=true
https://down.nigx.cn/huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium.bin?download=true
https://down.nigx.cn/huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v1.bin?download=true
https://down.nigx.cn/huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v2.bin?download=true
https://down.nigx.cn/huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin?download=true

**常用模型对比：**

| 模型 | 大小 | 转写质量 | 推理速度 |
|------|------|----------|----------|
| ggml-tiny | ~77MB | 基础 | 最快 |
| ggml-base | ~148MB | 良好 | 快 |
| ggml-small | ~488MB | 优秀 | 中等 |
| ggml-medium | ~1.5GB | 非常优秀 | 较慢 |
| ggml-large | ~3.09GB | 最佳 | 慢 |

### 3. 获取 whisper.cpp 二进制文件

#### 方法 1: 下载预编译的二进制文件

从 [whisper.cpp releases](https://github.com/ggerganov/whisper.cpp/releases) 下载适合你平台的预编译二进制文件，解压到 `./whisper-bin/Release/` 目录。

#### 方法 2: 从源码编译

```bash
git clone https://github.com/ggerganov/whisper.cpp.git
cd whisper.cpp
make
cp main ../whisper-sync/whisper-bin/Release/whisper-cli
```

### 4. 配置 API Key（可选）

创建 `.env` 文件（参考 `.env.example`）：

```bash
# 不设置 API_KEY 则无需认证
# 设置后所有 API 和 WebSocket 请求需要提供 API Key
API_KEY=your-secret-key

# 服务端口
PORT=3000
```

> 可通过环境变量 `API_KEY` 或 `.env` 文件配置。不设置则不启用认证。

### 5. 启动服务

```bash
npm start
```

服务将在 `http://localhost:3000` 启动。

## 🔐 API Key 认证

如果配置了 `API_KEY`，所有请求均需提供 API Key，支持以下方式：

### HTTP 请求

**方式 1：Header（推荐）**
```http
X-API-Key: your-secret-key
```

**方式 2：Query 参数**
```
/api/models?api_key=your-secret-key
```

### WebSocket 连接

通过 URL 查询参数提供：
```
ws://localhost:3000?api_key=your-secret-key
```

> 不设置 `API_KEY` 时，所有接口无需认证即可访问。

## 📡 API 文档

### HTTP 接口

#### 1. 获取可用模型

```http
GET /api/models
```

**响应示例：**
```json
{
  "success": true,
  "models": [
    {
      "name": "ggml-base",
      "path": "D:\\whisper-sync\\models\\ggml-base.bin",
      "file": "ggml-base.bin"
    },
    {
      "name": "ggml-tiny",
      "path": "D:\\whisper-sync\\models\\ggml-tiny.bin",
      "file": "ggml-tiny.bin"
    }
  ]
}
```

#### 2. 获取当前配置

```http
GET /api/config
```

**响应示例：**
```json
{
  "success": true,
  "config": {
    "temperature": 0.0,
    "no_speech_threshold": 0.6,
    "compression_ratio_threshold": 2.4,
    "logprob_threshold": -1.0,
    "enableHallucinationFilter": true,
    "hallucinationPatterns": 15
  }
}
```

#### 3. 更新配置

```http
POST /api/config
Content-Type: application/json
```

**请求体：**
```json
{
  "temperature": 0.3,
  "no_speech_threshold": 0.7,
  "enableHallucinationFilter": true
}
```

**参数说明：**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| temperature | number | 0.0 | 采样温度，0-1，越低越确定性 |
| no_speech_threshold | number | 0.6 | 静音检测阈值，0-1 |
| compression_ratio_threshold | number | 2.4 | 熵阈值，用于检测解码器失败 |
| logprob_threshold | number | -1.0 | 对数概率阈值 |
| enableHallucinationFilter | boolean | true | 是否启用反幻觉过滤 |

#### 4. 语音转文字

```http
POST /api/transcribe
Content-Type: multipart/form-data
```

**参数：**
- `audio`: 音频文件（必需）
- `model`: 模型名称（可选，默认 ggml-base）
- `language`: 语言代码（可选，默认 auto）

**支持的语言代码：**
- `auto`: 自动检测
- `zh`: 中文
- `en`: 英语
- `ja`: 日语
- `ko`: 韩语
- `es`: 西班牙语
- `fr`: 法语
- `de`: 德语

**响应示例：**
```json
{
  "success": true,
  "result": {
    "text": "你好，这是转写结果",
    "segments": [
      {
        "start": 0,
        "end": 2.5,
        "text": "你好"
      }
    ],
    "language": "zh",
    "model": "ggml-base",
    "processingTime": 28,
    "hallucinationsRemoved": 0
  }
}
```

### WebSocket 接口

**连接地址：** `ws://localhost:3000`

**消息格式：**
```json
{
  "type": "transcribe",
  "audio": "base64编码的音频数据",
  "model": "ggml-base",
  "language": "zh"
}
```

**响应：**
```json
{
  "type": "result",
  "result": {
    "text": "转写结果",
    "segments": [...],
    "language": "zh",
    "model": "ggml-base"
  }
}
```

## 🛠️ 核心优化

### 参数调优

| 参数 | 值 | 效果 |
|------|-----|------|
| temperature | 0.0 | 减少随机性，提高稳定性 |
| beam-size | 1 | 减少搜索宽度，提升速度 |
| best-of | 1 | 只保留最佳结果 |
| max-context | -1 | 禁用上下文依赖 |
| no-fallback | true | 禁用温度回退 |

### 智能反幻觉过滤

内置 **15+** 种幻觉内容检测模式：

1. 常见幻觉短语（谢谢观看、订阅、点赞等）
2. 填充词检测（嗯、呃、啊等）
3. 重复模式检测（单字符重复、短语重复）
4. 音乐/字幕标记检测（♪、🎵、[字幕]等）
5. 网站/链接幻觉检测
6. 时间戳幻觉检测
7. 版权/广告幻觉检测
8. 字符多样性检测
9. 词汇重复率检测

### 音频预处理

- **静音检测**: 基于能量 + 零交叉率分析
- **高通滤波**: 去除低频噪音（200Hz 以下）
- **低通滤波**: 去除高频噪音（3000Hz 以上）
- **归一化**: 自动调整音频音量

## 📁 项目结构

```
whisper-sync/
├── models/                    # 模型文件目录
│   ├── ggml-base.bin
│   └── ggml-tiny.bin
├── public/                    # Web 前端文件
│   └── index.html            # 可视化测试界面
├── src/
│   ├── index.js              # 主服务入口（HTTP + WebSocket）
│   ├── model-manager.js      # 模型管理模块
│   ├── config-manager.js     # 配置管理模块（持久化）
│   ├── hallucination-filter.js # 反幻觉检测模块
│   ├── audio-preprocessor.js # 音频预处理模块
│   └── transcriber.js        # 转写引擎封装
├── whisper-bin/               # whisper.cpp 二进制文件
│   └── Release/
│       └── whisper-cli.exe
├── uploads/                   # 临时上传目录
├── .env                       # 环境变量配置（API Key 等，不提交到 Git）
├── .env.example               # 环境变量配置示例
├── config.json                # 配置文件（自动生成）
├── package.json
└── README.md
```

## 🌐 Web 界面

访问 `http://localhost:3000` 可使用可视化测试界面：

**功能特点：**
- 🔑 **API Key 输入**: 支持在界面中输入 API Key，自动应用到所有请求
- 📤 **HTTP 上传**: 选择音频文件进行转写
- 🔧 **参数调整**: 实时调整 temperature、静音检测阈值等参数
- 💾 **配置保存**: 参数自动保存，刷新页面不丢失
- 🎤 **实时录音**: 使用 WebSocket 进行实时语音转写
- 📊 **结果展示**: 显示转写文本和处理时间

## 🚀 开发模式

```bash
npm run dev
```

启用开发模式，支持热更新。

## 📝 配置文件

配置文件 `config.json` 自动保存在项目根目录：

```json
{
  "temperature": 0.0,
  "no_speech_threshold": 0.6,
  "compression_ratio_threshold": 2.4,
  "logprob_threshold": -1.0,
  "enableHallucinationFilter": true,
  "hallucinationPatterns": 15
}
```

## ⚠️ 注意事项

1. **音频格式**: 支持 flac, mp3, ogg, wav 等格式
2. **内存要求**: 根据模型大小调整（tiny: ~1GB, base: ~2GB, large: ~8GB）
3. **首次加载**: 模型首次加载可能需要几秒时间
4. **FFmpeg**: 音频预处理需要安装 FFmpeg

## 🔒 生产部署

### 使用 PM2 管理进程

```bash
npm install -g pm2

# 创建 PM2 配置文件
cat > ecosystem.config.js << 'EOF'
module.exports = {
  apps: [{
    name: 'whisper-sync',
    script: './src/index.js',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '4G',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    },
    error_file: './logs/error.log',
    out_file: './logs/out.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z'
  }]
}
EOF

# 启动服务
mkdir -p logs
pm2 start ecosystem.config.js
pm2 startup
pm2 save
```

### Nginx 反向代理配置

```nginx
server {
    listen 80;
    server_name your-domain.com;

    client_max_body_size 100M;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 86400;
    }
}
```

## 📜 许可证

MIT

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📧 联系方式

如有问题或建议，请通过 Issue 联系。