mpvacious: mining movie subtitles into Anki cards from mpv

Sentence mining, which is why the package is still called subs2srs

mpvacious is a user script for mpv that offers utilities for creating and modifying Anki flashcards from movies and TV shows. It allows you to select subtitle lines, create audio clips and images, and send them to Anki.

The workflow it supports is called sentence mining, and the release package name gives the history away. The Makefile sets PROJECT to mpvacious and PACKAGE to subs2srs, and the name of the config file installed into the mpv script-opts directory follows that package name rather than the project name.

That is a design decision worth understanding, because it explains what the script does and does not do. This is not a batch converter that takes a directory of subtitle files and produces a deck. It is an interactive tool for the case where you are watching something, you hear or read a phrase you do not know, and you want a card for it before the film moves on.

What makes the card useful is that the three parts come from the same moment. The subtitle line is the text, the audio clip is the sentence as it was spoken, including the surrounding context that makes it memorable, and the image is the frame it was spoken in. A vocabulary card with a single word and a bare audio clip is much weaker than one with the full sentence and a picture, and that difference is what this script exists to capture.

The script supports secondary subtitles, configurable media formats, and customizable keyboard bindings. The secondary subtitle support is a practical detail rather than a gimmick: the second track is usually the translation, so a card can carry the original line as the prompt and the translation as the answer, or the other way round.

The dependency chain: mpv, Anki, AnkiConnect and a clipboard tool

The requirements table in the readme is where this project is honest about its scope, because the script needs four other programs before it works.

mpv itself is required, and the version floor is specific: mpv v0.41.0 or newer. Anki is required, and AnkiConnect is required, installed from AnkiWeb. AnkiConnect is the bridge, since mpvacious does not talk to Anki directly but through this add-on.

Then there is a clipboard utility, and the table shows it varies by platform. On GNU/Linux it is xclip or wl-copy, and on macOS it is pbcopy. Its purpose is stated plainly: to copy subtitle text to clipboard. On Windows the cell is empty, which is consistent with the rest of the table since the clipboard there is handled by the system.

curl is needed on all platforms, installed by default on all platforms except Windows 7.

The mpv row links to different sources per platform: the Arch Linux wiki for GNU/Linux, the SourceForge mpv-player-windows files for Windows 10 and later, and mpv.io for macOS. macOS users are advised to use homebrew or manually add mpv to PATH, and Windows users are pointed at a mpv build by shinchiro.

The recommendation is GNU/Linux, with the note that Windows is not recommended but is acknowledged because some people have not switched yet. There is also an explicit warning against FlatPak or similar containers, with a separate howto document for people who insist.

The full dependency install on Arch-based distributions is two commands.

sudo pacman -Syu mpv curl xclip --needed
trizen -S anki

The second of those is the AUR helper installing Anki, which on Arch means a user package rather than a repository package.

FFmpeg support is the make or break detail

The prerequisites section contains the single most useful troubleshooting hint in the readme, and it is about mpv rather than about Anki.

You need to make sure that your build of mpv supports encoding of audio and images, and the readme gives a shell command to test it.

$ mpv 'test_video.mkv' --loop-file=no --frames=1 -o='test_image.jpg'

If the command fails, the guidance is to find a compatible build on the mpv website, or instead install FFmpeg and enable FFmpeg support in the mpvacious config file.

Then the sentence that explains most of the support questions: most problems with adding audio or images to Anki cards can be fixed by installing FFmpeg and enabling its settings.

That is a coherent mechanism. mpvacious asks mpv to produce a still frame and an audio segment at the position of the subtitle. If mpv was built without the encoders, it cannot write a JPEG or an audio file at all, and the symptom appears much later as a card with a missing image or a missing sound. The command above is therefore not a diagnostic nicety, it is the first thing to run.

The two ways out are also the two real options. Find an mpv build with the encoders compiled in, which on Linux usually means a distribution package built with the full dependency set, or install FFmpeg separately and point mpvacious at it through the config file. The readme links to a configuration section for enabling FFmpeg support.

