X Spaces 实时字幕翻译

Chrome Manifest V3 扩展，支持两种实时翻译方式：

• 按 twspace-crawler 核实的协议读取 X Spaces 字幕：拦截 chatToken → accessChatPublic 换 endpoint → 轮询 chatapi/v1/history → 只解析 final 行并带时间轴。
• 捕获当前 X 标签页音频，通过 Groq Whisper 语音识别后翻译。

文本翻译默认使用谷歌在线翻译，也支持 OpenAI 兼容接口。

安装

npm install
npm run build

1. 打开 chrome://extensions，启用“开发者模式”。
2. 点击“加载已解压的扩展程序”，选择本项目的 dist/。
3. 点击扩展图标旁的菜单进入“扩展程序选项”，在“识别来源”中选择：
   • Show captions 字幕翻译（默认）：无需 Groq Key。打开 X Space 并开启 Show captions，点击扩展图标即可显示翻译浮窗。字幕来自服务端数据流，不抓页面 DOM。
   • 音频转文字翻译：填写 Groq API Key 并保存。回到正在播放的 X Space，点击扩展图标开始识别，图标显示 ON。
4. 浮窗中灰色小字按「昵称 @账号：原文」显示，白色文字为中文翻译。昵称和账号保持原文且不参与翻译；说话人从 Space 参与者头像旁读取，不显示 Bio，无法识别时仅显示发言内容。
5. 浮窗顶部可直接切换「Show captions / 音频识别」。切到字幕会自动停止音频并恢复字幕监听；切到音频后需按浮窗提示点击浏览器工具栏扩展图标开始捕获。
6. 浮窗可点击「暂停 / 开始」；音频模式下再次点击扩展图标或关闭浮窗可彻底停止音频捕获。
7. 两种模式不会同时运行，避免重复翻译；切换模式后无需刷新页面。

选择 OpenAI 时，Base URL 可填写 https://api.openai.com/v1、兼容服务的 /v1 或完整 /chat/completions 地址。本地服务仅允许 http://localhost 或 http://127.0.0.1。

Groq Key 仅用于语音转文字（STT），不是文字转语音（TTS）。默认模型为 whisper-large-v3-turbo，可在设置页调整 2–15 秒的音频分片时长。

开发与验证

npm run typecheck
npm test
npm run test:coverage
npm run build

修改代码后需要重新构建，并在 chrome://extensions 中点击扩展的刷新按钮。

开发热更新

npm run dev

首次启动后，在 chrome://extensions 手动重新加载一次 dist/。之后保存 src/、 manifest.json 或 scripts/build.mjs 时会自动重新构建；构建成功后，扩展和已打开的 x.com / twitter.com 页面会自动重载。构建失败时不会刷新浏览器。

限制与排查

• 原生字幕模式拦截 SpaceById / live_video_stream 拿到 chatToken，再按 twspace-crawler 的路径换票并轮询 Chatman history。只展示 final 字幕，按 Space 开始时间对齐时间轴。若未捕获到 token，浮窗会显示「正在获取字幕数据流」，刷新 Space 页面即可。无字幕时请改用音频识别模式。
• 音频模式只在用户点击“开始音频识别”后捕获当前标签页；停止或关闭翻译浮窗会释放音频流。
• 音频分片会上传至 Groq。使用前请确认你有权处理相关内容，并遵守所在地法律及服务条款。
• 音频模式通常比 X 原生字幕多出数秒延迟；多人重叠讲话和专有名词可能降低准确率。
• 默认谷歌翻译使用 translate.googleapis.com 在线接口，受网络环境及服务策略影响，不保证永久可用。
• X 没有公开稳定的 Spaces 字幕 API。字幕通道依赖 Chatman endpoint / chat token；若 X 更改 SpaceById 或 live_video_stream 响应结构，需要更新 src/shared/chatman.ts。
• OpenAI 模式出现“尚未授权访问 API 域名”时，在设置页重新保存。出现 HTTP 错误时检查 Base URL、模型名、余额及 API Key。
• API Key 存放在 chrome.storage.local，不会进入 X 页面，但并非操作系统钥匙串加密。建议使用限额密钥。