1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
|
# Soundfont XML Format Specification
Soundfont XMLs describe the layout of a single soundfont. These package raw samples together into instruments, of which there are three kinds:
- **Effects**: These are simple sound effects that just play a single sample without any modulation.
- **Drums**: These define a MIDI-style percussion key map.
- **Instruments**: These are instruments that may be played at any key with up to three voices and may be modulated by an envelope.
In the specification, `Note Name`s can be either a MIDI note name e.g. `C4` or it may be a **Zelda64** note number, which are related to MIDI note numbers ($n$) by $(n - 21) \mod 128$.
---
```xml
<Soundfont
Name="<C Identifier>"
Index="<uint>"
Medium="<Medium>"
CachePolicy="<CachePolicy>"
SampleBank="<Path>"
Indirect="[uint]"
SampleBankDD="[Path]"
IndirectDD="[uint]"
LoopsHaveFrames="[bool]"
PadToSize="[uint]"
NumInstruments="[uint]"
>
```
Begins a new soundfont.
**Attributes**
- **Name**: Soundfont symbol name. Must be a valid C identifier.
- **Index**: Soundfont index. Must be an integer.
- **Medium**: Storage medium. Must be an enum name from `SampleMedium`.
- **CachePolicy**: Cache policy. Must be an enum name from `AudioCacheLoadType`.
- **SampleBank**: Path to samplebank xml used by this soundfont.
- <ins>[Optional]</ins> **Indirect**: Pointer index if the samplebank is referenced indirectly.
- <ins>[Optional]</ins> **SampleBankDD**: Path to samplebank xml used for DD medium.
- <ins>[Optional]</ins> **IndirectDD**: Pointer index if the DD samplebank is referenced indirectly.
- <ins>[Optional]</ins> **LoopsHaveFrames**: Whether loops in this soundfont store the total frame count of the sample. Must be a boolean.
- <ins>[Optional]</ins> **PadToSize**: For matching only. Specifies the total file size the result output should be padded to.
- <ins>[Optional]</ins> **NumInstruments**: For matching only. Specifies the total number of instrument pointers. Usually this is automatically assigned based on `max(program_number) + 1` but some vanilla banks don't match this way.
**Tags**
-
```xml
<Envelopes>
```
Lists envelopes defined in this soundfont.
**Attributes**
N/A
**Tags**
-
```xml
<Envelope
Name="<C Identifier>"
Release="<u8>"
>
```
Starts a new envelope.
**Attributes**
- **Name**: Unique name for this envelope. Must be a valid C identifier.
- **Release**: Release rate index (into `gAudioCtx.adsrDecayTable`) for this envelope
**Tags**
-
```xml
<Point
Delay="<s16>"
Arg="<s16>"
/>
```
Add a point to the envelope at (delay, arg)
**Attributes**
- **Delay**: Duration until the next point
- **Arg**: Value of the envelope at this point
---
-
```xml
<Disable/>
```
Insert a ADSR_DISABLE command
---
-
```xml
<Hang/>
```
Insert a ADSR_HANG command
---
-
```xml
<Goto
Index="<uint>"
/>
```
Insert a ADSR_GOTO command
**Attributes**
- **Index**: Index of the envelope point to jump to
---
```xml
</Envelope>
```
---
```xml
</Envelopes>
```
---
-
```xml
<Samples
IsDD="[Bool]"
Cached="[Bool]"
>
```
Begins a list of samples used in this Soundfont.
**Attributes**
- <ins>[Optional]</ins> **IsDD**: Whether all the samples in the list are on the Disk Drive. The sample data will come from the samplebank `SampleBankDD`. **Default is `false`.** **NOTE this is not fully implemented, it should always be `false`.**
- <ins>[Optional]</ins> **Cached**: Whether all the samples in the list should be added to the `usedSamples` cache. **Default is `false`.**
**Tags**
-
```xml
<Sample
Name="<C Identifier>"
SampleRate="[Sample Rate]"
BaseNote="[Note Name]"
FineTune="[Fine Tune]"
IsDD="[Bool]"
Cached="[Bool]"
/>
```
Declares a sample used in this soundfont.
**Attributes**
- **Name**: The name of this sample. A sample with this name must be present in the samplebank used by the soundfont.
- <ins>[Optional]</ins> **SampleRate**: An overriding sample rate for this sample. **Default comes from the sample file.**
- <ins>[Optional]</ins> **BaseNote**: An overriding root key for this sample. **Default comes from the sample file.**
- <ins>[Optional]</ins> **FineTune**: An overriding fine tuning for this sample, in cents, in the range [-100, 100]. **Default comes from the sample file.**
- <ins>[Optional]</ins> **IsDD**: Whether this sample is on the Disk Drive. The sample data will come from the samplebank `SampleBankDD`. **Default is `false`.** **NOTE this is not fully implemented, it should always be `false`.**
- <ins>[Optional]</ins> **Cached**: Whether this sample should be added to the `usedSamples` cache. **Default is `false`.**
---
```xml
</Samples>
```
---
-
```xml
<Effects>
```
Begins a list of sound effects to define for this soundfont. Sound effects correspond to simple sounds that cannot be played at different keys.
**Attributes**
N/A
**Tags**
-
```xml
<Effect
Name="<C Identifier>"
Sample="<Sample Name>"
SampleRate="[Sample Rate]"
BaseNote="[Note Name]"
FineTune="[Fine Tune]"
/>
```
Defines a single sound effect.
**Attributes**
- **Name**: The name of the sound effect, the name is made available in sequence files in the form `SF{n}_{name}` where `n` is the index of this soundfont and `name` is this name. For example, if `n=0` and `name=ExampleEffect` the name to use in sequence files is `SF0_ExampleEffect`.
- **Sample**: The name of the sample associated with this effect.
- <ins>[Optional]</ins> **SampleRate**: An overriding sample rate for this effect. **Default comes from the sample definition.**
- <ins>[Optional]</ins> **BaseNote**: An overriding root key for this effect. **Default comes from the sample definition.**
- <ins>[Optional]</ins> **FineTune**: An overriding fine tuning for this effect, in cents, in the range [-100, 100]. **Default comes from the sample definition.**
---
```xml
</Effects>
```
---
-
```xml
<Drums>
```
Begins the percussion definitions for this soundfont. Percussion corresponds to the MIDI notion of percussion, where single samples are mapped across a range of keys.
**Attributes**
N/A
**Tags**
-
```xml
<Drum
Name="<C Identifier>"
Note="[Note Name]"
NoteStart="[Note Name]"
NoteEnd="[Note Name]"
Pan="<u8>"
Envelope="<Envelope Name>"
Release="[u8]"
Sample="<Sample Name>"
SampleRate="[Sample Rate]"
BaseNote="[Note Name]"
FineTune="[Fine Tune]"
/>
```
Defines a single percussion range.
**Attributes**
- **Name**: The name of this sound. Definitions are emitted for sequence files in the form `SF{n}_{name}_{note}` for every note covered by this sound.
- <ins>[Optional]</ins> **Note**: The key to map this sound to. Should not overlap with other definitions. **If this field is left unspecified, `NoteStart` and `NoteEnd` become required.**
- <ins>[Optional]</ins> **NoteStart**: The first key that is mapped to this sound. Should not overlap with other definitions. **If this field is left unspecified, `Note` becomes required. If this field is specified, `NoteEnd` must also be specified.**
- <ins>[Optional]</ins> **NoteEnd**: The last key that is mapped to this sound. Should not overlap with other definitions. **If this field is left unspecified, `Note` becomes required. If this field is specified, `NoteStart` must also be specified.**
- **Pan**: The stereo weight for this sound. Center=`64`.
- **Envelope**: The envelope to modulate the volume over time with. Must be defined in the `Envelopes` list.
- <ins>[Optional]</ins> **Release**: An override for the envelope release rate. **Default is the release rate specified in the envelope definition**
- **Sample**: The name of the sample to use.
- <ins>[Optional]</ins> **SampleRate**: An overriding sample rate for this sound. **Default comes from the sample definition.**
- <ins>[Optional]</ins> **BaseNote**: An overriding root key for this sound. **Default comes from the sample definition.**
- <ins>[Optional]</ins> **FineTune**: An overriding fine tuning for this sound, in cents, in the range [-100, 100]. **Default comes from the sample definition.**
---
```xml
</Drums>
```
---
-
```xml
<Instruments>
```
Begins the instrument definitions for this soundfont. Instruments correspond to the MIDI notion of instruments, with up to 3 samples (voices) per instrument that must map to contiguous ranges of notes.
**Attributes**
N/A
**Tags**
-
```xml
<Instrument
ProgramNumber="<>"
Name="<C Identifier>"
Envelope="<Envelope Name>"
Release="[u8]"
Sample="<Sample Name>"
SampleRate="[Sample Rate]"
BaseNote="[Note Name]"
FineTune="[Fine Tune]"
RangeLo="[Note Name]"
SampleLo="[Sample Name]"
SampleRateLo="[Sample Rate]"
BaseNoteLo="[Note Name]"
FineTuneLo="[Fine Tune]"
RangeHi="[Note Name]"
SampleHi="[Sample Name]"
SampleRateHi="[Sample Rate]"
BaseNoteHi="[Note Name]"
FineTuneHi="[Fine Tune]"
/>
```
Defines an instrument.
**Attributes**
- **ProgramNumber**: MIDI Program Number for this instrument. Must be in the range `0 <= n <= 125`
- **Name**: The name of this instrument.
- **Envelope**: Envelope to use, identified by name.
- <ins>[Optional]</ins> **Release**: Release rate index override. **Default release rate comes from the chosen envelope.**
- **Sample**: The name of the middle sample to use for this instrument.
- <ins>[Optional]</ins> **SampleRate**: Sample rate override for the middle sample. **Default is sourced from the sample properties.**
- <ins>[Optional]</ins> **BaseNote**: Base note override for the middle sample. **Default is sourced from the sample properties.**
- <ins>[Optional]</ins> **FineTune**: Fine tuning override for the middle sample, in cents, in the range [-100, 100]. **Default is sourced from the sample properties.**
- <ins>[Optional]</ins> **RangeLo**: The largest note for SampleLo. SampleLo will be used instead of Sample for keys in the range [0, RangeLo]. **If left unspecified, SampleLo must not be specified. If specified, SampleLo must be specified.**
- <ins>[Optional]</ins> **SampleLo**: The name of the low sample to use for this instrument.
- <ins>[Optional]</ins> **SampleRateLo**: Sample rate override for the low sample. **Default is sourced from the sample properties.**
- <ins>[Optional]</ins> **BaseNoteLo**: Base note override for the low sample. **Default is sourced from the sample properties.**
- <ins>[Optional]</ins> **FineTuneLo**: Fine tuning override for the low sample, in cents, in the range [-100, 100]. **Default is sourced from the sample properties.**
- <ins>[Optional]</ins> **RangeHi**: The smallest note for SampleHi. SampleHi will be used instead of Sample for keys in the range [RangeHi, 127]. **If left unspecified, SampleHi must not be specified. If specified, SampleHi must be specified.**
- <ins>[Optional]</ins> **SampleHi**: The name of the high sample to use for this instrument.
- <ins>[Optional]</ins> **SampleRateHi**: Sample rate override for the high sample. **Default is sourced from the sample properties.**
- <ins>[Optional]</ins> **BaseNoteHi**: Base note override for the high sample. **Default is sourced from the sample properties.**
- <ins>[Optional]</ins> **FineTuneHi**: Fine tuning override for the high sample, in cents, in the range [-100, 100]. **Default is sourced from the sample properties.**
---
```xml
</Instruments>
```
---
```xml
</Soundfont>
```
---
|
