https://github.com/user-attachments/assets/466d1aa7-c7d1-4ea2-a296-0835d3700962

mpvacious

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 script supports secondary subtitles, configurable media formats, and customizable keyboard bindings. Mpvacious works best with Goldendict-ng or Rikaitan. Watch a 📽️ video demonstration.

✨ Ajatt-Tools is looking for new contributors!

Requirements

You need to install some third-party programs before you install mpvacious.

<table> <tr> <th><a href="https://www.gnu.org/gnu/about-gnu.html">GNU/Linux</a></th> <th><a href="https://www.gnu.org/proprietary/malware-microsoft.en.html">Windows 10+</a></th> <th><a href="https://www.gnu.org/proprietary/malware-apple.en.html">macOS</a></th> <th>Comments</th> </tr> <tr> <td><a href="https://wiki.archlinux.org/index.php/Mpv">mpv</a></td> <td><a href="https://sourceforge.net/projects/mpv-player-windows/files">mpv</a></td> <td><a href="https://mpv.io/installation/">mpv</a></td> <td>mpvacious is a user-script for mpv. Get mpv v0.41.0 or newer.</td> </tr> <tr> <td><a href="https://wiki.archlinux.org/index.php/Anki">Anki</a></td> <td colspan="2" align="center"><a href="https://apps.ankiweb.net/">Anki</a></td> <td></td> </tr> <tr> <td colspan="3" align="center"><a href="https://ankiweb.net/shared/info/2055492159">AnkiConnect</a></td> <td>Install from AnkiWeb.</td> </tr> <tr> <td><a href="https://www.archlinux.org/packages/core/x86_64/curl/">curl</a></td> <td colspan="2" align="center"><a href="https://curl.haxx.se/">curl</a></td> <td>Installed by default on all platforms except Windows 7.</td> </tr> <tr> <td><a href="https://www.archlinux.org/packages/extra/x86_64/xclip/">xclip</a> or <a href="https://archlinux.org/packages/extra/x86_64/wl-clipboard">wl-copy</a></td> <td></td> <td>pbcopy</td> <td>To copy subtitle text to clipboard.</td> </tr> </table>

Install all dependencies at once (on Arch-based distros):

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

Prerequisites

• A guide on how to set up Anki can be found on our site.

• If you're on a Windows or a Windows-like machine, a mpv build by shinchiro is recommended.

• macOS users are advised to use homebrew or manually add mpv to PATH.

• Note that it is not recommended to use FlatPak or similar containers. If you still want to, read this.

• Make sure that your build of mpv supports encoding of audio and images. This shell command can be used to test it.

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

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

• Most problems with adding audio or images to Anki cards can be fixed by installing FFmpeg and enabling it settings.

Installation

There are multiple ways you can install mpvacious.

We recommend using GNU/Linux. Windows is not recommended, but we acknowledge that some people haven't switched to GNU/Linux yet.

From the AUR

mpvacious can be installed with the mpv-mpvacious package. This method will install mpvacious to /etc/mpv.

Using Bash on GNU/Linux and macOS

Requires curl and unzip.

Run install.sh with this command:

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

On GNU/Linux, we try to detect what package manager variant of the config location you're using, with precedent being:

~/.var/app/io.mpv.Mpv     (flatpak)
~/snap/mpv
~/snap/mpv-wayland
~/.config/mpv

To install into any of these locations, make sure the ones above it don't exist.

Using Powershell on Windows

Open Powershell.

Optional, needed to run a remote script the first time if not enabled already:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Run install.ps1 with this command:

irm https://raw.githubusercontent.com/Ajatt-Tools/mpvacious/HEAD/scripts/install.ps1 | iex

NOTE: If this command is run in an mpv installation directory with portable_config, it'll install there instead of AppData.

Development mode - Using git

Installing Mpvacious in development mode allows contributors to easily test their changes. With this setup, any changes made to the *.lua files will be applied immediately after restarting mpv.

First approach

Clone the repository, then create a symlink from the mpvacious directory to the mpv config directory.

Commands for GNU/Linux:

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

To update an existing installation, use git in the project folder.

git pull

Second approach

Clone the repo directly into the mpv/scripts directory.

Commands for GNU/Linux:

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

To update an existing installation, use git.

cd ~/.config/mpv/scripts/mpvacious && git pull

Manually

This way is not recommended because it's easy to make a mistake during the process and end up with a broken installation.

mpvacious is a user-script for mpv, so it has to be installed in the directory mpv reads its user-scripts from.

| OS | Location | |--------------------|--------------------------------------------------| | GNU/Linux or macos | ~/.config/mpv/scripts/ | | Windows | C:/Users/Username/AppData/Roaming/mpv/scripts/ |

Download the latest release or the master branch for a development version, and extract the "mpvacious" folder to your mpv scripts directory.

<details> <summary>Expected directory tree</summary>

~/.config/mpv/scripts
|-- other script 1
|-- other script 2
|-- mpvacious
|   |-- main.lua
|   |-- helpers.lua
|   `-- other files
`-- other script 3

</details> <details> <summary>A note for mpv v0.32 and older</summary>

Older versions of mpv don't know how to handle user-scripts in subdirectories. You need to tell mpv where to look for mpvacious.

Open or create ~/.config/mpv/scripts/modules.lua and add these lines:

local mpv_scripts_dir_path = os.getenv("HOME") ..  "/.config/mpv/scripts/"
package.path = package.path .. ';' .. os.getenv("HOME") .. '/.config/mpv/scripts/mpvacious/?.lua'
function load(relative_path) dofile(mpv_scripts_dir_path .. relative_path) end
load("mpvacious/main.lua")

</details> <details> <summary>A note for Celluloid</summary>

In Celluloid user scripts are installed in /.config/celluloid/scripts/. When following the instructions above, replace .config/mpv with .config/celluloid and optionally mpvacious with the name of the folder mpvacious is cloned into.

</details>

Configuration

The config file should be created by the user, if needed.

| OS | Config location | |--------------------|-------------------------------------------------------------------| | GNU/Linux | ~/.config/mpv/script-opts/subs2srs.conf | | Windows | C:/Users/Username/AppData/Roaming/mpv/script-opts/subs2srs.conf | | Windows (portable) | mpv.exe folder/portable_config/script-opts/subs2srs.conf |

If a parameter is not specified in the config file, the default value will be used. mpv doesn't tolerate spaces before and after =.

<p align="center"> <a href="mpvacious/config/default_config.conf">Example configuration file</a> </p>

If the first field is empty, it will be set contain the string [empty]. Otherwise, Anki won't allow mpvacious to add new notes. This won't happen if the sentence field is first in the note type settings.

Tip: Try our official note type if you don't want to configure note fields yourself. Alternatively, we have a collection of user-created note types, which you can browse here.

If you are having problems playing media files on older mobile devices, set audio_format to mp3 and/or snapshot_format to jpg. Otherwise, I recommend sticking with opus for audio, and avif or webp for images, as they greatly