QtPotato/README.md

<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.

## 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:

```sh
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:

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

```sh
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

```sh
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](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.

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](LICENSES/GPL-3.0-or-later.txt).