AI 同声传译助手

实时将英语或其他外语的单向音频流翻译成中文字幕，支持中间结果展示和自动修正。

项目说明

展示视频：DemoShowcase.mkv

本项目对应比赛题目二：AI 同声传译助手。目标是为英语演讲、技术分享、国际会议和网课等外语音频场景提供实时中文传译能力，通过字幕或语音输出帮助用户跟上内容节奏，并支持对中间识别和翻译结果进行自动修正。

技术实现上，前端使用 Vue 3、TypeScript 和 Vite 构建交互界面，桌面端使用 Electron 提供本地应用、托盘菜单、桌面音频采集和透明悬浮字幕窗口。后端使用 Python FastAPI 和 WebSocket 接收实时音频流、转发字幕事件并管理历史记录，Python 依赖通过 uv 管理，桌面打包时后端以 PyInstaller sidecar 形式内置。实时翻译主链路使用阿里云百炼 Qwen3.5-Livetranslate Realtime，配置与历史记录通过 SQLite 在本机持久化保存。

功能特性

• 🎙️ 浏览器麦克风实时音频采集
• 🖥️ Electron 桌面模式，支持桌面音频、麦克风或混合采集
• 🪟 Electron 透明置顶字幕悬浮窗，可编辑位置/大小/字号并锁定显示
• 🔤 阿里云百炼 Qwen3.5-Livetranslate Realtime 端到端语音翻译
• 🌐 音频流直接生成实时中文字幕，支持源语言转录与最终结果回写
• 🔐 页面配置 DashScope API Key 和实时翻译模型，API Key 后端加密保存
• 🗂️ SQLite 持久化保存实时翻译历史
• ✨ 活跃字幕尾部裁剪、历史字幕滚动、修正高亮、波形可视化
• 📊 音频波形可视化
• 📦 Electron 打包桌面应用，支持托盘菜单、单实例运行和内置后端 sidecar

快速开始

桌面应用开发

cp .env.example .env
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
# 将生成结果填入 APP_SECRET_KEY
# 可填入 DASHSCOPE_API_KEY，或在应用“配置”面板保存 DashScope API Key

启动前端开发服务器：

cd frontend
npm install
npm run dev

另开一个终端启动 Electron。Electron 会自动启动本地 FastAPI sidecar；开发模式下依赖 uv：

cd frontend
npm run electron:dev

首次进入应用后，在“配置”面板保存 DashScope API Key 和模型名称。默认模型为 qwen3.5-livetranslate-flash-realtime，API Key 会加密写入 SQLite。

桌面应用使用说明：

• 主窗口右上角关闭按钮不会退出应用，只会隐藏到系统托盘。
• 托盘菜单提供“打开主窗口”、“打开/关闭悬浮字幕”、“退出应用”。
• 只有托盘菜单里的“退出应用”会关闭主窗口、悬浮字幕、内置后端进程和托盘图标。
• 应用启用了单实例保护，重复启动 exe 会唤起已有主窗口，不会再启动第二个后端。
• 悬浮字幕编辑态显示工具条，可拖动窗口、拖动边缘调整大小、使用 A-/A+ 调整字号、锁定或关闭字幕。
• 悬浮字幕锁定态默认只显示字幕；鼠标移入字幕区域时右上角淡入“编辑/关闭”，鼠标离开约 800ms 后自动隐藏。
• 点击“关闭”后，后续实时字幕不会自动重新弹出悬浮窗，需要从主窗口或托盘重新打开。

桌面应用打包

Windows 推荐直接用仓库脚本：

Set-ExecutionPolicy -Scope Process Bypass
.\scripts\build-windows.ps1

快速生成未安装目录包用于本机测试：

.\scripts\build-windows.ps1 -Target dir

如果已经安装过依赖，可以跳过依赖安装：

.\scripts\build-windows.ps1 -SkipInstall

脚本会检查 uv、node、npm，然后构建 Vue renderer、用 PyInstaller 生成 Windows 后端 sidecar translator-backend.exe，最后调用 electron-builder 输出 Windows 桌面包。

默认 dist 产物为安装包，通常运行：

frontend\release\AI 同声传译助手 Setup 1.0.2.exe

-Target dir 产物适合本机快速调试，运行：

frontend\release\win-unpacked\AI 同声传译助手.exe

重新安装或重新打包测试前，先通过托盘菜单“退出应用”，或在任务管理器中确认旧进程已结束。Electron 默认后端端口是 38766，如果本地后端启动失败，可先检查端口占用：

netstat -ano | findstr :38766

发布版后端日志保存在 %APPDATA%\SimultaneousTranslator\backend-data\backend.log。

Linux/macOS 手动打包：

cd backend
uv sync --group dev

cd ../frontend
npm install
npm run electron:dist

打包流程会先构建 Vue renderer，再用 PyInstaller 把 FastAPI 后端打成 translator-backend onedir sidecar，最后由 electron-builder 生成桌面应用。打包产物输出到 frontend/release/。

当前环境下如果 Electron 二进制下载较慢，可以配置 npm/Electron 镜像后重试。

Docker/Web 可选部署

docker compose up -d --build

打开浏览器访问 http://localhost:3000

首次进入页面后，在右侧“配置”面板保存 DashScope API Key 和模型名称。API Key 会加密写入后端 SQLite，数据库保存在 Docker volume backend_data 中。

完成传译并停止后，右侧“历史”面板会显示本次会话的最终中文译文。历史记录只保存最终译文，不保存中间结果。

Web 版不具备系统级透明悬浮字幕、托盘菜单和桌面音频 loopback 能力；这些能力只在 Electron 桌面模式中可用。

常用容器命令：

docker compose ps
docker compose logs -f backend frontend
docker compose down

历史记录和页面保存的供应商配置会保留在 Docker volume 中；如需清除容器数据：

docker compose down -v

开发

Backend

cd backend
uv sync
export APP_SECRET_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
uv run uvicorn app.main:app --reload --port 8000

Frontend

cd frontend
npm install
npm run dev

本地开发时，Vite 会代理 /api 和 /ws 到 localhost:8000。

Electron 开发模式默认通过 preload 指向 http://127.0.0.1:38766，并由 Electron 主进程启动本地后端。可用 SKIP_BACKEND_SIDECAR=1 跳过自动启动，或通过 BACKEND_PORT 修改端口。

如果设置 APP_URL，Electron 会加载该 URL 而不是打包内置页面，通常只用于调试。正式包不要设置 APP_URL、SKIP_BACKEND_SIDECAR、BACKEND_EXECUTABLE 或 BACKEND_PORT，除非明确知道要覆盖默认行为。

技术架构

详见 PLAN.md

实时翻译模型

• 阿里云百炼 qwen3.5-livetranslate-flash-realtime
• 可选：输出语音播放
• 可选：视觉上下文输入