# Volume control.
#
# The simplest type of script, which demonstrates plugin loading,
# audio path assigment and MIDI matching. Try this script with:
#
#    $ jacktube -R simple-volume-control.jt
#

# Load the "amp" plugin from the LADSPA package. You can find plugins
# by running jacktube with the "-l" switch.

%amplifier = "amp";

# To see which ports a plugin has, you can run jacktube with the "-p"
# switch and look for your plugin. Here you will see which ports exist,
# as well as their names and min/max/default values.

# Let's start the amplifier at a sane dB value.

%amplifier["amps gain"] = 0;

# Note that the port name does not have to be complete, as long as it
# is nonambiguous, you can type just the beginning of the name.

# Now we need to connect the amplifier to an input and output signal.
# The input comes from Jack and goes into the input of the plugin, and
# the output from the plugin goes to a Jack output port.

%amplifier["input"] ~ <~input;
>~output ~ %amplifier["output"];

# As you can see, the "~" is used to build a signal path. Note the
# two opposite '<' and '>' markers as well. They signal input and
# output ports, respectably. In this case we are only using one signal
# path, so our signal will be a mono signal. If we wanted stereo, we'd
# have to either instantiate the plugin twice, or use a stereo plugin
# and two Jack ports in each end.

# A volume control that stays at zero dB gain is of little use, so
# let's make it react to MIDI events. We start by matching the CC
# message 7, which is MIDI volume, on channel 1.

final [<@midi_in, 0, type[control], 7, all]

# Let's explain what was defined on that line from start to finish.
# First, we started with the word "final". This is to make sure that we
# consume the event, so that other scopes cannot match it.
#
# Inside the matching scope we see "<@midi_in", which is the type and
# name of the MIDI port we want to use for MIDI input. This will show
# up in qjackctl and other Alsa sequencer clients.
#
# Then we have 0, which is in fact channel 1. All number ranges,
# including channel numbers, MIDI CC messages and program changes start
# at zero in Jacktube. Consequently, when comparing to a program that
# uses values starting at one, you will have to subtract one from that
# value to use it with Jacktube.
#
# Following that is "type[control]", which is the type of MIDI we want
# to match, and then the control (CC) number and then the value range.

# Matching scopes are always followed by an event scope, with
# statements that should be carried out inside it, so let's define one
# that sets the gain value according to the received CC message:

{
	%amplifier["amps gain"] = -70 + event[value] * 70 / 127;
}

# "event[value]" refers to the value of the volume control message we
# received. The mathematical expression is simply a way of mapping the
# values 0-127 (the standard CC range) to values between -70 (minimum
# value for the plugin port, e.g. total silence) and 0 (no gain).

# If we want to use this script instance in a MIDI chain, we should
# forward all other MIDI messages, otherwise MIDI hosts that come after
# us will never receive anything.

[<@midi_in, all, all, all, all]
{
	>@midi_out = [event[channel], event[type], event[param], event[value]];
}

# Note the reversed '>' before the midi_out name, this is because it is
# an output port, and not an input port. Note also that even though we
# match every possible MIDI message in the matching scope, volume
# control messages on channel 1 will not be matched because of the
# "final" keyword in the previous matching scope.