From cebce0915fba9e8da4ca8106a6f3f0e0ed9cd1bd Mon Sep 17 00:00:00 2001 From: Tri Vo Khac Date: Mon, 2 Nov 2026 20:27:08 +0700 Subject: [PATCH] docs: add project README - Document features, dependencies, build steps, and AppImage packaging - Explain subtitle translation, shortcuts, configuration, and licensing --- README.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..41aa802 --- /dev/null +++ b/README.md @@ -0,0 +1,146 @@ +

+ QtPotato logo +

+ +

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](https://invent.kde.org/multimedia/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. + +## 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](https://invent.kde.org/libraries/mpvqt) ≥ 1.0 +- [QCoro](https://github.com/qcoro/qcoro) ≥ 0.10 (Qt 6) +- [QtKeychain](https://github.com/frankosterfeld/qtkeychain) ≥ 0.14 (Qt 6) +- FFmpeg (libavformat, libavcodec, libavutil) + +On Arch Linux: + +```sh +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 + +```sh +cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release +cmake --build build +./build/bin/qtpotato [file] +``` + +To install system-wide: + +```sh +sudo cmake --install build +``` + +### Tests + +```sh +cmake -B build -DBUILD_TESTING=ON +cmake --build build +ctest --test-dir build +``` + +### AppImage + +```sh +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 `