poka.sh

 Docs

Install Poka and troubleshoot a preview

how-to

This page installs the desktop app and its optional media support, and fixes the problems people meet most. For the web app there is nothing to install: open poka.sh.

Install the desktop app

  1. Get the package for your system. The installers are a .deb (Linux), a .msi or poka-setup.exe (Windows) and a .dmg (macOS). If you build from source, Build and run from source produces them.
  2. Install it the usual way for that package. The .deb needs dbus (a hard dependency) and recommends python3-nautilus, which apt installs by default; a non-GNOME desktop can leave it out. The .deb also installs the Nautilus Space-key extension for you.
  3. On Windows, the app needs WebView2, which comes with Windows 10 21H2 and later and with Windows 11.
  4. Start Poka and preview a file (Preview your first file). Extensions for individual formats are installed on first use from the catalogue at poka.sh, after Poka checks each file's SHA-256 and size.

Install libmpv for audio and video

Poka does not ship libmpv. It loads the library at run time, so you can install or replace it yourself. Without it, media files still show their metadata card and play in the built-in webview player where its decoder supports the format.

  • Windows: put libmpv-2.dll next to poka.exe, or in a folder on PATH.
  • Linux: install your distribution's libmpv (apt install libmpv2, pacman -S mpv, dnf install mpv-libs).
  • macOS: brew install mpv.
  • Anywhere: set POKA_LIBMPV to the library's full path. When it is set, it is the only place Poka looks.

Restart Poka afterwards. Playback opens in a borderless mpv window.

Troubleshoot a preview

Start here: which of these did you see?

A card saying no extension is installed. The format has no extension on this machine yet. Click the install button. If the install fails, check your network connection and try again. Poka refuses to publish an extension unless every downloaded file matches its recorded SHA-256 and size.

"<id> timed out after <N>ms". The extension used more than its time budget (max_time_ms in its manifest) and was stopped. This usually means a very large or pathological file.

"SHA256 mismatch for ...". The .wasm on disk does not match the hash in its plugin.json, so Poka refused to run it. Reinstall the extension. Manifests with an empty sha256 skip the check; that is for local development builds only.

"Conflict: X and Y both claim .ext" in the log. Two installed extensions declare the same file extension. The first one scanned wins and the other is ignored. Remove one of them.

The Space key does nothing on Linux. The trigger works under GNOME with Nautilus only. Check that python3-nautilus is installed and restart Nautilus with nautilus -q. Other desktops (XFCE with Thunar, KDE and others) have no Space-key trigger yet; use Open with or poka <file>.

The preview looks wrong. Read the information card: the viewer draws it with the preview, and for a picture, a 3D model or a drawing it sits closed under the preview. It lists facts from the file, notes where the file does not look like its extension says (a PNG renamed .jpg, for example) or where the parser found trailing data, and a SHA-256 when you press Verify.

In the browser, a message names a failure kind. The web app says why a preview failed: a module would not download or is not a valid module (load), it ran and failed (run), it answered with something unreadable (output), it ran out of time (timeout), the file is over the size cap (too-large), or the list of formats would not load (routes). Reload the page; if it persists, report the message.

A pasted link does not preview. The link must end in a recognisable extension and point to a public file, and the site must allow cross-origin requests. Otherwise download the file and drop it on the page.

Still stuck, on a developer install. python3 scripts/poka-doctor.py diagnoses a stale or broken local install: dangling symlinks, an install behind the current build, conflicting manifests and modules that are built but not installed.

Clear the caches

Poka keeps thumbnails, generated previews, decoded previews, transcoded media and a compiled-module cache. Where they are is listed in Environment variables and file locations. The settings window can show their size and clear them.