# voiceTranscribe

**Repository Path**: newjcj/voiceTranscribe

## Basic Information

- **Project Name**: voiceTranscribe
- **Description**: mac电脑上部署的可以上传mp3然后转带追踪精确到每个字播放进度的的字幕json文件，还可以生成双语原文与翻译同时显示，使用的技术whinsper和omlx
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 语音转文字服务

基于 mlx-whisper 的语音转文字 Web 服务，支持双语翻译。

## 环境要求

- macOS (Apple Silicon M4)
- Python 3.12
- oMLX (可选，用于双语翻译)

## 快速启动

```bash
python3.12 run.py
```

服务启动后访问 http://localhost:8899

## 功能

1. **项目管理** - 创建项目并上传 MP3 文件
2. **语音转文字** - 使用 mlx-whisper 将 MP3 转为 JSON（逐词时间戳）
3. **卡拉OK播放** - 基于 Whisper JSON 的逐字/词高亮播放
4. **双语翻译** - 调用 oMLX API 翻译为另一种语言
5. **状态管理** - 刷新所有项目状态，显示转写/翻译进度

## 项目结构

```
voice/
├── config.py            # 配置（端口、路径、API参数）
├── logger.py            # 日志模块（控制台+文件）
├── database.py          # JSON 数据库操作
├── whisper_service.py   # mlx-whisper 转写服务
├── translate_service.py # omlx 双语翻译服务
├── app.py               # Flask Web 服务
├── run.py               # 启动脚本（自动安装依赖）
├── requirements.txt     # Python 依赖
├── templates/
│   ├── index.html       # 首页（项目列表）
│   └── player.html      # 播放页（卡拉OK）
├── tests/
│   └── test_core.py     # 单元测试
├── projects/            # 项目数据目录
└── logs/                # 日志目录
```

## 局域网访问

服务默认绑定 `0.0.0.0:8899`，局域网其他设备可通过 `http://<Mac的IP>:8899` 访问。

如果无法访问，可能需要在 macOS 防火墙中放行：

```bash
# 查看防火墙状态
/usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# 如需临时关闭防火墙（不推荐长期关闭）
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off

# 添加 Python 到防火墙白名单（推荐）
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add $(which python3.12)
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp $(which python3.12)
```

## 双语翻译配置

使用本地 oMLX 提供的 OpenAI 兼容 API：

- API 地址: `http://127.0.0.1:8000/v1`
- 模型: `gemma-4-e4b-it-4bit`

确保 oMLX 服务已启动后再使用翻译功能。

## 测试

```bash
python3.12 -m pytest tests/ -v
```