Skip to content

detailed_architecture.md

Latest commit

 

History

History
153 lines (131 loc) · 8.19 KB

detailed_architecture.md

File metadata and controls

153 lines (131 loc) · 8.19 KB

PC端实时屏幕翻译工具：详细功能与技术方案

1. 项目目标

  • 为桌面端用户提供字幕级实时翻译体验，在不中断原有视频播放的前提下展示双语字幕。
  • 支持 Windows/macOS 双平台，覆盖多种源语言（英文、日文、韩文等）与中文目标语言。
  • 采用模块化设计，便于后续扩展新特性（多目标语言、团队协作、云端同步等）。

2. 用户场景与交互流程

  1. 用户启动应用，授予屏幕录制权限，并在主界面配置 API Key、Endpoint、源语言等参数。
  2. 用户点击“选择字幕区域”，拖拽选择屏幕原字幕区域。
  3. 用户点击“选择显示区域”，拖拽翻译字幕展示窗口位置。
  4. 用户点击“开始”，后台线程进入抓取→OCR→翻译→渲染循环。
  5. 实时翻译结果以覆盖层形式显示在目标区域，可随时暂停或调整设置。
  6. 日志面板展示最近的 OCR 结果、翻译调用状态与错误信息，便于排查问题。

3. 功能清单

3.1 核心功能

  • 区域选择：半透明遮罩＋矩形拖拽，分别记录源字幕区域与翻译显示区域。
  • 实时屏幕捕捉：按照设定频率获取源区域截图，支持跨平台热键触发。
  • OCR 识别：调用 EasyOCR（或可替换 OCR 引擎）识别字幕文本，支持多语言切换与自定义置信度阈值。
  • 去重与缓存：对连续帧进行去重，避免重复翻译，提高性能。
  • 翻译调用：对接 OpenAI 格式接口，支持自定义模型、温度、最大 token 等参数。
  • 结果渲染：透明置顶窗口实时刷新翻译文本，支持字体、颜色、滚动等样式自定义。

3.2 辅助功能

  • 配置管理：本地持久化 API Key、Endpoint、语言偏好、刷新频率、样式设定。
  • 日志与提示：UI 中展示状态（运行中、暂停、失败）、错误消息与调试日志。
  • 快捷键支持：定义全局热键，快速开始/停止翻译或重新选择区域。
  • 任务栏/托盘集成：托盘菜单展示运行状态、入口配置与退出操作。

3.3 进阶功能（规划）

  • 多语言译文并行显示，满足多目标语言需求。
  • 字幕滚动历史与保存功能，便于复盘。
  • 云端同步配置，支持多设备共享设置。
  • 插件接口，供高阶用户接入自定义翻译或后处理逻辑。

4. 技术架构概览

  • 表现层：PyQt6/PySide6 实现主控窗口、区域选择器、翻译覆盖层。
  • 应用层：MainApp 管理生命周期、配置、事件绑定；TranslationEngine 管理后台循环；DisplayOverlay 管理渲染。
  • 基础服务层：屏幕捕捉器（mss 或系统 API）、OCR 处理器（EasyOCR）、翻译协调器（requests 调用外部 API）。
  • 支持服务：配置读取/写入模块、日志模块、缓存模块（去重）、错误与告警模块。

5. 模块设计

5.1 MainApp

  • 负责 UI 初始化、配置加载、模块实例化。
  • 管理按钮事件：区域选择、开始/停止、设置面板。
  • 与 TranslationEngine 通过信号/回调交互，接收翻译结果并交给 DisplayOverlay。

5.2 RegionSelector

  • 基于全屏透明窗口，捕获鼠标拖拽事件。
  • 以 QRect 形式返回坐标与尺寸，并对结果进行归一化处理。
  • 支持 ESC/右键取消与重新选择逻辑。

5.3 TranslationEngine

  • 运行在独立线程或使用 QThread 包装，避免阻塞 UI。
  • 循环步骤：
    1. capture_screen_area(rect) → 获取 numpy 数组格式图像。
    2. ocr_reader.readtext(image) → 提取文本与置信度。
    3. 文本清洗（去空格、合并行、过滤低置信度结果）。
    4. 判断是否与上一轮结果相同，若不同进入翻译。
    5. translate_text(text) → requests 调用外部 API，处理超时重试。
    6. 通过回调向 UI 层发送翻译结果与原文，供显示与日志使用。
  • 提供可配置的刷新频率、重试策略、最大队列长度。

