https://github.com/kerim/iina-clickable-subtitles
IINA plugin that makes subtitles clickable for language learning with macOS Look Up integration
https://github.com/kerim/iina-clickable-subtitles
devanagari hindi iina language-learning macos plugin subtitles video-player
Last synced: 4 months ago
JSON representation
IINA plugin that makes subtitles clickable for language learning with macOS Look Up integration
- Host: GitHub
- URL: https://github.com/kerim/iina-clickable-subtitles
- Owner: kerim
- License: mit
- Created: 2025-11-16T16:02:16.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-11-16T16:07:13.000Z (7 months ago)
- Last Synced: 2026-01-20T13:57:44.511Z (4 months ago)
- Topics: devanagari, hindi, iina, language-learning, macos, plugin, subtitles, video-player
- Language: JavaScript
- Size: 9.77 KB
- Stars: 4
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://iina.io/))
- **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](../../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:
```bash
/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](CONTRIBUTING.md) for development setup and guidelines.
### Quick Development Setup
```bash
# 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](LICENSE) - See LICENSE file for details
## Credits
- Built for [IINA](https://iina.io/) video player
- Addresses feature request: [GitHub Issue #5805](https://github.com/iina/iina/issues/5805)
- Developed with help from [Claude Code](https://claude.com/claude-code)
## Contributing
Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting pull requests.
## Support
- **Issues**: [GitHub Issues](../../issues)
- **Feature requests**: [GitHub Discussions](../../discussions)
- **IINA Documentation**: https://docs.iina.io/
---
**Made for language learners** ❤️