Preview

mpv-Subtitle-Definition.mp4

mpv-Subtitle-Definition is an mpv-player 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 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:

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):

python3 -m venv .venv
source .venv/bin/activate

3. Install the required Python packages:

pip install -r requirements.txt

4. Download NLTK data (if not already installed):

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:

touch .env
nano .env

# .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!