# 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 ``` 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. - [Optional] **Indirect**: Pointer index if the samplebank is referenced indirectly. - [Optional] **SampleBankDD**: Path to samplebank xml used for DD medium. - [Optional] **IndirectDD**: Pointer index if the DD samplebank is referenced indirectly. - [Optional] **LoopsHaveFrames**: Whether loops in this soundfont store the total frame count of the sample. Must be a boolean. - [Optional] **PadToSize**: For matching only. Specifies the total file size the result output should be padded to. - [Optional] **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 ``` Lists envelopes defined in this soundfont. **Attributes** N/A **Tags** - ```xml ``` 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 ``` 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 ``` Insert a ADSR_DISABLE command --- - ```xml ``` Insert a ADSR_HANG command --- - ```xml ``` Insert a ADSR_GOTO command **Attributes** - **Index**: Index of the envelope point to jump to --- ```xml ``` --- ```xml ``` --- - ```xml ``` Begins a list of samples used in this Soundfont. **Attributes** - [Optional] **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`.** - [Optional] **Cached**: Whether all the samples in the list should be added to the `usedSamples` cache. **Default is `false`.** **Tags** - ```xml ``` 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. - [Optional] **SampleRate**: An overriding sample rate for this sample. **Default comes from the sample file.** - [Optional] **BaseNote**: An overriding root key for this sample. **Default comes from the sample file.** - [Optional] **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`.** - [Optional] **Cached**: Whether this sample should be added to the `usedSamples` cache. **Default is `false`.** --- ```xml ``` --- - ```xml ``` 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 ``` 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. - [Optional] **SampleRate**: An overriding sample rate for this effect. **Default comes from the sample definition.** - [Optional] **BaseNote**: An overriding root key for this effect. **Default comes from the sample definition.** --- ```xml ``` --- - ```xml ``` 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 ``` 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. - [Optional] **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.** - [Optional] **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.** - [Optional] **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. - [Optional] **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. - [Optional] **SampleRate**: An overriding sample rate for this sound. **Default comes from the sample definition.** - [Optional] **BaseNote**: An overriding root key for this sound. **Default comes from the sample definition.** --- ```xml ``` --- - ```xml ``` 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 ``` 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. - [Optional] **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. - [Optional] **SampleRate**: Sample rate override for the middle sample. **Default is sourced from the sample properties.** - [Optional] **BaseNote**: Base note override for the middle sample. **Default is sourced from the sample properties.** - [Optional] **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.** - [Optional] **SampleLo**: The name of the low sample to use for this instrument. - [Optional] **SampleRateLo**: Sample rate override for the low sample. **Default is sourced from the sample properties.** - [Optional] **BaseNoteLo**: Base note override for the low sample. **Default is sourced from the sample properties.** - [Optional] **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.** - [Optional] **SampleHi**: The name of the high sample to use for this instrument. - [Optional] **SampleRateHi**: Sample rate override for the high sample. **Default is sourced from the sample properties.** - [Optional] **BaseNoteHi**: Base note override for the high sample. **Default is sourced from the sample properties.** --- ```xml ``` --- ```xml ``` ---