sfz2pat - Man Page

sfz2pat filename.sfz

This documents both the conversion program sfz2pat and the sfz loader of the gt midi player.

The name of one or more .wav files containing samples and various parameters describing the desired patch structure and how to play the patch are given in a text file with the extension .sfz.  Run the sfz2pat utility on filename.sfz, and, if all goes well, the result will be a GUS patch file named filename.pat.

The same .sfz file can be loaded and played directly by gt.  Just put the name of the file into timidity.cfg or a file it sources, as you would the name of a GUS .pat file.  Some features of sfz patches can only be used when the patch is loaded directly, because they don't fit into the GUS format.

The format of .sfz files is described in http://www.rgcaudio.com/sfzformat.htm. See also http://www.drealm.org.uk/sfz/plj-sfz.html a more lucid, less authoritative, account (from PL Jones). An .sfz patch file is a text file describing a single instrument, as implemented here. (Though a whole set of drums can be characterized in a single .sfz file for RGC Audio's player program, this implementation requires a separate patch file for each drum.)

Typically, an instrument will have a number of different samples, and which sample sounds when a note on that instrument is played will depend on various circumstances -- the pitch of the note, how loud it is, and so on.  A sample thought of in relation to whether it sounds when a note is played is referred to as a layer in the RGC documentation, but I usually call it a sample. Each individual sample (layer) of an instrument is described in a region of the .sfz patch file (see the <region> opcode below).

Only a very tiny, little, miniscule part of SFZ is currently interpreted.  SFZ opcodes in the .sfz file that are not yet implemented are ignored.  Those that are interpreted may or may not work exactly as specified in the RGC Audio documentation (or as described here).

The .pat files that are created are GUS extended patch files, so they can have velocity layers and can be in stereo. If the source .wav file is in stereo, the extended GUS patch derived from it will also be in stereo.  In addition to .wav files, you can also use .aiff and .ogg files for samples.  24-bit .wav files are ok, but for GUS patches, they are down-converted to 16 bits, so the extra resolution is lost.  When loading patches directly, all 24 bits are used.

Here are the opcodes currently intepreted.

<group>

Beginning of global opcodes that apply thoughout following regions, until the next <group> or end of file.

<region>

Beginning of local opcodes that apply only until the next <region>, or <group> or end of file.

sample=filename

Gives path of a file containing sample data.

key=k

Note to play. k is a number 0-127 or an IPN note name (letter A-G, optional # or b, then octave from -1 to 9), and likewise below for all values referred to as k.

hikey=k

Highest key of range. Default is 60.

lokey=k

Lowest key of range. Default is 60.

pitch_keycenter=k

Middle key of range. Default is 60.

hivel=v

Highest velocity of range. v is a number 0-127. Default is 127.

lovel=v

Highest velocity of range. v is a number 0-127. Default is 0.

offset=n

Where patch starts in sample file, in samples from the beginning of the file. Default is 0.

end=n

Where patch ends in sample file, in samples. Default is the end of the file.

loop_start=n

Where the loop start point of patch is in sample file, in samples. Default is the offset of the sample.

loop_end=n

Where the loop end point of patch is in sample file, in samples. Default is the end of the sample.

loop_mode=loop_sustain

Makes the sample loop while note is held. Default is no loop.

volume=f

How loud to play the sample, in decibels. Default is 0 decibel change to what is found in the sample file.

amp_random=f

The sample is amplified by a randomly selected amount from 0 to f, given in decibels. (This has no effect when creating .pat files.)

ampeg_release=f

Release time for the volume envelope, in seconds.

group=n

Defines the group the sample belongs to.

off_by=n

The sample will stop playing when a note from group n is started.

trigger=first

The sample will be played only if no other note in the same group (and on the same channel) is playing. (This has no effect when creating .pat files.)

trigger=legato

The sample will be played only if another note in the same group (and on the same channel) is playing. (This has no effect when creating .pat files.)

hirand=f

The sample plays only when a randomly selected number between 0 and 1 is less than f. (This has no effect when creating .pat files.)

lorand=f

The sample plays only when a randomly selected number between 0 and 1 is greater or equal to f. (This has no effect when creating .pat files.)

sw_hikey=k

Highest key in switch range.

sw_lokey=k

Lowest key in switch range.

sw_down=k

The sample will play only if note k is playing (on the same channel), provided it falls within the switch range. (This has no effect when creating .pat files.)

sw_up=k

The sample will not play if note k is playing (on the same channel), provided it falls within the switch range. (This has no effect when creating .pat files.)

Probably, there are lots of bugs.  This is an experiment.

Greg Lee <greg@ling.lll.hawaii.edu>