根据您提供的GitHub仓库信息，WhisperSubTranslate 是一款完全免费、本地运行的开源桌面应用。它的核心功能是从视频中提取语音并生成字幕（SRT文件），然后将其翻译成多种语言。整个过程无需联网、无需注册，且没有使用次数限制。

以下是一份详细的部署和使用教程。

🛠️ 第一步：系统要求与准备

在开始之前，请确保您的电脑满足以下基本要求：

  • 操作系统: Windows、macOS 或 Linux。
  • Node.js 环境 (如需从源码运行): 版本需要 22.12.0 或更新。你可以在终端中运行 node -v 来检查版本。
  • 显卡 (可选，用于加速):
    • NVIDIA GPU: 建议安装 CUDA Toolkit 以获得更快的处理速度。
    • AMD 或 Intel GPU: 应用会使用 Vulkan 进行加速。
    • 无独立显卡: 应用会自动回退到 CPU 处理，速度会慢一些，但依然可用。

📥 第二步：下载与安装

根据你的使用需求，有两种主要方式获取应用。

方式一：直接下载安装包 (推荐给普通用户)

这是最简单快捷的方式，无需任何命令行操作。

  1. 访问该项目的 Releases 页面（通常在 GitHub 仓库右侧的 “Releases” 标签下）。
  2. 下载最新版本的压缩包（例如 WhisperSubTranslate-win-x64.zip 或对应你系统的版本）。
  3. 将压缩包解压到你想要的文件夹（例如 D:\WhisperSubTranslate）。
  4. 进入解压后的文件夹，双击运行 WhisperSubTranslate.exe (Windows) 或对应的可执行文件即可启动应用。

方式二：从源码运行 (推荐给开发者)

如果你想获得最新代码或进行二次开发，可以按照以下步骤操作。

  1. 克隆仓库:

    1
    2
    git clone https://github.com/Blue-B/WhisperSubTranslate.git
    cd WhisperSubTranslate

  2. 安装依赖:

    1
    npm install
    • 注意: 在 Windows 上，此步骤会自动下载 whisper.cpp (CUDA 和 Vulkan 版本，体积较大，约 700MB)。在 Linux 上，whisper.cpp 会从源码编译，你需要提前安装 cmake、build-essential 等工具。

  3. 启动应用:

    1
    npm start

🚀 第三步：初始配置与模型下载

首次启动应用时，需要进行一些必要的配置，主要是下载语音识别模型。

  1. 选择模型: 应用启动后，在设置或主界面中，你需要选择一个语音识别模型。默认推荐 large-v3-turbo，它在速度和准确率上取得了很好的平衡。你可以根据你的显卡显存（VRAM）大小选择合适的模型：
    • 显存 < 2GB: 选择 tiny, base 或 small 模型。
    • 显存 2GB - 4GB: 选择 medium 或默认的 large-v3-turbo。
    • 显存 >= 4GB: 可以选择 large-v3 以获得最佳识别效果。
    • 字幕同步问题: 如果生成的字幕时间轴不准，可以尝试 large-v2 Sync 模型（首次使用会自动下载额外的同步引擎）。
  2. 自动下载: 选定模型后，应用会自动开始下载对应的模型文件（大小从75MB到4.4GB不等），并存放到 _models 文件夹中。请耐心等待下载完成。

🎬 第四步：生成与翻译字幕

模型准备就绪后，就可以开始处理视频了。

  1. 添加视频: 点击应用主界面的 “添加视频” 或 “+” 按钮，选择你需要处理的本地视频文件。
  2. 选择识别语言 (可选): 如果视频中的语音主要是某种语言，你可以在设置中指定，这有助于提高识别准确率。如果不确定，可以选择“自动检测”。
  3. 选择翻译引擎和目标语言:
    • 离线翻译 (免费、私密): 选择 “Hy-MT2 (local)”。这是应用内置的本地翻译模型，完全离线，无需API密钥，且免费无限使用。你可以在设置中选择 1.8B 或 7B 版本（7B版本更大，更准确，但需要更多显存）。
    • 在线翻译 (需要API密钥): 你可以选择 MyMemory (免费，但有每日字符限制)、DeepL、OpenAI GPT、Gemini 或 Claude。选择这些引擎时，你需要在设置中输入对应的 API密钥。注意，这些服务可能产生费用。
  4. 开始处理: 点击 “开始” 或 “生成字幕” 按钮。应用会先进行语音识别生成原始字幕，然后自动调用你选择的翻译引擎进行翻译。
  5. 查看结果: 处理完成后，你可以在应用界面预览生成的 .srt 字幕文件，并可以将其保存到本地。

⚙️ 重要配置与数据位置

  • 数据存储: 所有模型、设置和任务历史都保存在本地，不会上传。
    • Windows: %APPDATA%\whispersubtranslate\
    • 配置文件: translation-config-safe.json (包含你的API密钥，通过系统安全存储加密)
    • 任务历史: history.json (最多保存200条记录)
  • 便携模式: 如果你想在U盘上使用，可以在应用根目录下创建一个名为 portable-data/ 的文件夹，所有数据将保存在此，而非系统盘。
  • Linux 密钥环: 在Linux上，API密钥安全存储依赖于 gnome-keyring。在无图形界面的SSH会话中，应用会降级为不安全的存储方式并发出警告。

❓ 常见问题与提示

  • 处理速度慢: 这是本地处理的正常现象，尤其在使用CPU或大模型时。建议关闭其他占用GPU或CPU资源的程序。
  • 字幕时间轴不准: 尝试使用 Sync 系列模型，它们专为修正同步问题而设计，对非英语（如日语、韩语、中文）视频效果更好。
  • 翻译质量: 离线模型 (Hy-MT2) 的质量在标准测试中可与主流商业API媲美。在线引擎（如DeepL、GPT）在处理复杂上下文时可能更有优势。
  • 日志查看: 如果遇到错误，可以查看 %APPDATA%\whispersubtranslate\logs\errors.log 文件以获取详细信息。

🔧 开发者构建

如果你想自己构建Windows安装包，可以在项目根目录下运行：

1
npm run build-win

构建产物将输出到 dist2/ 文件夹。

现在，你已经完成了所有部署步骤。启动应用，导入你的第一个视频，开始生成并翻译字幕吧！如果你在使用中遇到问题，可以查阅项目的 CONTRIBUTING.md 或在GitHub仓库提交Issue。