DSH YouTube Bilingual Subtitles

Natural bilingual captions for YouTube, powered by DeepSeek Harness.

> Experimental and unofficial. This project observes caption text already rendered in the YouTube page. YouTube does not provide a supported API for reading arbitrary viewers' live caption text. DOM selectors can change, and users are responsible for reviewing YouTube's terms before use or distribution.

![Project demo](docs/images/demo.png)

Why this exists

Automatic captions often arrive as fragments, repeat words, and revise their last few tokens. Translating every DOM mutation produces choppy subtitles. This project first stabilizes and deduplicates the English stream, then asks DeepSeek to segment complete thoughts and translate them naturally.

Highlights

Streaming correction handling: captions become eas becomes captions become easier, not two phrases.
Context-aware sentence segmentation instead of word-by-word translation.
English and translated lines rendered in an isolated Shadow DOM overlay.
DeepSeek API credentials stay inside Harness and never enter the extension.
Loopback-only bridge, fixed extension origin, automatic short-lived bearer pairing.
No telemetry and no subtitle persistence by default.
Clear source-only fallback when the model is offline, rate-limited, or unconfigured.

Requirements

DeepSeek Harness 0.1.0-rc.6
Node.js 22.19+ or 24+
Chrome 144+
A working model route in Harness (default: deepseek-official / deepseek-v4-flash)

Quick start from a GitHub Release

1. Open the v0.1.0-alpha.2 release and download both assets: - dsh-youtube-bilingual-subtitles-0.1.0-alpha.2.tgz - dsh-youtube-bilingual-subtitles-chrome-0.1.0-alpha.2.zip 2. Install the Harness bundle:

``powershell dsh plugin --profile web add .\dsh-youtube-bilingual-subtitles-0.1.0-alpha.2.tgz dsh web ``

Keep this terminal running while subtitles are in use.

3. Extract the Chrome ZIP. 4. Open chrome://extensions, enable Developer mode, choose Load unpacked, and select the extracted folder containing manifest.json. 5. Open the extension's Options, click Save and test connection. 6. Open a YouTube video, turn on English CC, and start watching.

No API key is copied into Chrome. The extension automatically pairs with the loopback Harness plugin. The Harness package and Chrome ZIP must come from the same release. After an upgrade, restart dsh web and reload the unpacked extension on chrome://extensions.

Local development

git clone https://github.com/yun-zhi-dao/dsh-youtube-bilingual-subtitles.git
cd dsh-youtube-bilingual-subtitles
corepack pnpm install
corepack pnpm run check
.\scripts\install-local.ps1

The install script validates the project, installs it into the web DSH profile, and prints the exact Chrome extension folder.

Architecture

Visible YouTube caption DOM
  -> isolated MV3 content script
  -> extension service worker
  -> authenticated 127.0.0.1 Harness route
  -> token stabilization and adaptive segmentation
  -> ctx.llm.stream (DeepSeek)
  -> validated bilingual cue
  -> Shadow DOM overlay

The plugin intentionally does not reuse Harness /api. It owns a narrow /youtube-bilingual/v1 route and refuses to load when the Harness Web server is bound beyond 127.0.0.1.

Privacy and security

The extension sends only visible caption text, minimal timing, and an ephemeral session identifier to the user-selected local Harness endpoint. It does not send video URLs, titles, channel names, account details, cookies, or browsing history. See [PRIVACY.md](PRIVACY.md) and [SECURITY.md](SECURITY.md).

The extension has only these scopes:

content script: https://www.youtube.com/*
network host: http://127.0.0.1/*
permission: storage

There is no remote JavaScript, eval, analytics, advertising, or background transcript database.

Troubleshooting

Symptom	Resolution
`HTTP 403` while testing the connection	Install the Harness package and Chrome ZIP from the same release, restart `dsh web`, then reload the unpacked extension. Versions before `0.1.0-alpha.2` also rejected a valid Chrome health check when Chromium omitted its Origin header.
Harness is offline	Start `dsh web` and keep that terminal running.
No captions detected	Turn on English CC in the YouTube player; some videos do not provide captions.

Known limitations

YouTube caption DOM is undocumented and may change without notice.
Only captions currently rendered by YouTube are processed; this is not speech recognition.
Not every video or live stream provides English captions.
The initial release is distributed as an unpacked extension, not through Chrome Web Store.
Translation latency and cost depend on the configured model and network.

Uninstall

.\scripts\uninstall-local.ps1

Then remove the extension from chrome://extensions.

License

[MIT](LICENSE). YouTube is a trademark of Google LLC. This project is not affiliated with or endorsed by Google, YouTube, or DeepSeek.

Source facts

Install

Check the source files