https://github.com/tripasect/mpv-subtitle-definition
🎥 Enhance your viewing experience in mpv by providing instant, on-screen definitions for difficult or obscure words found in subtitles.
https://github.com/tripasect/mpv-subtitle-definition
chatgpt english-learning flashcards foreign-language language-learning movies mpv mpv-extension mpv-script mpv-subtitle subtitle subtitles watching
Last synced: about 1 month ago
JSON representation
🎥 Enhance your viewing experience in mpv by providing instant, on-screen definitions for difficult or obscure words found in subtitles.
- Host: GitHub
- URL: https://github.com/tripasect/mpv-subtitle-definition
- Owner: tripasect
- License: mit
- Created: 2025-02-02T03:04:18.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-02-06T06:48:42.000Z (3 months ago)
- Last Synced: 2025-04-05T22:16:57.613Z (about 1 month ago)
- Topics: chatgpt, english-learning, flashcards, foreign-language, language-learning, movies, mpv, mpv-extension, mpv-script, mpv-subtitle, subtitle, subtitles, watching
- Language: Python
- Homepage:
- Size: 157 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Preview
https://github.com/user-attachments/assets/49ad32c3-a4fb-4d44-9795-27a1ef1f8381
**mpv-Subtitle-Definition** is an [mpv-player](https://github.com/mpv-player/mpv) extension put together to help language learners easier understand difficult or obscure words appearing in movie or video subtitles when using mpv. When triggered by a key (`TAB` or `ENTER`), it reads the current subtitle text displayed on screen, sends it to a Python script that extracts challenging words, and then uses ChatGPT's API to look up their definitions. The definitions are then returned to the Lua script and displayed on-screen (OSD) for easy reference.
## Features
- **Real-Time Assistance:** Instantly provides definitions for difficult or obscure words in subtitles.
- **Seamless Integration:** Triggered directly from mpv using configurable keys (`TAB`/`ENTER`).
- **Automated Word Analysis:** Utilizes a Python script to parse subtitle text and detect challenging vocabulary.
- **Powered by ChatGPT:** Leverages ChatGPT’s API to retrieve clear, dictionary-style definitions with example sentences.
- **Customizable:** Easily extendable and modifiable to suit your needs.
# Prerequisites
- **mpv:** Ensure you have mpv installed on your system. If you don't, visit [mpv-player](https://github.com/mpv-player/mpv) for more information.
- **Python 3.6+:** The Python script requires Python 3.6 or higher.
- **OpenAI API:** You need generative AI. I use ChatGPT 4o mini but you can use your provider of choice with a bit of modification.
# Installation
1. Clone this repository in the scripts folder of mpv and de-nest the .lua file:
```bash
cd ~/.config/mpv/scripts
git clone https://github.com/tripasect/mpv-Subtitle-Definition.git
cd mpv-Subtitle-Definition
mv mpv-Subtitle-Definition.lua ..
```
2. Create and activate a `.venv` virtual environment (**required**):
```bash
python3 -m venv .venv
source .venv/bin/activate
```
3. Install the required Python packages:
```bash
pip install -r requirements.txt
```
4. Download NLTK data (if not already installed):
```bash
python -c "import nltk; nltk.download('punkt'); nltk.download('averaged_perceptron_tagger'); nltk.download('wordnet')"
```
5. Create a .env file in the project root and add your OpenAI API key to it:
```bash
touch .env
nano .env
```
```file
# .env
OPENAI_API_KEY=your_openai_api_key_here
```
# Usage
- Start mpv and play your video.
- Trigger the script: While watching the video, press `TAB` or `ENTER` to capture the current subtitle text.
- View definitions: The extension will pause the playback, analyze the subtitle text and, if difficult words are found, show their definitions on the screen. If no difficult words are found, it simply resumes the playback without querying ChatGPT at all.
# Customization
- Word Lists: To prevent common words from being looked up, maintain a directory of text files by adding/updating the .txt files in directory path `/word-lists`.
- Key Bindings: Adjust the Lua script to change the trigger key if needed.
- Prompting: Since the backbone of the extension is generative AI, it is easy to modify its behavior. Change the `query` string in the .py file to best suit your needs.
# Contributions
Yes please. Do fork this and make it better, do open issues and do submit your pull requests.
Happy viewing and learning!