1UNSF(1) General Commands Manual UNSF(1)
2
6 unsf - break up SoundFont .sf2 files into GUS-type instrument patches.
7
11 unsf [-v|-s|-m|-d|-n|-V] [-M <bank>:<instrument>=<layer>] [-D
12 <bank>:<instrument>=<layer>] soundfont-file
13
17 Unsf is a tool to convert SoundFont files into GUS patches. Some rea‐
18 sons you might want to do such a thing are: (1) Your midi player can
19 use GUS patches but doesn't know how to read soundfonts, (2) You want a
20 convenient way of substituting patches or reassigning banks of instru‐
21 ments by editing GUS config files, or (3) You need to modify patches by
22 changing amplitude, stripping envelopes, or make other changes that can
23 easily be done by attaching options in config files. Or (4), my own
24 reason, you might need to use a version of timidity covered under the
25 Lessor GNU Public License and find that the versions of timidity that
26 can read soundfonts are protected by the more restrictive GNU Public
27 License (e.g., Timidity++ or kmidi, or the Alsaplayer midi plugin).
28 Instrument samples embedded in soundfonts have a more complicated
30 structure, and have more features, than GUS patches. So breaking a
31 soundfont up into GUS patches loses information and quality, unless the
32 GUS patch format is extended. The patch files produced by unsf do con‐
33 tain most of the information and structure they had as part of the
34 original soundfont, but the extensions to GUS format are tucked away in
35 hidden places, as they must be, to be compatible with programs expect‐
36 ing to see ordinary GUS patches. I'll describe the extensions below.
37 Unsf is easy to use. If you're using a version of timidity, just put a
39 soundfont into the directory where you keep patches -- perhaps
40 /usr/local/lib/timidity -- then cd to that directory and say "unsf
41 filename.sf2". Unsf will create directories for each bank of instru‐
42 ments in the soundfont and put the patch files for all the instruments
43 into the appropriate bank directories. The names of the directories
44 and patch files are derived from the names they were given inside the
45 soundfont. Unsf also creates a GUS type configuration file, which will
46 be called "<filename>.cfg", the <filename> part coming from the name of
47 the original soundfont. Edit timidity.cfg by adding the line "source
48 <filename>.cfg" and you're ready to use the new patches.
49 However, you won't hear any of the enhancements of sf2 instruments,
51 unless you use my reference version of timidity, because no other midi
52 players as yet know how to find the special information in the extended
53 GUS patch files. How could there be any? I just made up this exten‐
54 sion to GUS patch structure. What you will hear is only the keyrange
55 set of samples for the left channel of the first velocity layer. Sf2
56 instruments can have several velocity layers, meaning sets of samples
57 tuned for the different timbres produced by different note loudness,
58 and they can also be in stereo, with different sets of samples for the
59 left and right channels.
60 This diagram describes the overall structure of sf2 instruments and
63 extended GUS patches:
64 key range 1 sample |GUS
66 left channel key range 2 sample |compatible
67 velocity range 1 ... |part
68 key range 1 sample
69 right channel key range 2 sample
70 ...
71 left channel ...
73 Instrument velocity range 2
74 right channel ...
75 velocity range 3 ...
77 ...
79 velocity range 19 ...
81 In addition to the extra sets of samples for various velocity (loud‐
83 ness) ranges and for left and right channels, sf2 instruments have
84 parameters for controlling an extra low frequency modulator and a band‐
85 pass filter. These parameters are also carried over into the extended
86 GUS patches produced by unsf. My reference version of timidity does
87 not interpret and use all this extra information, by any means, but it
88 does understand velocity ranges, stereo instruments, and a couple of
89 the extra sf2 parameters: volume-envelope-delay and exclusive-class.
90 The first delays the beginning of note volume envelopes by a variable
91 amount, and the second causes notes of certain instruments to be termi‐
92 nated when a new note of that instrument or an instrument in the same
93 class is begun.
94 My reference version of timidity is the one contained the the SDL_mixer
96 library of the gaming program library SDL (Simple Direct Layer),
97 http://www.libsdl.org. As of now (Sept 2004) only the CVS version of
98 SDL_mixer has my version of timidity. My patches for the latest
99 released version are in the archive:
100 ftp://ling.lll.hawaii.edu/pub/greg/Surround-SDL.tgz
101 I have also made a free standing demo version of timidity, which is in:
102 ftp://ling.lll.hawaii.edu/pub/greg/gt-0.3.tar.gz
103
106 -s Small. Extract only a single velocity layer.
107 -m Mono. Extract only the left channel of stereo patches.
109 -d Drum. Assume the sf2 file is a drum kit, even though it is not
111 marked as such in the soundfont, so that individual notes are
112 broken out into separate drum patches.
113 -n No write. Don't write out patches or directories.
115 -V Do not normalize sample volumes (it's time-consuming).
117 -F Adjust sustain by guessing which looping patches should be con‐
119 tinued until note is released.
120 -v Verbose.
122 -M <bank>:<instrument>=<layer>
124 Make the given velocity layer the default for bank:instrument,
125 this affects programs which do not know howto handle the
126 extended GUS patch format, as they will always play the default
127 layer, and this determines which layer gets written when using
128 -s.
129 -D <bank>:<instrument>=<layer>
131 Same as -M but then for drum banks.
132
135 Greg Lee <greg@ling.lll.hawaii.edu>
136 SoundFont loader based on code provided by George Foot.
137 SoundFont file extension written by Takashi Iwai <iwai@dragon.mm.t.u-
138 tokyo.ac.jp>
139 Version 0.0.1, 19th Sept 2004 UNSF(1)