5.4 DisplayOverlay

  • 无边框透明窗口，总在最前，大小位置绑定目标区域。
  • QLabel 显示文本，支持多行、描边、阴影等样式，避免与背景混淆。
  • 可根据用户配置调整字体、颜色、背景透明度。
  • 支持淡入淡出或平滑滚动效果，提升用户体验。

5.5 配置与持久化

  • 采用 JSON/YAML 存储（如 settings.json）。
  • 提供加载、验证、保存接口，敏感信息（API Key）可加密存储或提示用户加密。

5.6 日志与监控

  • 使用 Python logging 模块记录运行状态、错误、请求耗时。
  • UI 提供日志面板或弹窗提醒重要错误。
  • 预留接入 Sentry 等远程监控的接口（可选）。

6. 数据流与处理流程

UI 事件 → MainApp → TranslationEngine.start()
           ↓
    ScreenCapturer → OCRProcessor → TextCache
           ↓                 ↓
    TranslationCoordinator (API 调用)
           ↓
      主线程回调 → DisplayOverlay.update_text()
  • 所有跨线程通信通过信号槽或线程安全队列完成。
  • 控制循环周期，确保 OCR/翻译耗时不会导致堆积。

7. 技术选型与依赖

需求 方案/库 说明
GUI PyQt6 / PySide6 跨平台、支持透明窗口与托盘
屏幕捕捉 mss 性能好，封装简洁
OCR EasyOCR 多语言支持，可替换为 PaddleOCR/Tesseract
翻译 API requests + 自定义封装 兼容 OpenAI 接口格式，可扩展 Azure/OpenRouter
配置持久化 json/yaml + pathlib 简单可靠
日志 logging + rotating log 支持文件与控制台输出
打包 PyInstaller 支持 Windows/macOS 可执行文件

8. 性能优化策略

  • 并发设计：隔离 UI 与后台处理线程，必要时引入线程池或 asyncio。
  • 缓存机制：基于 hash 或文本对比的去重，避免重复翻译。
  • 批处理：对于多段字幕可批量请求翻译 API，减少网络往返。
  • 资源复用：OCR 模型初始化一次，多次复用，避免重复加载。
  • 降级策略：API 超时或失败时降级显示原文或提示，避免应用崩溃。

9. 安全与隐私

  • 明确提示用户授权屏幕录制权限，并说明数据仅用于前端翻译，不做持久化。
  • API Key 加密存储或要求用户每次启动输入，避免明文保存在磁盘。
  • 网络请求使用 HTTPS，支持自定义 API Endpoint 证书验证（可配置忽略但默认启用）。

10. 配置管理

  • 配置项示例：
    • api.endpoint
    • api.key
    • translation.source_language
    • translation.target_language
    • engine.interval_ms
    • overlay.font_size
    • overlay.background_alpha
  • 提供导入/导出配置功能，方便迁移。

11. 日志与监控

  • 日志级别：DEBUG/INFO/WARNING/ERROR。
  • 关键事件：OCR 结果、翻译请求耗时、失败重试、权限异常。
  • 可选：集成远程错误上报（Sentry）或本地日志查看器。

12. 测试策略

  • 单元测试：覆盖配置解析、文本处理、缓存逻辑。
  • 集成测试：模拟 OCR 输出与翻译 API 返回，验证管道串联。
  • UI 测试：使用 Qt Test 或截图对比验证覆盖层渲染。
  • 性能测试：脚本对不同帧率、字幕密度进行压测，记录延迟与 CPU 占用。

13. 打包与发布

  • 使用 PyInstaller 生成平台特定可执行文件，编写 .spec 文件定义资源、数据文件。
  • macOS 需处理代码签名、公证；Windows 需附带 VC++ 运行库依赖提示。
  • 发布 artifacts 前进行最终测试，确保配置、权限、字体资源完整。

14. 项目里程碑计划

  1. M1 核心功能（2 周）
    • 完成 UI 框架、区域选择、基础翻译循环。
  2. M2 功能整合（2 周）
    • 增强配置管理、日志展示、快捷键、错误处理。
  3. M3 性能与 UX 优化（2 周）
    • 引入缓存、样式自定义、历史字幕、托盘支持。
  4. M4 打包与发布（1 周）
    • 完成打包脚本、跨平台测试、文档与发布说明。