.\" # Copyright 2024-2025 David Robillard <d@drobilla.net>
.\" # SPDX-License-Identifier: ISC
.Dd August 1, 2025
.Dt JALV.GTK3 1
.Os
.Sh NAME
.Nm jalv.gtk3
.Nd run an LV2 plugin with a GTK3 interface
.Sh SYNOPSIS
.Nm jalv.gtk3
.Op Fl dghmpstx
.Op Fl b , Fl Fl buffer-size Ns = Ns Ar size
.Op Fl c , Fl Fl control Ns = Ns Ar setting
.Op Fl l , Fl Fl load Ns = Ns Ar dir
.Op Fl n , Fl Fl jack-name Ns = Ns Ar name
.Op Fl P , Fl Fl preset Ns = Ns Ar uri
.Op Fl r , Fl Fl update-frequency Ns = Ns Ar hz
.Op Fl S , Fl Fl scale-factor Ns = Ns Ar scale
.Op Fl U , Fl Fl ui-uri Ns = Ns Ar uri
.Op Ar plugin_state
.Sh DESCRIPTION
.Nm
is a simple LV2 host that runs a single plugin.
This version has a GTK3 interface that shows either generic controls or a custom plugin GUI.
.Pp
.Nm
has one positional argument, which can be a plugin URI, preset URI, or the path to a bundle or data file that describes one.
If none is given, then a plugin selector dialog is initially displayed.
.Pp
The options are as follows:
.Bl -tag -width 3n
.It Fl b , Fl Fl buffer-size Ns = Ns Ar size
Buffer size for plugin <=> UI communication.
.It Fl c , Fl Fl control Ns = Ns Ar setting
Set control value, for example,
.Fl c Ar vol=1.4
where
.Dq vol
is the symbol of some control port on the plugin.
.It Fl d , Fl Fl dump
Dump plugin <=> UI communication.
.It Fl g , Fl Fl generic-ui
Show generic UI instead of custom plugin GUI.
.It Fl h , Fl Fl help
Print the command line options.
.It Fl l Ar frames
Length of an audio block.
.It Fl m , Fl Fl minimal-ui
Show only the plugin interface without any application extras.
.It Fl n , Fl Fl jack-name Ns = Ns Ar name
Use the given JACK client name.
Note that JACK may adjust the name if necessary unless
.Fl x
is also given.
.It Fl P , Fl Fl preset Ns = Ns Ar uri
Load the given preset before running plugin.
.It Fl p , Fl Fl print-controls
Print control output changes to
.Dv stdout .
.It Fl r , Fl Fl update-frequency Ns = Ns Ar hz
Set the UI update frequency.
By default the screen refresh rate is used, typically 30 or 60 Hz.
.It Fl S , Fl Fl scale-factor Ns = Ns Ar factor
Override the UI scale factor.
.It Fl s , Fl Fl show-hidden
Show controls that are normally hidden.
.It Fl t , Fl Fl trace
Print debug trace messages.
This enables the
.Dq trace
LV2 log, which is used by some plugins to print debugging output.
Some extra internal error messages are also enabled.
Note that this may print in the audio thread, which can cause dropouts.
.It Fl U , Fl Fl ui-uri Ns = Ns Ar uri
Load the UI with the given URI.
.It Fl x , Fl Fl exact-jack-name
Use only the exact JACK client name given by
.Fl n
or exit if it's unavailable.
.El
.Sh ENVIRONMENT
.Bl -tag -width LV2_PATH
.It Ev LV2_PATH
Search path for LV2 bundles, in
.Ev PATH
format.
.El
.Sh SEE ALSO
.Xr jalv 1 ,
.Xr jalv.qt5 1
.Sh AUTHORS
jalv was written by
.An David Robillard
.Aq Mt d@drobilla.net
with contributions by others.
The original GTK interface was added by Alexandros Theodotou and Nick Lanham.