EchoSRT 是一个音视频字幕自动化提取与翻译工具。提供 WebUI 工作台，支持本地 GPU/CPU 推理以及云端 API 处理，提供一站式、全自动流水线解决方案。
完整文档：EchoSRT 文档站 包含安装指南、使用教程、架构说明、API 参考和部署方案。
- 本地推理引擎：内置
faster-whisper，自动探测 NVIDIA CUDA 加速或回退 CPU 模式，支持 VAD 静音过滤、Beam Size 等高阶参数。子进程隔离运行，崩溃不影响主服务。 - 云端 API 引擎：兼容 OpenAI 格式的语音 API，针对超大文件实现突破 25MB 限制的物理切片与时间戳重排机制。额外支持说话人识别（Speaker Diarization）与词级时间戳。
- 在线 API 翻译：基于并发信号量 (
asyncio.Semaphore) 实现字幕分块异步翻译。支持 DeepSeek、ChatGPT 等任意兼容 OpenAI 接口的模型，结合上下文自动润色。 - 本地离线推理：支持 GGUF 量化模型，基于
llama-cpp-python实现本地推理。将模型文件放入models/llm/目录后，通过 WebUI 配置 GPU 加速层数、上下文长度与闲置释放时间。显存不足时自动下调max_tokens防止 OOM。 - GPU 显存互斥管理：开启后本地识别 (
faster-whisper) 与本地翻译 (GGUF) 互不抢占显存，翻译任务自动给识别任务让路，防止因并发加载导致的 OOM 崩溃。
- API 多方案管理：支持为 ASR 和 LLM 分别预设多套 API 配置（Base URL / Key / Model），一键切换方案池。
- 自动化非阻塞流水线：后端基于 FastAPI +
asyncio.Queue实现多任务调度，支持批量下发处理。 - 断点续传与状态持久化：任务中断或服务重启后，自动从断点（提音/识别/翻译）恢复，无需从头开始。
- 任务中断与取消：支持单个任务中断或一键中断全部任务，优雅中止 FFmpeg/API 请求并清理临时文件。
- FFmpeg 高级控制：支持多音轨选择、指定时间范围裁剪（
-ss/-to），适配多音轨 MKV 等复杂场景。 - 任务资产清理：支持按类型（视频/音频/原声/翻译字幕）批量清理任务资产，释放磁盘空间。内置 500MB 磁盘安全冗余检查。
- 可视化 Web 工作台：Vue 3 前端，提供实时 WebSocket 状态同步、滚动日志输出与看板式资产管理。支持拖拽排序任务。
- 分流代理机制：支持按模块（模型下载 / 云端 ASR / LLM 翻译）独立接管 HTTP/SOCKS5 网络代理，三路互不干扰。
- 媒体库扫描引擎：自动扫描磁盘目录，基于文件指纹（路径 + 大小 + mtime）去重导入，支持状态自愈与 20+ 种媒体格式。
- 多平台 Docker 部署：提供 CPU 和 GPU 独立镜像，NAS 友好（PUID/PGID 权限对齐）。
已提供云端预编译镜像，在项目根目录下直接使用 docker-compose 启动：
# 启动 CPU 节点（适合绝大多数无显卡的家用 NAS 或服务器）
docker-compose up -d echosrt-cpu
# 或者：启动 GPU 节点（需在宿主机安装 NVIDIA Container Toolkit 及驱动）
docker-compose up -d echosrt-gpu注意：Docker Compose 中 CPU 默认映射
8000端口，GPU 默认映射8001端口，可同时启动。
使用 docker run 命令启动预编译镜像：
# CPU 版本
docker run -d --name echosrt-cpu \
-p 8000:8000 \
-v $(pwd)/workspace:/app/workspace \
-v $(pwd)/models:/app/models \
-v $(pwd)/config:/app/config \
ghcr.io/siveci/echosrt:cpu-latest
# GPU 版本 (需增加 --gpus all 参数，端口改用 8001 避免与 CPU 实例冲突)
docker run -d --name echosrt-gpu \
--gpus all \
-p 8001:8000 \
-v $(pwd)/workspace:/app/workspace \
-v $(pwd)/models:/app/models \
-v $(pwd)/config:/app/config \
ghcr.io/siveci/echosrt:gpu-latest# 构建 CPU 镜像
docker build -t echosrt:cpu-local -f Dockerfile .
# 构建 GPU 镜像
docker build -t echosrt:gpu-local -f Dockerfile.gpu .
# 构建完成后，将上述 docker run 命令中的镜像名称替换为构建的镜像名后运行# 1. 安装 FFmpeg
# Windows: 下载 FFmpeg 并在项目根目录创建 bin/ffmpeg/bin/ 放入 ffmpeg.exe
# Linux: sudo apt install ffmpeg
# 2. 安装基础 Python 依赖
pip install -r requirements.txt
# [可选] 若需使用本地大模型(GGUF)翻译并开启 CUDA 加速，请安装预编译的 llama-cpp-python
# （注：以下链接以 CUDA 12.2 为例。若为其他 CUDA 版本，请将 cu122 替换为对应版本号如 cu118、cu121 等）
pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu122
# 3. 启动后台服务与 WebUI
python app.py- 浏览器打开
http://127.0.0.1:8000或http://[远程IP]:8000进入工作台。 - 访问
/docs查看 Swagger API 接口文档。
- 在 [任务工作区] 拖拽上传视频或音频文件，系统支持批量排队上传，音频文件将自动经过 FFmpeg 进行标准化 16kHz 单声道重采样。
- 勾选任务并点击"执行全量工作流"，后端会在后台自动串行执行提音、识别、翻译。
- 本地模式：对于含有大量环境噪音的视频，建议在「高级设置 -> 阈值过滤」中开启 VAD 智能静音过滤，减少模型的"幻觉"复读并提升推理速度。
- 云端模式：长音频切片上传过程全自动完成，如果使用非官方的第三方代理接口，请注意调整大文件网络超时时间。
- 填入 API Base URL 和 API Key。
- 自定义 Prompt 强制大模型输出特定风格（例如语气、设定、特定角色人名映射等）。
- 支持多套 API 方案预设，在 [语音识别] 和 [LLM 翻译] 标签页中管理。
- 本地引擎：将 GGUF 量化模型放入
models/llm/目录后，在 LLM 翻译标签页切换至"本地离线引擎"，选择模型文件并配置 GPU 加速层数、上下文长度与闲置释放时间。
服务首次启动时自动从 config/config.example.json 生成 config/config.json。主要配置项：
| 配置域 | 说明 |
|---|---|
system_settings |
全局网络代理开关、代理 URL（HTTP/SOCKS5）、GPU 显存互斥开关 (vram_mutual_exclusion)、最大上传文件限制 (max_upload_size_mb) |
secrets |
Hugging Face 认证令牌 (hf_token)，用于访问受限模型 |
model_settings |
Whisper 模型大小（tiny / base / small / medium / large-v2 / large-v3 / distil-*）与下载目录 |
transcribe_settings |
ASR 引擎选择 (local / api)、语言、Beam Size、VAD 静音过滤、温度采样、幻觉抑制阈值等高阶参数 |
vad_settings |
VAD 过滤开关与高级 VAD 参数 |
ffmpeg_settings |
音轨选择 (audio_track)、时间范围裁剪 (start_time / end_time) |
llm_settings |
LLM 引擎选择 (api / local)、API 多方案池（含并发数、批次大小、超时、System Prompt）；local_settings 包含 GGUF 模型路径、GPU 加速层数、上下文长度与闲置释放时间；target_language 翻译目标语言 |
online_asr_settings |
云端 ASR API 多方案池、说话人识别 (speaker_labels)、词级时间戳 (word_timestamps) |
library |
媒体库扫描路径、格式白名单（20+ 种）、自动扫描开关 |
所有配置均可通过 WebUI 在线修改并即时生效。
| 类型 | 格式 |
|---|---|
| 视频 | .mp4 .mkv .avi .mov .flv .wmv .webm .ts .m2ts .rmvb .vob .asf |
| 音频 | .mp3 .wav .m4a .flac .aac .ogg .wma .opus |
| 字幕 | .srt（拖拽或上传已有字幕直接进入翻译阶段） |
| 规模 | 推荐场景 |
|---|---|
tiny / base |
快速测试、低配设备 |
small / medium |
均衡精度与速度 |
large-v2 / large-v3 |
最高精度（默认 large-v2） |
distil-* |
蒸馏模型，推理更快、显存占用更低 |
访问
/docs可查看自动生成的 Swagger 交互式文档。
| 方法 | 端点 | 说明 |
|---|---|---|
GET |
/api/system/info |
系统信息（GPU 检测） |
GET |
/api/config |
获取完整配置 |
POST |
/api/config |
更新配置 |
POST |
/api/config/restore |
恢复默认配置 |
POST |
/api/proxy/test |
代理连通性测试 |
GET |
/api/languages |
获取支持语言列表 |
GET |
/api/models |
获取 Whisper 模型列表 |
DELETE |
/api/models/{model_id} |
删除已下载模型 |
POST |
/api/models/{model_id}/download |
下载指定模型 |
GET |
/api/models/download_status |
模型下载进度 |
POST |
/api/llm/models |
获取远程 LLM 模型列表 |
GET |
/api/llm/local_models |
获取本地 GGUF 模型列表 |
POST |
/api/asr/models |
获取云端 ASR 模型列表 |
| 方法 | 端点 | 说明 |
|---|---|---|
POST |
/api/upload/{asset_type} |
上传资产（video / audio / srt） |
POST |
/api/task/execute |
执行任务流水线 |
POST |
/api/task/{task_id}/retry |
断点重试任务 |
GET |
/api/download/{task_id}?type= |
下载产物（original / translated） |
GET |
/api/task/{task_id}/assets |
获取单个任务资产信息 |
GET |
/api/tasks |
获取所有任务列表 |
DELETE |
/api/task/{task_id} |
删除任务及全部资产 |
DELETE |
/api/task/{task_id}/asset/{asset_type} |
删除单个资产 |
POST |
/api/tasks/reorder |
任务排序 |
POST |
/api/task/{task_id}/cancel |
中断单个任务 |
POST |
/api/tasks/cancel_all |
中断全部任务 |
| 方法 | 端点 | 说明 |
|---|---|---|
GET |
/api/library/paths |
获取扫描路径列表 |
POST |
/api/library/paths |
添加扫描路径 |
DELETE |
/api/library/paths |
删除扫描路径 |
POST |
/api/library/scan |
触发媒体库扫描 |
GET |
/api/library/discoveries |
获取已发现文件 |
POST |
/api/library/import |
批量导入为任务 |
| 方法 | 端点 | 说明 |
|---|---|---|
WS |
/ws/progress/{task_id} |
任务实时状态推送 |
GET |
/api/task/{task_id}/status |
HTTP 轮询任务状态 |
GET |
/api/pipeline/status |
全局流水线状态 |
├── api/ # FastAPI 后端
│ ├── routers/ # Web API 路由 (config, tasks, library, websocket)
│ ├── services/ # 业务逻辑层 (配置、调度、工作区、媒体库)
│ ├── workers/ # 异步队列消费者 (提音、识别、翻译)
│ ├── state.py # 全局状态管理
│ └── ws_manager.py # WebSocket 连接管理器
├── core/ # 底层算法库 (FFmpeg、Whisper、API转录、翻译、SRT格式化、本地LLM)
│ └── local_llm_manager.py # 本地 LLM 推理管理器 (GGUF / llama-cpp-python)
├── frontend/ # Vue 3 前端 (CDN 模式，免构建)
│ └── js/components/ # UI 组件 (工作区、ASR、翻译、控制台、设置)
├── config/ # 配置文件 (自动生成 config.json)
├── .github/workflows/ # CI/CD (Docker 发布)
├── models/ # Faster-Whisper 离线模型 & 本地 LLM 存储
│ └── llm/ # GGUF 量化模型存放目录
├── workspace/ # 音视频及字幕任务产物
├── app.py # WebUI & API 后端启动入口
├── requirements.txt # 生产依赖
├── docker-compose.yml # Docker Compose 编排
├── Dockerfile # CPU Docker 镜像
└── Dockerfile.gpu # GPU (CUDA) Docker 镜像
| 维度 | 要求 |
|---|---|
| 操作系统 | Windows 10+ / Linux |
| Docker | 支持 linux/amd64 (GPU 版需具备 NVIDIA Runtime) |
| Python | 3.9 - 3.13（推荐 3.12.x） |
| 硬件(推荐) | 至少 8GB 内存；使用本地 GPU 引擎推荐至少 6GB+ 显存的 NVIDIA 显卡 |
Docker 权限说明：如果在 NAS (如群晖、Unraid 等) 上部署遇到读写权限的问题，增加环境变量
-e PUID=1000和-e PGID=1000(替换为实际的 UID/GID)，容器将会自动对齐挂载目录的读写权限。
- API 自动轮询与故障自愈：在遇到可恢复错误（如 HTTP 429/401）时，自动切换方案池中的下一个可用方案。
- 任务插队与优先级调度：后端队列支持紧急任务优先处理。
- 全局队列进度透明化：流水线看板显示具体进度百分比与子状态（如"正在提音 45%"）。
- 翻译断点续传与语义缓存：引入基于原文 MD5 缓存机制，翻译中断后跳过已完成段落，避免重复消耗 API 额度。
- SRT 格式对齐算法优化：增强翻译后 SRT 组装逻辑，应对 LLM 输出行数不一致的情况。
完整规划与已完成的特性请见 文档站 - 更新日志。
- 合法使用：本项目仅供技术研究、个人视频剪辑与字幕制作辅助使用。
- 接口规范：请用户自行准备合规的 LLM API 及云端识别 API，确保使用不违反当地法律法规及服务商的使用条款。
- 开源许可：本项目基于 MIT 协议开源，完全免费，由第三方模型引起的任何输出内容问题概不负责。