Bilingual-Subtitle-Extension

KO | EN

gitlite — search

#hacktoberfest #python #hacktoberfest2021 #javascript #golang #typescript #java #html #linux #hacktoberfest-accepted #css #config

Bilingual-Subtitle-Extension

★ 150 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Bilingual Subtitles for YouTube</h1>

Original English captions above, Simplified Chinese translations below, timed from YouTube caption cues.

Preview captured on <a href="https://www.youtube.com/watch?v=rB9ql0L0cUQ">YouTube Creators</a>.

Bilingual Subtitles is a dependency-free Chrome extension that displays an English caption line with a DeepSeek-generated Simplified Chinese translation directly below it.

The extension works from YouTube caption tracks rather than transcribing audio. It captures caption data from the player, translates adjacent lines in contextual batches, prioritizes work near the current playback position, and stores completed translations locally for later viewing.

> [!NOTE]
> Version 0.1.0 supports DeepSeek only and is installed as an unpacked Chrome extension.

## Contents

- [Highlights](#highlights)
- [Requirements](#requirements)
- [Installation](#installation)
- [Setup](#setup)
- [Usage](#usage)
- [Privacy and permissions](#privacy-and-permissions)
- [Compatibility](#compatibility)
- [Troubleshooting](#troubleshooting)
- [Technical design](#technical-design)
- [Development and validation](#development-and-validation)
- [Contributing](#contributing)
- [License and disclaimer](#license-and-disclaimer)

## Highlights

- **Stacked bilingual display** - shows the original English caption above its Simplified Chinese translation.
- **Player-first caption capture** - observes caption responses requested by YouTube's own player, including POT-bearing requests.
- **Fallback caption acquisition** - can try the track URL directly or reuse a POT-bearing URL already issued by the player.
- **Playhead-aware translation queue** - prioritizes the active batch, then upcoming batches, with older unseen work handled later.
- **Contextual batching** - sends adjacent caption lines together so the model has useful context while preserving line order.
- **Manual and automatic captions** - prefers a manual English track and falls back to an auto-generated English track.
- **Resumable local cache** - saves translated lines by video and caption track, including partial progress.
- **Failure isolation** - retries temporary API failures and splits malformed or truncated batches into smaller requests.
- **Playback-aware overlay** - resizes with the player, supports theater and fullscreen layouts, and hides during ads.
- **SPA navigation support** - starts a new session when YouTube changes videos without a full page reload.
- **Live popup status** - reports waiting, loading, translation progress, active state, and common configuration problems.
- **No dependencies or build step** - the extension is plain HTML, CSS, and JavaScript.

## Requirements

- Google Chrome 111 or newer.
- A desktop YouTube watch page at `https://www.youtube.com/watch`.
- A video with a manual or auto-generated English caption track.
- A [DeepSeek API key](https://platform.deepseek.com/api_keys) with available API quota.

DeepSeek bills API usage separately. Translation volume varies by video, selected model, and API behavior. Review the [current DeepSeek pricing](https://api-docs.deepseek.com/quick_start/pricing/) and your account usage before translating long videos.

## Installation

### Download the repository

Clone the project:

```bash
git clone https://github.com/CpfPatrick/Bilingual-Subtitle-Extension.git
```

Alternatively, [download the main branch as a ZIP file](https://github.com/CpfPatrick/Bilingual-Subtitle-Extension/archive/refs/heads/main.zip) and extract it.

### Load the extension

1. Open `chrome://extensions`.
2. Enable **Developer mode**.
3. Select **Load unpacked**.
4. Choose the repository folder containing `manifest.json`.
5. Reload any YouTube tabs that were already open.

Chrome injects the content scripts when a matching page loads. A YouTube tab opened before installation or extension reload must therefore be refreshed.

## Setup

1. Create or copy an API key from the [DeepSeek API keys page](https://platform.deepseek.com/api_keys).
2. Select the extension icon in Chrome.
3. Open **Settings**.
4. Paste the key into **DeepSeek API key**.
5. Keep `deepseek-v4-flash` as the model unless you intentionally want another compatible DeepSeek model.
6. Select **Test connection**.
7. Select **Save** after the connection succeeds.

The model field is editable. A custom model must be available to your DeepSeek account and compatible with the Chat Completions endpoint and JSON output.

## Usage

1. Open a regular YouTube watch page with English captions.
2. Confirm that **Bilingual subtitles** is enabled in the extension popup.
3. Start playback.
4. Open the popup to view caption-loading or translation progress.
5. Seek normally. Work that has not started will be reprioritized around the new playback position.
6. Disable the popup toggle when you want to return to YouTube's native caption display.

The extension may enable YouTube captions so the player issues a caption request. While the bilingual overlay is active, the native caption container is hidden to prevent duplicate text.

Disabling the extension removes the overlay and stops scheduling new translation work. API requests that were already sent may still finish.

### Translation cache

Successfully translated lines are written to `chrome.storage.local`. When the same video and caption track are opened again with a matching cue count, cached lines can be reused.

To remove stored translations:

1. Open the extension's **Settings** page.
2. Select **Clear translation cache**.

The cache uses video-and-track entries. When its index grows beyond 80 entries, the extension removes 20 of the least recently used entries.

## Privacy and permissions

### Data handling

- The DeepSeek API key is stored in `chrome.storage.local`.
- The key is not placed in Chrome sync storage.
- The API credential and selected model name are sent to `api.deepseek.com` for connection tests and translation requests.
- English subtitle text is sent to `api.deepseek.com` only when requesting a translation.
- Caption and watch-page metadata requests are made to YouTube as part of caption acquisition.
- Translations and cache metadata are stored locally.
- The enabled preference and selected model name are stored in `chrome.storage.sync` and may sync through Chrome when browser sync is enabled.
- The repository does not include analytics, advertising, tracking, or telemetry code.

Chrome local extension storage is not an operating-system keychain. Protect access to your browser profile and never commit an API key to the repository.

### Manifest access

| Manifest entry | Why it is needed |
|---|---|
| `storage` | Stores the API key, translation cache, enabled preference, and model preference. |
| `unlimitedStorage` | Allows the local translation cache to grow beyond the normal extension storage quota. |
| `https://api.deepseek.com/*` | Sends key tests and translation requests to DeepSeek. |
| `https://www.youtube.com/*` content-script match | Reads player and caption state, observes caption responses, and renders the overlay on YouTube. |

The DeepSeek endpoint is hardcoded in the background service worker. The content script cannot supply an arbitrary API destination.

## Compatibility

| Surface or feature | Status |
|---|---|
| Google Chrome 111 or newer | Supported |
| Desktop `www.youtube.com/watch` pages | Supported |
| Manual English captions | Supported and preferred |
| Auto-generated English captions | Supported as a fallback |
| YouTube SPA navigation | Supported |
| Theater mode | Supported |
| Fullscreen player | Supported |
| Video ads | Handled by pausing or hiding the overlay during the ad |
| Live streams | Not supported |
| YouTube Shorts | Not supported |
| Mobile `m.youtube.com` | Not supported |
| Embedded players | Not supported |
| Videos without English captions | Not supported |
| Audio transcription | Not provided |
| Source languages other than English | Not supported in version 0.1.0 |
| Target languages other than Simplified Chinese | Not supported in version 0.1.0 |
| Translation providers other than DeepSeek | Not supported in version 0.1.0 |

When several English tracks exist, the extension automatically selects the first manual track it finds, then the first auto-generated track. Version 0.1.0 does not include a track selector.

Other Chromium-based browsers may behave similarly, but this release targets and documents Google Chrome only.

## Troubleshooting

| Symptom | What to check |
|---|---|
| The popup says the extension is not running | Reload the YouTube tab. Tabs opened before installation or extension reload do not contain the content scripts. |
| The popup says to open a video | Use a regular `/watch?v=...` page. Home pages, Shorts, mobile pages, and embedded players are unsupported. |
| The API key is missing or rejected | Open **Settings**, confirm the key and model, run **Test connection**, and save the settings. Also check DeepSeek account quota. |
| The extension remains on loading subtitles | Confirm that the video has English captions, wait for any active ad to finish, and reload the page. |
| The overlay shows English but no translation | Translation may still be pending, or the key may be missing or rejected. Check the popup status. |
| Subtitles are unavailable for one video | Turn YouTube captions on once, reload the page, and retry. YouTube may not have exposed a usable caption response for that video. |
| Translation stops partway through | Check the popup for an API-key problem. Temporary network and server failures are retried, but a batch can still fail after the retry limit. |
| Cached text appears incomplete or stale | Open **Settings**, clear the translation cache, and reopen the video. |
| The popup reports a generic failure | Open the YouTube page's DevTools console and filter for `bsub`. Include relevant lines when reporting an issue. |
| Nothing changes after editing the source | Reload the extension at `chrome://extensions`, then refresh the YouTube tab. |

When filing a bug, include the Chrome version, a reproducible public video URL, the observed popup state, and relevant `bsub` console logs. Remove credentials and other sensitive data first.

## Technical design

```text
YouTube player
    |
    | timed-text fetch or XHR
    v
interceptor.js  [MAIN world, document_start]
    |
    | window.postMessage
    v
content.js      [isolated content-script world]
    |
    | chrome.runtime.sendMessage
    v
background.js   [Manifest V3 service worker]
    |                         |
    | DeepSeek API            | chrome.storage.local
    v                         v
translated batches       translation cache
    \                         /
     \                       /
      v                     v
       bilingual player overlay
```

### Caption acquisition

`interceptor.js` wraps the page's `fetch` and `XMLHttpRequest` functions before the YouTube player loads. It observes non-empty `/api/timedtext` responses and keeps a small buffer for responses captured before `content.js` begins listening.

Caption acquisition proceeds in this order:

1. Read any matching response already held in the interceptor buffer.
2. Ask the YouTube player to select the chosen English track and capture the resulting player request.
3. Fetch the selected caption track URL directly in `json3` format.
4. Reuse a POT-bearing timed-text URL previously issued by the player.

Track metadata is read from the live player API when possible. The MAIN-world bridge can also inspect `ytd-app` data and the initial player response. A same-origin watch-page HTML request provides a metadata fallback.

The extension rejects translated caption tracks, matches the current video and English track, parses `json3` events, merges contiguous duplicate ASR cues, and preserves caption timing.

### Translation pipeline

`content.js` groups cues into batches with both of these limits:

- At most 20 caption lines.
- At most 1,200 source characters.

Up to three batches can be in flight. The scheduler prioritizes a batch covering the current playback time, followed by future batches ordered by distance from the playhead. Pending batches behind the playhead are handled last.

`background.js` owns all DeepSeek traffic. Each request:

- Uses the configured DeepSeek model.
- Sends adjacent lines together for context.
- Requests a JSON object containing one translation per input line.
- Limits generated output to 4,000 tokens.
- Validates the translation array and expected line count.

Network failures and HTTP 429 or server errors use exponential backoff. Invalid, empty, mismatched, or truncated results can be retried and recursively split into smaller groups. Authentication failures pause new work until the key changes.

### Cache behavior

The cache key combines the YouTube video ID and caption-track identifier. Each entry records:

- The cue count.
- An array aligned with the source cues.
- A last-touched timestamp.

Successful partial results are retained so one failed section does not discard completed translations. A changed cue count is treated as a cache miss.

### Overlay behavior

The overlay is attached inside `#movie_player` and contains separate English, translated, and notice lines. Rendering follows the video element's current time and supports overlapping active cues.

A `ResizeObserver` adjusts text size with the player. Native YouTube captions remain enabled for caption acquisition but are hidden with CSS only while the bilingual renderer is active. Removing the active state restores native-caption visibility.

## Development and validation

The project has no package manager, dependency installation, bundling, or generated output.

### Project layout

| Path | Role |
|---|---|
| `manifest.json` | Manifest V3 configuration, permissions, scripts, popup, and options page. |
| `interceptor.js` | MAIN-world player bridge and timed-text interception. |
| `content.js` | Session lifecycle, track selection, caption parsing, batching, scheduling, and rendering. |
| `background.js` | DeepSeek client, retry behavior, API-key testing, and translation cache. |
| `overlay.css` | Native-caption hiding and bilingual-overlay styling. |
| `popup.html`, `popup.js` | Enable toggle and live session status. |
| `options.html`, `options.js` | API key, model, connection test, and cache controls. |
| `icons/` | Extension icons. |
| `docs/assets/` | README and documentation images. |

### Local development loop

1. Edit the source file.
2. Open `chrome://extensions`.
3. Select **Reload** for the extension.
4. Refresh the YouTube test tab.
5. Inspect the page console with the filter `bsub`.

Version 0.1.0 does not include an automated test suite. Validate behavior manually before opening a pull request.

### Manual validation checklist

- [ ] Install the extension in a clean Chrome profile.
- [ ] Save and test a valid DeepSeek key.
- [ ] Verify a video with manual English captions.
- [ ] Verify a video with auto-generated English captions.
- [ ] Confirm English appears above the translation.
- [ ] Seek forward while translation is still in progress.
- [ ] Navigate to another video without a full page reload.
- [ ] Enter and leave theater mode.
- [ ] Enter and leave fullscreen mode.
- [ ] Confirm the overlay is hidden during an ad and returns afterward.
- [ ] Disable and re-enable the popup toggle.
- [ ] Reopen a translated video and confirm cache reuse.
- [ ] Clear the cache and confirm translation can start again.
- [ ] Verify the missing-key and rejected-key states.
- [ ] Verify the no-English-caption notice.
- [ ] Verify the live-stream notice.
- [ ] Confirm native captions remain available when the extension is disabled or fails.

## Contributing

[Issues](https://github.com/CpfPatrick/Bilingual-Subtitle-Extension/issues) and pull requests are welcome.

1. Fork the repository.
2. Create a focused branch.
3. Make the smallest change needed for the intended behavior.
4. Reload the unpacked extension and complete the relevant manual checks.
5. Update documentation when user-visible behavior changes.
6. Open a pull request describing the problem, approach, and validation performed.

Please keep the README English-only, preserve the version 0.1.0 DeepSeek-only scope unless a change has been discussed, and never commit API keys, cached subtitle data, or private logs.

## License and disclaimer

This project is available under the [MIT License](LICENSE).

This extension is an independent project and is not affiliated with, endorsed by, or sponsored by YouTube, Google, or DeepSeek.

YouTube interfaces and DeepSeek API behavior, availability, model names, limits, and pricing may change without notice. Users are responsible for their API credentials, account usage, charges, and compliance with the applicable service terms.

Machine-generated translations can contain errors or omissions. Do not rely on them as the sole source for legal, medical, safety-critical, or other high-impact decisions.

Bilingual-Subtitle-Extension

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README