jamak (자막, Korean for "subtitles") is an interactive subtitle downloader
for mpv: plain Lua, curl as the only dependency, backed
by OpenSubtitles.com. Needs mpv 0.39+.
- Fuzzy-filterable picker in mpv's console UI (same look as the built-in
g-sselector) instead of a blindly loaded top match. Results are cached: a wrong pick costs a reopen, not a re-query. - Moviehash matching, computed in Lua: subs for your exact file rank
first, tagged
[HASH], with frame-rate cross-checks against the video. - Optional quota-aware auto mode that never spends a download on a guess (5 per day without an account, 20 with a free one).
- Async everywhere: network calls never block playback.
git clone https://github.com/arrufat/mpv-jamak ~/.config/mpv/scripts/jamakor as a dotfiles submodule. Keep the directory name jamak, or your
script-opts file won't be found.
jamak works out of the box with no configuration. OpenSubtitles then counts downloads anonymously, 5 per day per IP address. To get 20 a day:
- Create a free opensubtitles.com account.
- Export
OPENSUBTITLES_USERNAMEandOPENSUBTITLES_PASSWORDin your environment, or copyjamak.conf.exampleto~/.config/mpv/script-opts/jamak.confand fill them in there. Environment variables win over the config file, key by key. The file is plain text; keep it out of public dotfiles.
jamak ships its own API key. To use your own instead, register a consumer
at opensubtitles.com/consumers
and set OPENSUBTITLES_API_KEY (or api_key).
Recommended in mpv.conf, so downloaded subtitles auto-load on replay:
sub-auto=fuzzy
slang=en,eng,ko,kor| Key | Action |
|---|---|
Ctrl+u |
Search by moviehash + guessed title, pick from the list. Press again to reopen cached results. |
Ctrl+U |
Manual search: edit the title, choose a language, pick. |
Rebindable via script-binding jamak/jamak-search and
.../jamak-search-manual.
Ranking: hash match, language priority, human before AI-translated
([AI]), matching frame rate, regular before hearing-impaired ([HI],
flip with prefer_hi=yes), download count. A hash match that contradicts
the file name's episode code or the other hash matches is tagged [HASH?]
and ranks below trusted ones. The prompt shows the video's fps; a row
shows its own only when it disagrees. Downloads land next to the video as
<video>.<lang>.srt (or in fallback_dir) and load immediately.
With auto=yes, a video without subtitle tracks gets a hands-free
download when a trusted hash match exists; otherwise jamak only hints
that results are available. Audio files and images are skipped.
Debugging: script-message jamak-hash prints the file's moviehash;
--msg-level=jamak=v logs queries and result counts.