mpv-subversive

MPV (v0.38.0+) plugin for GNU/Linux that makes it easy to find and load subtitles for the shows you're watching.

demo.webm

This plugin depends on functionality provided by the AniList API and Jimaku.

The code to display the GUI menu is largely borrowed from autosubsync-mpv

Dependencies

• unrar, unzip, 7zip (to extract archives)
• luasocket, luasec (optional, script will fall back on CURL if this isn't present)
• luarocks (optional, to install luasocket and luasec)

Using luasocket/luasec is a bit faster since we can reuse TCP sockets in that case, but CURL should be perfectly usable too.

Installation

sudo pacman -Syu unrar unzip p7zip lua51 luarocks
sudo luarocks --lua-version 5.1 install luasocket
sudo luarocks --lua-version 5.1 install luasec
git clone --recurse-submodules https://github.com/nairyosangha/mpv-subversive.git ~/.config/mpv/scripts/mpv-subversive

Usage

Identifying media

When pressing b (for browse!) the plugin will ask the user to identify the media they're currently watching.

This is done by trying to parse the media's filename and extracting the title and episode number from it.

When we could not parse the filename succesfully there's a good chance no matches will be found, in this case the user is asked to provide the show name manually. This uses the new mp.input() scripting functionality for which MPV version 0.38.0 is required.

Configuration

Configuration can be done by creating a mpv-subversive.conf file in MPV's script-opts folder ($HOME/.config/mpv/script-opts/mpv-subversive.conf by default)

The valid settings can be viewed in main.lua

mpv-subversive/main.lua

Lines 7 to 25 in 77b4a58

	OPTS = {
	enabled = true,
	-- the selected subtitle file is stored in the directory below. Leave it blank to skip this step
	-- If the path is relative, this is interpreted as relative to the currently playing file
	chosen_sub_dir = './subs',
	cache_directory = "/tmp/subloader",
	-- When looking up the show for any given file, the result of that lookup is stored in the cache
	-- That same result is then used for all other files in the directory of that file.
	enable_lookup_caching = true,
	-- Exclude some directories from being considered for lookup caching.
	-- This can be useful if you have a directory which contains many unrelated files.
	-- you can add multiple directories, separated by semicolons (;)
	media_blacklist_dir = "",
	subtitle_backend = 'jimaku', -- can be either 'jimaku' or 'offline'
	-- the following options are used when using the 'offline' backend
	subtitle_mapping = string.format("%s/mapping.csv", mp.get_script_directory()),
	-- the following options are used when using the 'jimaku' backend
	API_TOKEN = "",
	}

Caching lookups

When looking up a new show the script will store the AniList media ID in a file called .anilist.id in the same directory as the file. This file is then used for all consecutive lookups done in the same directory, so you don't have to look up each episode in a series.

This option can be disabled in the configuration, and certain directories can be excluded from being cached as well, see above.

Subtitle backends

jimaku

The script will query jimaku.cc. To be able to do this, you need to create an account and generate an API key.

This API key then needs to be added to the script's configuration, see above.

offline (WIP)

To be able to use the plugin in offline mode, you need to have a locally stored archive of subtitles, and a mapping which links an AniList ID to a path to the directory (or zip/rar file) containing subtitles for the given ID. We look for this mapping file (with name mapping.csv) in the script's directory itself. This can be overwritten in the configuration.

This file should look like this, 2 columns are expected, the anilist ID and a relative path to the local mapping directory.

3269,"./mapping/.hack//G.U. Trilogy"
11755,"./mapping/009 RE:CYBORG"
5525,"./mapping/07-Ghost"
116242,"./mapping/100-man no Inochi no Ue ni Ore wa Tatteiru"
127366,"./mapping/100-man no Inochi no Ue ni Ore wa Tatteiru 2nd Season"
6682,"./mapping/11eyes"
159559,"./mapping/16bit Sensation: ANOTHER LAYER"
133411,"./mapping/180-byou de Kimi no Mimi wo Shiawase ni Dekiru ka?"
161680,"./mapping/1LDK+JK Ikinari Doukyo? Micchaku!? Hatsu Ecchi!!?"
113231,"./mapping/2.43: Seiin Koukou Danshi Volley-bu"

A script to create this mapping is provided: build_offline_mapping.lua. To run this script you'll need the following:

• https://github.com/rxi/json.lua -> download the json.lua file and save it in this directory

• fill in your API key here:

  mpv-subversive/build_offline_archive.lua

  Line 7 in ad2fb72

  local headers = { ["Authorization"] = '' }

• https://github.com/luaposix/luaposix (optional) -> can also be installed with luarocks, see instructions above

If you don't want to install luaposix, you should uncomment the line that saves the mapping every so often. If you don't, it will only attempt to save the mapping at the very end, so if something goes wrong during the initial load you'll have to try all over again.

mpv-subversive/build_offline_archive.lua

Lines 75 to 76 in ad2fb72

	-- uncomment this if you don't have luaposix installed, otherwise killing the process will mean everything gets downloaded again
	-- if #new_mapping % 10 == 0 then save_last_run() end

To run the script, you can simply do luajit ./build_offline_mapping.lua

Luajit is a dependency of MPV so it should be preinstalled. It will probably work with Lua 5.1 as well.