# 在自己的电脑运行字幕程序

从[精选案例](<cases/subtitles.html>)下载[字幕服务源码包](<downloads/subtitle-service.zip>)，解压到一个独立目录。需要 Python 3.11 或 3.12；安装依赖和模型可能需要联网。

## 安装和启动

在解压后的程序目录运行：

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
Copy-Item .env.example .env
.\.venv\Scripts\python.exe -B run.py
```

`Copy-Item` 只用于首次创建配置文件。已有 `.env` 时保留自己的配置。

示例配置默认使用 CPU、int8 和 base 语音模型，首次运行允许下载。可以在 `.env` 设置 `VIDEO_ROOT`，或使用网页上传文件。服务启动后在本机打开 `http://127.0.0.1:8765`；API 文档位于 `/docs`。

## 翻译配置

Whisper 负责原文识别。逐段中文翻译需另外配置兼容 Chat Completions 的模型接口：

```dotenv
TRANSLATION_BASE_URL=填入服务的API根地址
TRANSLATION_MODEL=填入可用的模型名称
TRANSLATION_API_KEY=填入自己的密钥
```

也可使用自己的本地模型服务。未配置翻译时传 `translate=false`，先提取原文。原文完成后通过任务重试补做中文翻译。服务配置是否完整与外部模型是否连通，需要分别检查。

本项目已有批处理采用本地 Argos en→zh 1.9 模型；下载的通用 API 源码包不包含模型文件、原始视频、私有配置或已有任务数据库。

## Agent 客户端

```python
from agent_client import SubtitleClient

with SubtitleClient("http://127.0.0.1:8765") as client:
    job = client.submit_path("lesson.mp4", language="en", translate=False)
    client.wait(job["id"], timeout=7200)
    result = client.result(job["id"])
    client.download(job["id"], "./output")
```

路径提交读取服务端视频目录，客户端上传则读取调用者电脑上的文件。保存任务 ID 后可以继续轮询，无需重复创建任务。

## 工程检查

```powershell
.\.venv\Scripts\python.exe -B -m unittest discover -s tests -v
```

这些测试覆盖服务协议与错误恢复，不能替代外部翻译质量评价。默认服务只监听本机；如需给其他电脑调用，按程序配置要求设置访问令牌和监听地址。

参考：[faster-whisper](<https://github.com/SYSTRAN/faster-whisper/tree/v1.2.1>) · [FastAPI 上传](<https://fastapi.tiangolo.com/tutorial/request-files/>) · [Argos 模型索引](<https://github.com/argosopentech/argospm-index>)