QtPotato/README.md

QtPotato

A KDE video player built on mpv that translates subtitles with an LLM.

QtPotato is a Qt 6 / Kirigami video player for Linux. Playback is handled by libmpv, and the interface is modelled after Haruna. It can also translate a whole subtitle track with any OpenAI-compatible API and show the result in the player.

Features

• Subtitle translation: sends a text subtitle track (embedded or external) to an OpenAI-compatible chat completions API in batches, with nearby lines as context. The result is cached as an .srt file, so the same video does not have to be translated twice.
• mpv playback: hardware decoding and everything else libmpv supports. Your mpv.conf is loaded at startup (can be turned off in the settings).
• Subtitles: track selection, a secondary subtitle, delay, font size and outline settings.
• Playlist: other videos in the same folder are added automatically, with repeat and stop-after modes.
• Recent files, MPRIS (media keys and Plasma's media controls), and full screen with auto-hiding controls.
• Follows your Plasma style, colours and icons.

Installing on Arch Linux

From the pacman repository

Every release is built and published to this Gitea's package registry. Import the signing key once:

curl -O https://git.trivk.dev/api/packages/tri/arch/repository.key
sudo pacman-key --add repository.key
sudo pacman-key --lsign-key 9C48725295A5F54A6A491CF86B273DD49890E8A7

Then add the repository to /etc/pacman.conf and install:

[qtpotato]
SigLevel = Required
Server = https://git.trivk.dev/api/packages/tri/arch/$repo/$arch

sudo pacman -Syu qtpotato

The package is built against Arch's current Qt and KDE Frameworks. If it breaks after a system update before a new release is out, build it from source as below.

From the PKGBUILD

git clone https://git.trivk.dev/tri/QtPotato.git
cd QtPotato/packaging/aur/qtpotato   # or qtpotato-git for the latest main
makepkg -si

Building

Dependencies

• CMake ≥ 3.25 and a C++20 compiler
• Qt ≥ 6.8 (Core, Gui, Qml, Quick, QuickControls2, Widgets, Network, Concurrent, DBus)
• KDE Frameworks ≥ 6.10: Extra CMake Modules, Kirigami, KI18n, KCoreAddons, KCrash, KConfig
• MpvQt ≥ 1.0
• QCoro ≥ 0.10 (Qt 6)
• QtKeychain ≥ 0.14 (Qt 6)
• FFmpeg (libavformat, libavcodec, libavutil)

On Arch Linux:

sudo pacman -S cmake ninja extra-cmake-modules qt6-base qt6-declarative \
    kirigami ki18n kcoreaddons kcrash kconfig mpvqt qcoro qtkeychain-qt6 ffmpeg

Build and run

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/bin/qtpotato [file]

To install system-wide:

sudo cmake --install build

Tests

cmake -B build -DBUILD_TESTING=ON
cmake --build build
ctest --test-dir build

AppImage

packaging/appimage/build-appimage.sh [build-dir]

The script downloads linuxdeploy and bundles the Qt, KF6 and mpv libraries from the host. The AppImage only runs on distros whose glibc is at least as new as the build machine's.

Translating subtitles

1. Open Settings → Translation (Ctrl+Shift+,) and fill in:
   • API base URL: the OpenAI-compatible endpoint including the version path, for example https://api.openai.com/v1 or http://localhost:11434/v1 for Ollama.
   • API key: stored in your system wallet (KWallet / Secret Service), not in the config file.
   • Model: type a name or click Load Models to fetch the list from the API.
   • Translate into: the target language, written the way you would tell the model (default: Vietnamese).
2. Play a video and select the subtitle track you want to translate.
3. Press Ctrl+T (Subtitles → Translate Subtitle). Progress is shown in the player; when it finishes, the translated track replaces the original.

Translations are cached in ~/.cache/qtpotato/translations/ as <video>.<key>.<lang>.srt. Only text subtitles can be translated; image-based ones (PGS, VobSub) are not supported.

Use Subtitles → Edit Translation Glossary… to back up or transfer terms:

• Export… saves the full current list and episode groups to a JSON file, including edits you have made in the dialog. The search filter does not limit the export.
• Import… merges a JSON glossary into the dialog. Existing Original terms take precedence (duplicates are compared without case differences), and episode groups are preserved. Review the result and click Save to apply it, or Cancel to discard it.

Importing and exporting glossary files do not call the translation API.

Terms extracted while translating an episode are stored under that episode. Later episodes reuse all existing terms and keep their original ownership; only newly extracted terms are added to the current episode. Old or imported terms without provenance are assigned to the first episode in which the glossary is opened, because their original episode cannot be reconstructed. Your edited translations and existing episode assignments are preserved. Groups sort by episode number, and changing group assignments does not invalidate the translation cache.

Keyboard shortcuts

The defaults follow Haruna.

Playback

Action	Shortcut
Play / pause	Space
Seek backward / forward 5 s	Left / Right
Seek backward / forward 15 s	Shift+Left / Shift+Right
Seek backward / forward 30 s	Down / Up
Previous / next chapter	PgDown / PgUp
Previous / next frame	, / .
Slower / faster	[ / ]
Reset speed	Backspace
Previous / next file	Shift+, / Shift+.
Volume down / up	0 / 9
Mute	M

Subtitles

Action	Shortcut
Translate subtitle	Ctrl+T
Toggle subtitles	Ctrl+S
Previous / next subtitle line	Ctrl+Left / Ctrl+Right
Next / previous subtitle track	J / Shift+J
Show earlier / later	Z / Shift+Z
Larger / smaller font	Ctrl+Z / Ctrl+X
Add external subtitle	Alt+S

Window

Action	Shortcut
Open file	Ctrl+O
Open URL	Ctrl+Shift+O
Full screen	F
Playlist	P
Screenshot	S
Settings	Ctrl+Shift+,

Seek step sizes and the volume step can be changed under Settings → Playback.

Configuration

• Settings: ~/.config/qtpotatorc
• mpv config: /etc/mpv/mpv.conf and ~/.config/mpv/mpv.conf
• Translation cache: ~/.cache/qtpotato/translations/

License

QtPotato is licensed under the GNU General Public License v3.0 or later.