autosubs.py for Kodi

A project to automatically create reasonable default settings for subtitles and audio tracks in Kodi.

How it works

Kodi has stupid default settings for playing subtitles. You can always enable subtitles in your native language, or always enable forced subtitles, but there's no way to automatically play subtitles in your native language only when the audio is not in your native language. This script fixes this problem by enabling subtitles manually for these files.

Because of limitations to Kodi's JSON-RPC API (which I would love to see fixed), the program modifies Kodi's database directly.

Modes of operation

• The scan mode, python autosubs.py -d videos.db scan <files>. In this mode, a list of files provided by the user are found in the Kodi database and their settings are updated to activate the correct subtitle by default. This mode does not require API access to Kodi.

• The watch mode, python autosubs.py -d videos.db watch. In this mode, the script connects via websockets to Kodi's JSON-RPC API. It listens for new movies being added to the database, and then sets the subtitle settings on them directly. While the more flexible scan mode should be used to establish settings for your existing files, this is a great way to keep Kodi up to date with newly added files.

• The audio mode, python autosubs.py -d videos.db audio <files>. This mode behaves similarly to scan mode, in that it scans a list of files provided by the user. This enables a different feature, however. audio mode uses heuristics to determine when a file contains multiple primary audio tracks, e.g. when both a 5.1 upmix and the original stereo are present, and offers to switch the tracks for you. This is not really related to the primary usage of this script, but was too handy not to include.

Heuristics employed to determine subtitle settings

autosubs.py follows this procedure to decide whether subtitles should be enabled for a given video, and which subtitles to prefer:

1. For each file, determine whether the default audio is English (or your selected language). The file is skipped if the audio is in your language.

2. Get the default subtitle. Prioritizing external subtitles (which are assumed to be in the same location as the file, with '.srt' as the extension), then internal forced subtitles, then internal subtitles with the "default" flag set, then any other subtitle tagged with your language in the file.

3. Ask the user which subtitle to make the default. You can press enter to select the default subtitle from step 2, or make your own selection from the detected subtitles. scan mode has a -q flag to automatically choose the default subtitle, which skips movies for which a subtitle has already been set. In watch mode, the default subtitle will always be applied automatically.

Usage examples

python3 autosubs.py -d videos.db scan myfiles/*.mkv

python3 autosubs.py -d videos.db -l French scan -auf file1.mkv file2.mkv

python3 autosubs.py -d videos.db watch ws://localhost:9090

In scan mode, you need to have all of the files you want to scan already in the Kodi videos database (which is named something like MyVideos###.db). It should be safe to use this script while Kodi is running, but if you're paranoid you can shut down Kodi first and make a backup of your database.

Options for all modes

--database, -d

Provide a path to your Kodi videos database. This option is required.

--language, -l

Set a default language. You can use either the full name or a two or three letter code (like "en" or "eng" for English). This is used as described above to decide whether a file needs subtitles automatically enabled.

Options for scan mode

There are several options:

--updateonly, -u

This skips reading files that already have subtitles set in the Kodi database. This is faster, because it means we don't have to scan the original files. It's also safer, because there's no risk you'll accidentally overwrite the settings for files you've already configured. But there's some chance you'll miss files that were incorrectly configured before.

--fastmode, -f

This checks to see whether the audio track selected by Kodi is already in your native language, and if so, it skips the file. At present, files with the default audio tagged in the file with your selected language are skipped anyway (since presumably they don't need subtitles set), but this is safer than fast mode because there's some chance the data in Kodi will be inaccurate, or that a dub will be the selected audio track. That said, turning this on is much faster because most files won't need to be scanned, even if they don't have subtitle settings.

--quiet, -q

This is designed to allow you to automatically run it whenever new files are added to Kodi's database. It implies both --updateonly and --fastmode, and also applies the default option (when there is one), or does nothing (when there isn't). This is similar to the behavior of autosubs.py in watch mode, but with this option you can run it manually.

--audio

This enables the feature described below. It's designed to detect cases where you might want to use a secondary audio track as the default, for example when the original mono mix is included as a secondary track in the file.

Requirements

• Python 3.8+
• pymediainfo
• pycountry
• websocket-client