docs: add project README

- Document features, dependencies, build steps, and AppImage packaging - Explain subtitle translation, shortcuts, configuration, and licensing
2026-11-02 20:27:08 +07:00
1 parent 5b1c1a75be
commit cebce0915f
@@ -0,0 +1,146 @@
+<p align="center">
+  <img src="src/icons/dev.trivk.qtpotato.svg" width="96" alt="QtPotato logo">
+</p>
+
+<h1 align="center">QtPotato</h1>
+
+<p align="center">A KDE video player built on mpv that translates subtitles with an LLM.</p>
+
+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 `<video>.<key>.<lang>.srt`.
+Only text subtitles can be translated; image-based ones (PGS, VobSub) are not supported.
+
+## 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](LICENSES/GPL-3.0-or-later.txt).