Four install paths, and the one the author recommends

The installation section says there are multiple ways to install mpvacious and recommends GNU/Linux.

The AUR route installs the mpv-mpvacious package and puts the script in /etc/mpv.

The shell script route requires curl and unzip.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ajatt-Tools/mpvacious/HEAD/scripts/install.sh)"

The script detects which package manager variant of the config location you are using. The precedence it looks for is a flatpak path at ~/.var/app/io.mpv.Mpv, then ~/snap/mpv, then ~/snap/mpv-wayland, then ~/.config/mpv. To install into any of those locations, the ones above it must not exist.

The PowerShell route for Windows needs the execution policy set first if it is not already.

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm https://raw.githubusercontent.com/Ajatt-Tools/mpvacious/HEAD/scripts/install.ps1 | iex

There is a note that if this is run in an mpv installation directory with portable_config, it installs there instead of AppData.

Then there is the development mode, which is the route a contributor uses, and it comes in two flavours. The first clones the repository and creates a symlink from the mpvacious directory into the mpv config directory, using a helper script.

git clone 'https://github.com/Ajatt-Tools/mpvacious.git'
mkdir -p ~/.config/mpv/scripts/
cd mpvacious
bash scripts/symlink.sh

The second clones the repository directly into the mpv/scripts directory.

mkdir -p ~/.config/mpv/scripts/
git clone 'https://github.com/Ajatt-Tools/mpvacious.git' ~/.config/mpv/scripts/mpvacious

Both approaches mean any changes to the lua files are applied immediately after restarting mpv, and updates are a git pull in the project folder.

The manual route is explicitly not recommended because it is easy to make a mistake and end up with a broken installation.

Where mpvacious does not fit

The main limitation is the one the design implies. mpvacious is an interactive script, so creating a card requires you to be watching, to notice the phrase, and to trigger the capture. There is no batch mode in the documentation and no way to run it over a corpus of subtitles while you sleep. If you want a study deck built from a season of subtitles, this is the wrong tool and you want a converter instead.

The second limitation is the dependency surface, and it is heavier than a script for a video player would suggest. Four separate programs, one of which is an add-on installed inside your spaced repetition application, and a version floor on mpv plus a requirement for a specific mpv build with encoders. On Arch the install is two commands, but on any other distribution the README only covers the shell script and PowerShell routes, and neither of those is a package manager. You are managing the dependency graph yourself.

The third is the platform asymmetry. The author recommends GNU/Linux, says Windows is not recommended, and warns against FlatPak. The Windows path exists and the readme provides an installer for it, but a script whose author calls the platform not recommended is a script you will be debugging alone.

The fourth is that AnkiConnect is a full extra program inside Anki, installed from AnkiWeb. It is a normal arrangement for Anki tooling, but it does mean the card creation path depends on an add-on being present and running, and the failure mode when it is not is an mpv error rather than an Anki error, which is a confusing place to look.

The alternative approaches differ in what they optimise. A dedicated subtitle to Anki converter processes a library in bulk, which is what you want if you have one, and gives you no context capture from the moment you watched it. Anki's own import of tab separated text with a media file is the lowest friction path for a card with text and audio and no image. And the readme mentions that mpvacious works best with Goldendict-ng or Rikaitan as the dictionary side, which is a hint that the intended workflow is a watching environment with a dictionary and a spaced repetition system, not a bulk pipeline.

Editorial conclusion

mpvacious suits a language learner or movie student who wants to turn the dialogue they are actually watching into vocabulary cards, because the audio and the picture come from the same frame the subtitle was read in, which is what makes the card useful later. It does not suit someone who wants a general purpose subtitle to Anki converter for a large library, since the workflow is interactive and manual by design. Before adopting it, check that your mpv build supports audio and image encoding, since the documentation says most problems with adding audio or images to Anki cards come from missing FFmpeg support, and confirm your AnkiConnect setup works before you start creating cards.

Frequently asked questions

Official sources

1. Ajatt-Tools/mpvacious on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases