Immersive
Immersive is an mpv script for improving language immersion, with a special focus on sentence mining. It can automatically generate Anki cards including a dictionary definition of the target word, an audio clip of the sentence(s), a screenshot of the video, and pronunciation audio from Forvo. The script is highly configurable and supports many possible workflows.
This is a short video walking through the full process of creating a card with Immersive: https://youtu.be/FrTcu4ZO92w. It's possible to skip parts of the process if you don't need them.
Another demo that isn't artificially slowed down for the sake of being easier to follow: https://youtu.be/g1aPNkdGTUc
Requirements
The currently supported platforms are Linux and Windows. If you would like to assist in adding macOS support, please contact me.
Linux | Windows | required for & comments |
---|---|---|
mpv (0.33.0 or later) | ||
Anki with AnkiConnect | card export | |
curl | web requests (Forvo, AnkiConnect), installed on Windows 10 by default since April 2018 | |
socat | - | background playback (export preview and Forvo) |
xclip | PowerShell | clipboard access, PowerShell is installed by default |
Feature Overview
Fully Integrated Card Creation
The basic process for creating cards is as follows:
- Bring up the subtitle selection menu (
a
) - Select the subtitles that should be on the card using
a
or the autoselect (toggle withA
). If there are no subtitles or if they are badly timed, set the start/end time for the audio export manually usingQ
andE
. If you wish to take a screenshot at a specific time instead of the current frame, set it usings
. - Enter target word selection mode using
d
. Select the target word with (Ctrl
+)⇧
+←
/→
and confirm it using (⇧
+)⏎
. It's possible to search for an external word from the clipboard usingv
if there are no text subtitles or if a word can't be found. - Optionally add Forvo audio by pressing
a
after adding a target word. - Export to Anki using
f
.
The card creation process is highly customizable. For further information read this.
Dictionary Lookup in mpv
You can look up words in your configured dictionaries. Bring up the word
selection menu by pressing k
and search for the selection using (⇧
+)⏎
.
Subtitle Copying
Immersive can copy subtitles to the clipboard. Use c
to manually copy the
active line at any time, or toggle automatic copying with C
. You can
partially copy a line in the menu for selecting text from the active line.
Installation & Setup
For a guide to getting started as quickly as possible see below.
Immersive can be installed by placing the contents of this repository in a
folder within your mpv scripts directory (~/.config/mpv/scripts/
on Linux,
%APPDATA%\mpv\scripts
on Windows). This folder should be named immersive
.
Using any other name will mean that you will have to change the names of all
config files to match it as well.
All necessary files can be downloaded as a ZIP file from the latest
release. When installing
Immersive from a release archive, it only needs to be extracted into the mpv
config directory for the full release, or scripts
directory for the
script-only release. The above directory is already contained in the archive.
If you want the most up-to-date version possible, use the "Code" button at the
top of the repo's start page. Simply extract the contents of the file into
your mpv scripts folder and remove the branch name (most likely -master
)
from the name of the extracted directory.
The script is configured in several different files. These need to be placed
in a directory called script-opts
that is located next to your mpv.conf
and scripts folder. For a description of the general config syntax, see this
document.
In order to use the main feature of generating Anki cards with included definitions, these config files need to be present:
immersive-targets.conf
: how to export to Ankiimmersive-dictionaries.conf
: which dictionaries to use
The following config files are optional:
immersive.conf
: general configuration of the scriptimmersive-keys.conf
: reassign menu key bindingsimmersive-series.conf
: use custom series IDs and titlesimmersive-style.conf
: change the appearance of the interface
Documentation that is not about specific config files:
Updating
To update Immersive, delete the script's folder in your mpv config directory and replace it with the one from the latest release's script-only ZIP file. Also check if there were any changes to config entries that you have used in the change log.
Quick Start Guide
- Make sure your mpv install is version 0.33.0 or later.
- Download the latest full release of Immersive from here.
- Unzip its contents into your mpv config directory. Make sure that you are not overwriting any existing config files.
- Open
immersive-targets.conf
inscript-opts
with a text editor of your choice (like Notepad++, Sublime Text or vim), and change the values ofprofile
,deck
,note_type
, and thefield:
values so that they match your Anki setup. - Open
immersive-dictionaries.conf
and set up your dictionaries as explained here. If you are learning Japanese and using the Yomichan version of JMdict, you will most likely only have to changelocation
so it is set to the path of a directory containing the unzipped contents ofjmdict_english.zip
from the Yomichan website.
Your mpv config directory should contain the following files at this point:
scripts/
immersive/
dict/
interface/
systems/
utility/
LICENSE
main.lua
script-opts/
immersive-dictionaries.conf
immersive-series.conf
immersive-style.conf
immersive-targets.conf
immersive.conf
You can now start mpv and open the main menu of Immersive using Ctrl+a
or
begin creating a card with a
.
Troubleshooting
If Immersive crashes at any point (when this happens, the interface suddenly
disappears and all keybindings stop working), open the console using ˋ
/~
,
take a screenshot of it and report the issue to me. If you started mpv from
the command line the output there is preferable.
Suggestions & Reporting Issues
If you have any suggestions for improving Immersive or encounter a problem while using it please contact me, even if that problem is not understanding parts of the documentation or how to do something with the script. Outside of GitHub you can reach me on the Refold community's discord servers.