mirror/oot
1
0
Fork 0
mirror of https://github.com/zeldaret/oot.git synced 2025-01-15 12:47:04 +00:00
Code Issues Projects Releases Wiki Activity
oot/docs/audio/Soundfont_XML.md
Tharo df5d4cb467
[Audio 10/10] Loose ends (#2337) 
* Introduce afile_sizes, generate headers of sizes for soundfonts and sequences

* Initial tools/audio README

* Versioning for samplebank extraction

* Clean up the disassemble_sequence.py runnable interface

* Add static assertions for maximum bank sizes

* Boost optimization for audio tools

* Samplebank XML doc

* Soundfont XML doc

* More docs in sampleconv for vadpcm

* Various tools fixes/cleanup

* VADPCM doc

* Try to fix md formatting

* VADPCM doc can come later

* Fix merge with PR 9

* Fix blobs from MM

* Try to fix bss

* Try fix bss round 2

* Fix sampleconv memset bug

* Suggested documentation tweaks
2024-12-13 19:26:36 -05:00

12 KiB
Raw Blame History

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 Names 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.

<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.
  • [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

  • <Envelopes>

    Lists envelopes defined in this soundfont.

    Attributes

    N/A

    Tags

    • <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

      • <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
      • <Disable/>

        Insert a ADSR_DISABLE command

      • <Hang/>

        Insert a ADSR_HANG command

      • <Goto
    Index="<uint>"
/>

        Insert a ADSR_GOTO command

        Attributes

        • Index: Index of the envelope point to jump to
      </Envelope>

    </Envelopes>

  • <Samples
    IsDD="[Bool]"
    Cached="[Bool]"
>

    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

    • <Sample
    Name="<C Identifier>"
    SampleRate="[Sample Rate]"
    BaseNote="[Note Name]"
    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.
      • [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.
    </Samples>

  • <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

    • <Effect
    Name="<C Identifier>"
    Sample="<Sample Name>"
    SampleRate="[Sample Rate]"
    BaseNote="[Note Name]"
/>

      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.
    </Effects>

  • <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

    • <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]"
/>

      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.
    </Drums>

  • <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

    • <Instrument
    ProgramNumber="<>"
    Name="<C Identifier>"
    Envelope="<Envelope Name>"
    Release="[u8]"

    Sample="<Sample Name>"
    SampleRate="[Sample Rate]"
    BaseNote="[Note Name]"

    RangeLo="[Note Name]"
    SampleLo="[Sample Name]"
    SampleRateLo="[Sample Rate]"
    BaseNoteLo="[Note Name]"

    RangeHi="[Note Name]"
    SampleHi="[Sample Name]"
    SampleRateHi="[Sample Rate]"
    BaseNoteHi="[Note Name]"
/>

      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.
    </Instruments>

</Soundfont>