16.5. SoundFont 2 file parser

Module strudel_sf2

16.5.1. Constants

SF2_SAMPLE_MONO = 0x1

SF2_SAMPLE_MONO:uint const

SF2_SAMPLE_RIGHT = 0x2

SF2_SAMPLE_RIGHT:uint const

SF2_SAMPLE_LEFT = 0x4

SF2_SAMPLE_LEFT:uint const

SF2_SAMPLE_LINKED = 0x8

SF2_SAMPLE_LINKED:uint const

16.5.2. Enumerations

SF2GenOper

enum SF2GenOper

16.5.3. Structures

SF2SampleHeader
Fields:

  • name : string - Sample name (up to 20 characters).

  • start : uint - Start offset in sample data points.

  • end : uint - End offset in sample data points.

  • loop_start : uint - Loop start offset in sample data points.

  • loop_end : uint - Loop end offset in sample data points.

  • sample_rate : uint - Sample rate in Hz.

  • original_pitch : int - MIDI key number of the recorded pitch (0-127).

  • pitch_correction : int - Pitch correction in cents.

  • sample_link : uint - Index of linked sample (for stereo pairs).

  • sample_type : uint - Sample type flags (mono, left, right, linked).

SF2Generator
Fields:

  • oper : int - Generator operator (SF2GenOper enum value).

  • amount_i16 : int - Signed 16-bit amount.

  • amount_lo : int - Low byte of the amount (for range-type generators).

  • amount_hi : int - High byte of the amount (for range-type generators).

SF2Modulator
Fields:

  • src_oper : int - Primary modulator source (packed: index + flags).

  • dest_oper : int - Destination generator operator index.

  • amount : int - Signed modulation amount.

  • amt_src_oper : int - Secondary (amount) modulator source (packed: index + flags).

  • transform : int - Transform type (0=linear, 2=absolute value).

SF2Zone
Fields:

  • key_lo : int = 0 - Lowest MIDI key this zone responds to.

  • key_hi : int = 127 - Highest MIDI key this zone responds to.

  • vel_lo : int = 0 - Lowest MIDI velocity this zone responds to.

  • vel_hi : int = 127 - Highest MIDI velocity this zone responds to.

  • generators : array< SF2Generator> - Generators that modify voice parameters for this zone.

  • modulators : array< SF2Modulator> - Modulators that route dynamic sources to generators.

SF2InstrumentDef
Fields:

  • name : string - Instrument name.

  • global_zone : SF2Zone? - Optional global zone whose generators apply to all zones.

  • zones : array< SF2Zone?> - Instrument zones, each mapping a key/velocity region to a sample.

SF2PresetDef
Fields:

  • name : string - Preset name.

  • preset : int - MIDI program number (0-127).

  • bank : int - MIDI bank number.

  • global_zone : SF2Zone? - Optional global zone whose generators apply to all zones.

  • zones : array< SF2Zone?> - Preset zones, each mapping a key/velocity region to an instrument.

SF2File
Fields:

  • name : string - Soundfont name from the INFO chunk.

  • sample_data : array<int16> - Raw 16-bit PCM sample data.

  • samples : array< SF2SampleHeader> - Sample headers describing each sample region.

  • instruments : array< SF2InstrumentDef?> - Instrument definitions.

  • presets : array< SF2PresetDef?> - Preset definitions.

  • preset_lookup : table<int;int> - Fast lookup: (bank << 8 | program) -> index into presets.

RawPresetHeader

struct RawPresetHeader

RawInstrumentHeader

struct RawInstrumentHeader

RawBag

struct RawBag

16.5.4. Loading

sf2_load(path: string): SF2File?

Load and parse an SF2 soundfont file from disk.

Arguments:

  • path : string

sf2_parse(data: array<uint8>): SF2File?

Parse SF2 data from a byte array.

Arguments:

  • data : array<uint8>

16.5.5. Preset and zone lookup

sf2_find_preset(sf2: SF2File; bank: int; program: int): int

Find a preset by bank and program number. Returns the preset index, or -1 if not found.

Arguments:

  • sf2 : SF2File

  • bank : int

  • program : int

sf2_find_zones(sf2: SF2File; preset_index: int; key: int; velocity: int): array<int2>

Find instrument zones matching a key and velocity for a given preset. Returns array of (instrument_index, zone_index) pairs.

Arguments:

  • sf2 : SF2File

  • preset_index : int

  • key : int

  • velocity : int

16.5.6. Generator access

get_generator(zone: SF2Zone; oper: int; def_val: int = 0): int

Get the value of a generator from a zone. Returns def_val if not found.

Arguments:

  • zone : SF2Zone

  • oper : int

  • def_val : int

get_generator_range(zone: SF2Zone; oper: int): int2

Get the range (low, high) of a range-type generator. Returns int2(0, 127) if not found.

Arguments:
has_generator(zone: SF2Zone; oper: int): bool

Check whether a zone has a specific generator.

Arguments:

16.5.7. Unit conversion

centibels_to_linear(cb: int): float

Convert centibels to linear amplitude.

Arguments:

  • cb : int

cents_to_hz(cents: int): float

Convert SF2 cents to Hz (relative to 8.176 Hz).

Arguments:

  • cents : int

timecents_to_seconds(tc: int): float

Convert SF2 timecents to seconds.

Arguments:

  • tc : int

16.5.8. Modulator source helpers

sf2_mod_src_bipolar(src: int): bool

Return true if the modulator source polarity is bipolar (bit 9 set).

Arguments:

  • src : int

sf2_mod_src_cc(src: int): bool

Return true if the modulator source is a MIDI CC (bit 7 set).

Arguments:

  • src : int

sf2_mod_src_index(src: int): int

Extract the source index (bits 0-6) from a packed modulator source operand.

Arguments:

  • src : int

sf2_mod_src_negative(src: int): bool

Return true if the modulator source direction is negative (bit 8 set).

Arguments:

  • src : int

sf2_mod_src_type(src: int): int

Extract the modulator source curve type (bits 10-15): 0=linear, 1=concave, 2=convex, 3=switch.

Arguments:

  • src : int