KHORLO — Linux install
=======================

Khorlo is free. This is a beta: it works, and it is still being finished.


SOUND BUT NO INTERFACE? YOU NEED WEBKITGTK
-------------------------------------------

If Khorlo loads, plays notes, and shows a message saying the interface did not
load — nothing is broken and nothing is corrupt. Khorlo draws its interface in a
web view, and on Linux that web view is WebKitGTK, a system component most
desktop installs do not have until something pulls it in.

Install it and reopen your DAW. That is the whole fix.

  Debian 13 / Ubuntu 24.04 and newer
      sudo apt install libwebkit2gtk-4.1-dev

  Debian 12 / Ubuntu 22.04
      sudo apt install libwebkit2gtk-4.0-dev

  Fedora
      sudo dnf install webkit2gtk4.1-devel

  Arch / Manjaro
      sudo pacman -S webkit2gtk-4.1

  openSUSE
      sudo zypper install webkit2gtk3-soup2-devel

Close your DAW completely and reopen it. A DAW that has already scanned Khorlo
will not pick up the new library until it restarts.


"WHY THE -dev PACKAGE? I AM NOT A DEVELOPER."
----------------------------------------------

Because of how the library is looked up, not because you are building anything.

Khorlo asks the system for the file by its plain name:

    libwebkit2gtk-4.1.so

while the ordinary runtime package installs only the numbered version:

    libwebkit2gtk-4.1.so.0

Those are two different filenames. On Debian and Fedora the plain name is a small
pointer file that lives in the -dev package, so the runtime package alone is not
enough — you would install it, reopen Khorlo, and see the same screen. That is
the one wrong turn worth saving you.

Arch does not split its packages this way, which is why the Arch line has no
-devel on it.

The -dev package brings the other libraries Khorlo needs with it
(javascriptcoregtk, libsoup and GTK 3), so it is the only line you need.


WHERE THE FILES GO
------------------

Per user — no root needed, and the usual choice:

    mkdir -p ~/.vst3 ~/.clap
    cp -r Khorlo.vst3 ~/.vst3/
    cp -r Khorlo.clap ~/.clap/

System-wide, for every user on the machine:

    sudo cp -r Khorlo.vst3 /usr/lib/vst3/
    sudo cp -r Khorlo.clap /usr/lib/clap/

Then rescan in your DAW, or restart it.

Use ONE format. Installing both makes Khorlo appear twice in your plugin list —
harmless, but confusing.


WHAT THIS BUILD REQUIRES
------------------------

  * x86_64. There is no ARM build yet.
  * glibc 2.35 or newer — Ubuntu 22.04, Debian 12, and anything after them.
    (Builds before 0.9.02 needed glibc 2.38 by accident, which locked out
    Debian 12 and every Ubuntu LTS before 24.04. That was our mistake and it
    is fixed.)
  * GTK3 and WebKitGTK, as above.

To check your glibc:   ldd --version


IF YOUR DAW CANNOT SEE IT
-------------------------

  1. Is it in ~/.vst3 or ~/.clap, as a folder, with its Contents folder inside?
     Copy the whole Khorlo.vst3 directory, not the .so within it.

  2. Has your DAW rescanned? Restart it.

  3. Ask the loader what is missing — this names the exact library if one is:

         ldd ~/.vst3/Khorlo.vst3/Contents/x86_64-linux/Khorlo.so | grep "not found"

     Anything printed there is a package you need. Nothing printed means the
     plugin's dependencies are satisfied and the problem is elsewhere.

  4. Bitwig runs plugins in a separate process and logs failures to its own
     console — worth a look, it is often specific.


WAYLAND AND X11
---------------

Both work. If the interface misbehaves under one, trying the other is a useful
thing to tell us, because it narrows the cause considerably.

One known Linux quirk, unfixed and not ours: keyboard focus can be swallowed by
the plugin window in some hosts. It is a JUCE-level issue with how plugin windows
are embedded. Click outside and back if you get stuck.


STILL NOT LOADING?
------------------

Please send the log:

    ~/.config/Khorlo/ui-debug.log

It records whether a web engine was ever found, and it is the difference between
a guess and an answer. Say which distribution, which DAW, and Wayland or X11.

Two things NOT to spend time on, because they are already ruled out:

  * Trying the other plugin format. The CLAP and the VST3 are two wrappers
    around one plugin, and the interface is the same code in both. If one shows
    this screen, so will the other. That is expected, not a second data point.

  * Setting WEBKIT_DISABLE_DMABUF_RENDERER yourself. Khorlo already sets it for
    you when it is unset, to get past a renderer stall on some driver and
    compositor combinations. If you set it deliberately, your value is kept.


SOMETHING ELSE WRONG?
---------------------

Tell me. Nearly everything fixed in this beta was found by a user on a machine
we do not have.

  info@jas-i.com
  https://jas-i.com
