!
! This file is HORRIBLY out of date. See the website:
! http://wiki.zadzmo.org/doku.php?id=jtrigger:start
!
The basic syntax for the configuration file is a simplified form of C. It looks like this: [block-type] { statement; statement; }
All whitespace are neglected, so empty lines and newlines can be placed anywhere. Anything between a '#' character and a newline are treated as comments and ignored, so
# This block is an example.
block { # stuff
statement; # more stuff
}
is valid as well.
All strings must NOT contain whitespaces or special characters. If desired, they can be placed within double quotes.
block { param = "multi-word option and things"; }
--
The two main blocks are sample blocks and instrument blocks. There are also realtime blocks, and a few miscellanous ones.
A sample block specifies a file (or channel of a file) and a JACK output port, and other options like gain and velocity sensitivity.
An instrument block specifies a midi note and channel, and a list of samples that are triggered when a note on message is recieved at that note/channel.
Thus, the minimalist configuration is pretty much this:
--
sample{ file=drum.wav;
port=drum; }
instrument {
channel = 10;
note = 60;
samples = drum.wav; }
--
Loading JTrigger with the above it will play back the sample 'drum.wav' on reception of the middle C on channel 10. The JACK port which the sample is output to will be called 'drum'. Simple, but functional.
But - we can complicate things quickly by adding more samples to the instrument.
--
sample{ file = drum1.wav;
port = drum-left; }
sample{ file = drum2.wav;
port = drum-right; }
instrument {
channel = 10;
note = 60;
samples = drum1.wav, drum2.wav; }
--
This creates a stereo instrument, as the instrument is only concerned with midi. Notice that the two sides of the instrument are located in two different files.
If a file has multiple channels, they can be specified in the next example shown below. 'drum-left' is the first channel of the file, 'drum-right' is the second channel of the next one. This way, stereo wave files are not a problem.
Channels are numbered starting from 1, not zero. Choosing zero will force a mixdown. Mixdown will also occur if the channel isn't specified (like above), and the file is not mono.
--
sample{ name = drum-left;
file = drum.wav, 1;
port = drum-left; }
sample{ name = drum-right;
file = drum.wav, 2;
port = drum-right; }
instrument {
channel = 10;
note = 60;
samples = drum-left, drum-right;
}
--
Notice that we have to give the samples names now, otherwise there would be two samples with the same name, which JTrigger would not like. You could also use a stereo file to output different sounding drums on the same note, depending on velocity:
--
sample{ name = drum-high;
file = drum.wav, 1;
low = 50;
port = drum; }
sample{ name = drum-low;
file = drum.wav, 2;
high = 70;
port = drum; }
instrument {
channel = 10;
note = 60;
samples = drum-high, drum-low;
}
--
This cause JTrigger to crudely pan between the two samples as velocity increases. The 'peak' option can be used to change where velocity would be effectly maximum to help smooth things out if needed, or the overlap can be adjusted.
The below config will pan cleanly across two samples, resulting in a static amplitude across all velocity values but a clear timbre change instead.
--
sample{ name = drum-high;
file = snare.wav;
port = drum; }
sample{ name = drum-low;
file = tom.wav;
port = drum;
peak = 0; }
instrument {
channel = 10;
note = 60;
samples = drum-high, drum-low;
}
Notes for vd2-050513:
There is a simple output 'protocol' in effect to indentify message types now, in such a way as to be easily parsed by a user-interface program. Messages are sent one per line in the following format:
(id):(message)
The ID is a single character to indentify the type of message...
- 'alert' message. Jtrigger has decided that you should give the message to the user as usually it's some form of error.
- Debugging message. Not displayed unless turned on. It's a good idea not to bother the user with this unless requested.
- Informative. Extra detail, the user won't miss it but it's not a bad idea to tell them.
- 'response.' Usually used to return requested data, such as the contents of a sample.
- Some form of failure occured and Jtrigger is now exiting. Any user interface should pass the message to the user.
Reference of all sample options:
option description
name Symbolic name for the sample. These must be unique. If not
specified, it defaults to the last part of the file path.
Eg.: if file="/path/file.wav", name would be "file.wav"
gain Normally, at maximum velocity a sample is played back with it's
volume unmodified (in other words, velocity can only make a
sample quieter than what is stored on disk.) This can be used
to increase the volume, if needed. Defaults to '1.0' if not
specified.
file Path to the file that is loaded. This is required. The
channel of the file can optionally be specified as shown
above.
high Maximum velocity that this sample will respond to. Defaults
to 127, must be between 0-127. Cannot be set lower than the
peak value, if this is the case, high will be adjusted.
low Minimum velocity that this sample will respond to. Defaults
to 0, must be between 0-127. Cannot be set higher than the
peak value, if this is the case, low will be adjusted.
peak The velocity value that makes for the effective maximum.
For example, with high and low at their defaults, setting this
to zero will make a sample get quieter as velocity increases
instead of louder. Defaults to 127, must be between 0-127.
port This is the port that the sample will output to. Multiple
samples may specify the same port, in which case they will
simply be mixed together.
start Which frame in the file to start at. Default is zero, valid
range is from zero to one less than the length of the file.
New in vd2-050409.
stop Which frame in the file to stop playback at. Default is the
last frame of the file, valid range is from the last frame to
one more than the current value of the start parameter.
If set to zero or less jtrigger will assume the last frame.
New in vd2-050409.
canstop Determines if the sample an be turned off with a note off
message, possibilities are 'on' (will be turned off) and
'off' (will always play through to finish.) Default is on.
New in vd2-050630.
Reference of all instrument options:
option description
channel Midi channel to react to. Required. Must be between 1-16.
note Midi note to react to. Required. Must be between 0-127, with
60 being equal to the middle C.
samples Which samples to include in this instrument. Samples may be
in multiple instruments without problems, however,
samples are not polyphonic and thus if triggered again while
already playing back the sample will simply reset. Samples
may be specified in a comma seperated list and/or this option
can be used multiple times.