#  wf-voice-trail

**Repository Path**: wfchat/wf-voice-trail

## Basic Information

- **Project Name**:  wf-voice-trail
- **Description**: 语音转文本服务体验版
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wf-voice 体验版测试说明

wf-voice 是多语言语音识别服务，支持中、粤、英、日、韩多语言识别、情感识别和事件检测，提供 **HTTP 文件上传** 和 **WebSocket 实时音频流** 两种接入方式。

**体验版限制：每次上传的音频文件、每条实时音频流，最多处理前 30 秒内容**，超出部分不处理。正式版无此限制，价格是1万块钱，如果需要请联系我们购买。

## 1. 选择对应平台的安装包

| 平台 | 安装包 |
|---|---|
| macOS（Apple Silicon） | `wf-voice-1.4.0-trial-macos-arm64.tar.gz` |
| Linux x86_64 | `wf-voice-1.4.0-trial-linux-amd64.tar.gz` |
| Linux ARM64 | `wf-voice-1.4.0-trial-linux-arm64.tar.gz` |
| Windows 10/11 x64 | `wf-voice-1.4.0-trial-windows-amd64.zip` |

Linux 版本在 Debian 10（glibc 2.28）环境编译，二进制依赖的 glibc 符号最高为 2.27，可运行在 glibc 2.27/2.28 及更高版本的系统（CentOS 8、Debian 10、Ubuntu 18.10+ 等，已在 glibc 2.28 环境验证）。

解压：

Linux / macOS：

```bash
tar -xzf wf-voice-1.4.0-trial-<平台>.tar.gz
chmod +x wf-voice ffmpeg
```

Windows：直接解压 zip 即可，得到 `wf-voice.exe` 和 `ffmpeg.exe` 两个文件。

> macOS 包已用 Apple 开发者证书签名。首次运行如仍提示"无法验证开发者"，执行：
> `xattr -d com.apple.quarantine ./wf-voice ./ffmpeg`

## 2. 运行依赖

**无需安装 ffmpeg**：安装包内已附带静态编译的 `ffmpeg`（Windows 为 `ffmpeg.exe`，与 `wf-voice` 同目录，程序自动优先使用）。请保持解压后 `wf-voice` 和 `ffmpeg` 两个文件在同一目录。

**模型文件**：模型文件当前项目下```./model/wf-voice-small.gguf```，约 278MB。

## 3. 启动服务

Linux / macOS：

```bash
mkdir -p wav
./wf-voice -m ./model/wf-voice-small.gguf --save-dir ./wav
```

Windows（CMD 或 PowerShell，在解压目录下执行）：

```bat
mkdir wav
wf-voice.exe -m .\model\wf-voice-small.gguf --save-dir .\wav
```

启动后监听两个端口：

| 端口 | 用途 |
|---|---|
| 12435 | HTTP 接口（上传音频文件识别） |
| 12436 | WebSocket 接口（实时音频流识别） |

启动日志中出现 `Trial edition: max 30000 ms of audio per request/stream` 即为体验版。

常用可选参数：

| 参数 | 说明 |
|---|---|
| `--port PORT` | 修改 HTTP 端口（默认 12435） |
| `--wsport PORT` | 修改 WebSocket 端口（默认 12436） |
| `--no-save` | 不保存实时流的录音文件 |
| `-t N` | 推理线程数 |
| `-p N` | 并行处理数 |

## 4. 测试方法

### 4.1 网页测试

浏览器打开 `http://127.0.0.1:12435/inference`，选择音频文件提交，页面流式返回分段识别结果。

### 4.2 命令行上传音频文件

```bash
curl 127.0.0.1:12435/inference -X POST \
  -H "Content-Type: multipart/form-data" \
  -F file="@/path/to/audio.wav"
```

支持常见音频格式（wav、mp3、ogg、amr 等，服务端自动用 ffmpeg 转码）。返回示例：

```
[0.03-9.92] Good morning, this Tuesday is election day...
[10.18-21.50] ...
```

方括号内为语音段的开始/结束时间（秒）。

### 4.3 WebSocket 实时流

连接 `ws://127.0.0.1:12436`：

1. 连接后先发送一条**文本消息**作为客户端 ID（任意字符串）；
2. 之后持续发送**二进制消息**，内容为 16kHz、单声道、s16le（16bit 小端）PCM 原始音频数据；
3. 服务端边收边识别，识别结果以文本消息返回，格式为 `[<起始时间戳ms>+<时长秒>] 识别文本`。

## 5. 体验版的 30 秒限制行为

- **HTTP 上传**：音频超过 30 秒时只识别前 30 秒，服务端日志输出 `trial mode: truncate audio to 30000 ms`。
- **WebSocket 实时流**：每条连接累计只接收 30 秒音频，超出部分直接丢弃；首次超限时客户端会收到一条文本提示：`[TRIAL] 体验模式最多处理 30 秒音频，超出部分已忽略`。断开重连后重新计数。

## 6. 常见问题

- **启动即退出并提示 ffmpeg not found**：确认解压后 `ffmpeg` 与 `wf-voice` 在同一目录且有执行权限（`chmod +x ffmpeg`）。
- **提示 `error: failed to initialize sense voice context`**：模型路径不对，检查 `-m` 参数。
- **Linux 报 `version 'GLIBC_X.XX' not found`**：系统 glibc 低于 2.27，请更换 glibc 2.27 及以上系统（如 CentOS 8 / Debian 10 / Ubuntu 18.10+），或联系我们获取对应版本。
- **端口被占用**：用 `--port` / `--wsport` 更换端口。

测试中遇到其他问题，请附带启动命令、完整日志和测试音频反馈给我们。