IINA Clickable Subtitles

Make subtitles clickable for language learning in IINA video player

This IINA plugin displays subtitles in a selectable overlay, allowing you to click words and phrases to look them up using macOS's built-in Dictionary and Translation features. Perfect for learning Hindi, Arabic, Chinese, or any language with complex scripts.

Features

• Selectable Subtitles: Click and drag to select subtitle text
• macOS Look Up Integration: Right-click or Force Touch selected text to:
  • Look up definitions in Dictionary.app
  • Translate to/from any language
  • Search the web
  • Access all macOS Look Up features
• Responsive Design: Automatically adjusts font size and contrast for any window size
• Optimized for Complex Scripts: Specially tuned for Devanagari (Hindi), Arabic, Chinese, and other non-Latin scripts
• Clean Display: Native IINA subtitles are automatically hidden to prevent overlap

Prerequisites

• IINA 1.4.1 or later (Download)
• macOS 10.15 or later (for Look Up features)
• Subtitle files in SRT format

Installation

Option 1: Download Pre-built Plugin (Recommended)

1. Download the latest clickable-subtitles.iinaplugin from the Releases page
2. Double-click the downloaded file to install
3. Restart IINA
4. The plugin will load automatically

Option 2: Install from Source

1. Clone or download this repository
2. Open Terminal and run:

   /Applications/IINA.app/Contents/MacOS/iina-plugin link /path/to/clickable-subtitles

3. Restart IINA

Usage

1. Open a video in IINA
2. Load subtitle file:
   • Drag and drop an SRT file onto IINA
   • Or right-click → Load → Load Subtitle File
3. Select subtitle text:
   • Click and drag to select words or phrases
4. Look up the selection:
   • Right-click → Look Up
   • Or Force Touch (trackpad) on the selected text
   • Or Ctrl+Cmd+D keyboard shortcut

Example: Learning Hindi

When watching Hindi content with Devanagari subtitles:

1. A word appears: "आइडिया" (idea)
2. Select the word with your cursor
3. Right-click → Look Up
4. See translation, transliteration, and definition

The plugin preserves all the fine details of Devanagari characters (मात्रा marks, conjuncts, etc.) for clear readability.

How It Works

The plugin:

1. Reads subtitle data from IINA's mpv backend every 100ms
2. Displays subtitles in a transparent overlay on top of the video
3. Enables text selection in the overlay
4. Hides IINA's native subtitles to prevent overlap
5. Lets macOS handle dictionary/translation lookups natively

Supported Subtitle Formats

• SRT (SubRip) - Fully tested and supported
• Other formats may work but are untested

Known Limitations

• Plugin restart: Changes to plugin files require restarting IINA
• SRT only: Other subtitle formats not yet tested
• Polling-based: Uses 100ms polling (event-based subtitle tracking doesn't work in IINA's plugin API)

Troubleshooting

Subtitles don't appear

• Make sure subtitles are enabled in IINA (press J or check Subtitles menu)
• Verify your subtitle file is in SRT format
• Restart IINA

Can't select text

• The overlay should be clickable by default
• Try restarting IINA
• Check IINA logs (Help → Show Log Viewer) for errors

Font too small/large

The plugin uses responsive sizing:

• Large windows: 5vh font size
• Medium windows (≤600px): 6vh font size
• Small windows (≤400px): 7vh font size

If you need custom sizing, you can modify index.js and rebuild.

Development

Want to modify or contribute to the plugin? See CONTRIBUTING.md for development setup and guidelines.

Quick Development Setup

# Clone repository
git clone https://github.com/kerim/iina-clickable-subtitles.git
cd iina-clickable-subtitles

# Install dependencies
npm install

# Link plugin to IINA for development
/Applications/IINA.app/Contents/MacOS/iina-plugin link $(pwd)

# Edit index.js, bump version in Info.json, restart IINA to test

Technical Details

• Architecture: Uses IINA's overlay.simpleMode() for direct content injection
• Subtitle tracking: Polls mpv.getString("sub-text") every 100ms
• Styling: CSS with responsive breakpoints and webkit-text-stroke for outlines
• Text selection: Native browser text selection enabled with user-select: text

License

MIT License - See LICENSE file for details

Credits

• Built for IINA video player
• Addresses feature request: GitHub Issue #5805
• Developed with help from Claude Code

Contributing

Contributions welcome! Please read CONTRIBUTING.md before submitting pull requests.

Support

• Issues: GitHub Issues
• Feature requests: GitHub Discussions
• IINA Documentation: https://docs.iina.io/

---

Made for language learners ❤️