🎌 Netflix Furigana

A Chrome extension to learn Japanese while watching Netflix — furigana above kanji, hover tooltips with definitions, JLPT levels, and parts of speech.

Note: This is a vibe coded project — it works, but there may be hiccups. Use at your own risk and feel free to open issues.

---

⚠️ Required First Step — Bundle Kuromoji

Netflix blocks external CDN scripts via its Content Security Policy. You must bundle Kuromoji locally before the extension works. Open a terminal in this folder and run:

npm install kuromoji
cp node_modules/kuromoji/build/kuromoji.js src/kuromoji.js
cp -r node_modules/kuromoji/dict dict

This copies the tokenizer (~2MB) and dictionary files into the extension. Do this once.

---

🚀 Install in Chrome

1. Complete the Required First Step above
2. Open Chrome → chrome://extensions
3. Enable Developer Mode (top-right toggle)
4. Click Load unpacked → select this folder
5. Open Netflix, play a show with Japanese subtitles
6. Hover any word to see its definition. Press F to toggle furigana!

---

⌨️ Keyboard Shortcuts

Key	Action
F	Toggle furigana on/off
J	Toggle dual subtitles (Japanese on top)
Esc	Close tooltip

---

🈺 Dual Subtitles

Watch with subtitles in your language while the official Japanese subtitles (with furigana and hover dictionary) appear on a line just above them. Great for e.g. Chinese or English subs + Japanese on top.

• Toggle with the J key or the popup switch (off by default)
• Uses only Netflix's official Japanese subtitle track — no machine translation
• Works even with subtitles turned off (the Japanese line sits near the bottom of the video)
• When your selected subtitles are already Japanese, the dual line hides itself (the normal furigana overlay handles them)

How it works: a small script captures Netflix's own playback manifest, which lists every available subtitle track, then downloads the official Japanese WebVTT track and syncs it to the video locally.

Limitations:

• The title must actually offer Japanese subtitles on Netflix
• If you install or reload the extension while a video is already playing, refresh the page so the manifest can be captured

---

🔧 How It Works

Netflix Subtitle DOM
        │
        ▼
 MutationObserver (watches for subtitle changes)
        │
        ▼
  Kuromoji.js (local bundle — CSP safe)
  Splits Japanese text into words + readings
        │
        ▼
  <ruby> tags wrap kanji with <rt> furigana
        │
        ▼
  Hover → Jisho API lookup
  (definitions, JLPT, parts of speech)
        │
        ▼
  Tooltip displayed near hovered word

If subtitles stop being processed

Netflix occasionally changes their player DOM. If it breaks, open DevTools on Netflix, inspect the subtitle text element, and update SUBTITLE_SELECTORS in src/content.js to match the new class names.

---

⚠️ Known Issues

Extension may not work in full screen

The extension may not work when using Netflix's built-in full screen button. If furigana or tooltips disappear, exit full screen and use F11 or Chrome's full screen option instead.

Name furigana only works from the start of an episode

Netflix annotates character names with official furigana the first time they appear on screen. The extension captures these as it sees them and remembers them for the session (nameMemory). If you start watching mid-episode — or skip past the scene where a name is first introduced — that name won't be in memory.

When a name is unknown, kuromoji will fall back to guessing: it splits the kanji individually and applies its own readings, which are often wrong for proper nouns.

Workaround: Start from the beginning of an episode. Name introductions almost always happen early.

A proper fix would require a pre-built name dictionary — technically doable but not yet implemented.

---

📚 Dictionary

Definitions come from the Jisho.org API (JMdict — 200k+ entries). Results are cached per session so each word is only fetched once.

---

🗂 File Structure

netflix-japanese/
├── manifest.json
├── dict/                  ← Created by npm install step
├── src/
│   ├── kuromoji.js        ← Created by npm install step
│   ├── kuromoji-bundle.js
│   ├── content.js
│   ├── content.css
│   ├── page-hook.js       ← Runs in the page context; captures subtitle tracks
│   ├── popup.html
│   └── popup.js
└── icons/