.\" # Copyright 2024 David Robillard <d@drobilla.net>
.\" # SPDX-License-Identifier: ISC
.Dd December 20, 2024
.Dt JALV 1
.Os
.Sh NAME
.Nm jalv
.Nd run an LV2 plugin with a command-line interface
.Sh SYNOPSIS
.Nm jalv
.Op Fl dhipstx
.Op Fl b Ar size
.Op Fl c Ar symbol=value
.Op Fl U Ar ui_uri
.Op Fl l Ar dir
.Op Fl n Ar name
.Ar plugin_uri
.Sh DESCRIPTION
.Nm
is a simple LV2 host that runs one plugin.
It has several versions, this one has an interactive command-line interface.
.Pp
.Nm
has one positional argument, the URI of an installed LV2 plugin.
.Pp
The options are as follows:
.Bl -tag -width 3n
.It Fl b Ar bytes
Buffer size for communication between plugin and UI.
The default value should be enough,
but if there are overflows,
this option can be used to allocate more space.
.It Fl c Ar symbol=value
Set control value, for example,
.Fl c Ar vol=1.4
where
.Dq vol
is the symbol of a control port on the plugin.
.It Fl d
Dump communication between plugin and UI to
.Dv stdout .
Note that this may print an extreme amount of text,
piping the output to a pager or file is recommended.
.It Fl h
Print the command line options and exit.
.It Fl i
Ignore input on
.Dv stdin
and run non-interactively.
.It Fl l Ar dir
Load state from the given directory before running the plugin.
.It Fl n 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
Print control output changes to
.Dv stdout .
.It Fl s
Show plugin UI if possible.
This option only works when plugins provide a UI that uses the non-embeddable
.Li showHide
interface.
For embeddable UIs, use
.Xr jalv.gtk3 1
instead.
.It Fl t
Print trace messages from plugin.
This enables the
.Dq trace
log defined by LV2, which is used by some plugins to print debugging output.
.It Fl U Ar uri
Load the UI with the given URI.
Usually only one suitable UI is available on a given platform,
which is used by default.
If there are several, this option can be used to select which is loaded.
.It Fl V
Print version information and exit.
.It Fl x
Use only the exact JACK client name given by
.Fl n
or exit if it's unavailable.
.El
.Sh COMMANDS
The Jalv prompt supports several commands for interactive control:
.Pp
.Bl -tag -width 16n -compact
.It Ic help
Display help message.
.It Ic controls
Print settable control values.
.It Ic monitors
Print output control values.
.It Ic presets
Print available presets.
.It Ic preset Ar uri
Set preset.
.It Ic set index value
Set control value by port index.
.It Ic set Ar symbol Ar value
Set control value by symbol.
.It Ar symbol Cm = Ar value
Set control value by symbol.
.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.gtk3 1 ,
.Xr jalv.qt5 1 ,
.Xr lv2ls 1
.Sh AUTHORS
.Nm
was written by
.An David Robillard
.Aq Mt d@drobilla.net ,
with contributions by
Robin Gareus,
Hanspeter Portner,
and others.