.. _stdlib_strudel_sf2: ======================= SoundFont 2 file parser ======================= .. das:module:: strudel_sf2 Module strudel_sf2 +++++++++ Constants +++++++++ .. _global-strudel_sf2-SF2_SAMPLE_MONO: .. das:attribute:: SF2_SAMPLE_MONO = 0x1 SF2_SAMPLE_MONO:uint const .. _global-strudel_sf2-SF2_SAMPLE_RIGHT: .. das:attribute:: SF2_SAMPLE_RIGHT = 0x2 SF2_SAMPLE_RIGHT:uint const .. _global-strudel_sf2-SF2_SAMPLE_LEFT: .. das:attribute:: SF2_SAMPLE_LEFT = 0x4 SF2_SAMPLE_LEFT:uint const .. _global-strudel_sf2-SF2_SAMPLE_LINKED: .. das:attribute:: SF2_SAMPLE_LINKED = 0x8 SF2_SAMPLE_LINKED:uint const ++++++++++++ Enumerations ++++++++++++ .. _enum-strudel_sf2-SF2GenOper: .. das:attribute:: SF2GenOper enum SF2GenOper ++++++++++ Structures ++++++++++ .. _struct-strudel_sf2-SF2SampleHeader: .. das:attribute:: 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). .. _struct-strudel_sf2-SF2Generator: .. das:attribute:: 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). .. _struct-strudel_sf2-SF2Modulator: .. das:attribute:: 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). .. _struct-strudel_sf2-SF2Zone: .. das:attribute:: 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< :ref:`SF2Generator `> - Generators that modify voice parameters for this zone. * **modulators** : array< :ref:`SF2Modulator `> - Modulators that route dynamic sources to generators. .. _struct-strudel_sf2-SF2InstrumentDef: .. das:attribute:: SF2InstrumentDef :Fields: * **name** : string - Instrument name. * **global_zone** : :ref:`SF2Zone `? - Optional global zone whose generators apply to all zones. * **zones** : array< :ref:`SF2Zone `?> - Instrument zones, each mapping a key/velocity region to a sample. .. _struct-strudel_sf2-SF2PresetDef: .. das:attribute:: SF2PresetDef :Fields: * **name** : string - Preset name. * **preset** : int - MIDI program number (0-127). * **bank** : int - MIDI bank number. * **global_zone** : :ref:`SF2Zone `? - Optional global zone whose generators apply to all zones. * **zones** : array< :ref:`SF2Zone `?> - Preset zones, each mapping a key/velocity region to an instrument. .. _struct-strudel_sf2-SF2File: .. das:attribute:: SF2File :Fields: * **name** : string - Soundfont name from the INFO chunk. * **sample_data** : array - Raw 16-bit PCM sample data. * **samples** : array< :ref:`SF2SampleHeader `> - Sample headers describing each sample region. * **instruments** : array< :ref:`SF2InstrumentDef `?> - Instrument definitions. * **presets** : array< :ref:`SF2PresetDef `?> - Preset definitions. * **preset_lookup** : table - Fast lookup: (bank << 8 | program) -> index into presets. .. _struct-strudel_sf2-RawPresetHeader: .. das:attribute:: RawPresetHeader struct RawPresetHeader .. _struct-strudel_sf2-RawInstrumentHeader: .. das:attribute:: RawInstrumentHeader struct RawInstrumentHeader .. _struct-strudel_sf2-RawBag: .. das:attribute:: RawBag struct RawBag +++++++ Loading +++++++ * :ref:`sf2_load (path: string) : SF2File? ` * :ref:`sf2_parse (data: array\) : SF2File? ` .. _function-strudel_sf2_sf2_load_string: .. das:function:: sf2_load(path: string) : SF2File? Load and parse an SF2 soundfont file from disk. :Arguments: * **path** : string .. _function-strudel_sf2_sf2_parse_array_ls_uint8_gr_: .. das:function:: sf2_parse(data: array) : SF2File? Parse SF2 data from a byte array. :Arguments: * **data** : array ++++++++++++++++++++++ Preset and zone lookup ++++++++++++++++++++++ * :ref:`sf2_find_preset (sf2: SF2File; bank: int; program: int) : int ` * :ref:`sf2_find_zones (sf2: SF2File; preset_index: int; key: int; velocity: int) : array\ ` .. _function-strudel_sf2_sf2_find_preset_SF2File_int_int: .. das:function:: 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** : :ref:`SF2File ` * **bank** : int * **program** : int .. _function-strudel_sf2_sf2_find_zones_SF2File_int_int_int: .. das:function:: sf2_find_zones(sf2: SF2File; preset_index: int; key: int; velocity: int) : array Find instrument zones matching a key and velocity for a given preset. Returns array of (instrument_index, zone_index) pairs. :Arguments: * **sf2** : :ref:`SF2File ` * **preset_index** : int * **key** : int * **velocity** : int ++++++++++++++++ Generator access ++++++++++++++++ * :ref:`get_generator (zone: SF2Zone; oper: int; def_val: int = 0) : int ` * :ref:`get_generator_range (zone: SF2Zone; oper: int) : int2 ` * :ref:`has_generator (zone: SF2Zone; oper: int) : bool ` .. _function-strudel_sf2_get_generator_SF2Zone_int_int: .. das:function:: 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** : :ref:`SF2Zone ` * **oper** : int * **def_val** : int .. _function-strudel_sf2_get_generator_range_SF2Zone_int: .. das:function:: 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: * **zone** : :ref:`SF2Zone ` * **oper** : int .. _function-strudel_sf2_has_generator_SF2Zone_int: .. das:function:: has_generator(zone: SF2Zone; oper: int) : bool Check whether a zone has a specific generator. :Arguments: * **zone** : :ref:`SF2Zone ` * **oper** : int +++++++++++++++ Unit conversion +++++++++++++++ * :ref:`centibels_to_linear (cb: int) : float ` * :ref:`cents_to_hz (cents: int) : float ` * :ref:`timecents_to_seconds (tc: int) : float ` .. _function-strudel_sf2_centibels_to_linear_int: .. das:function:: centibels_to_linear(cb: int) : float Convert centibels to linear amplitude. :Arguments: * **cb** : int .. _function-strudel_sf2_cents_to_hz_int: .. das:function:: cents_to_hz(cents: int) : float Convert SF2 cents to Hz (relative to 8.176 Hz). :Arguments: * **cents** : int .. _function-strudel_sf2_timecents_to_seconds_int: .. das:function:: timecents_to_seconds(tc: int) : float Convert SF2 timecents to seconds. :Arguments: * **tc** : int ++++++++++++++++++++++++ Modulator source helpers ++++++++++++++++++++++++ * :ref:`sf2_mod_src_bipolar (src: int) : bool ` * :ref:`sf2_mod_src_cc (src: int) : bool ` * :ref:`sf2_mod_src_index (src: int) : int ` * :ref:`sf2_mod_src_negative (src: int) : bool ` * :ref:`sf2_mod_src_type (src: int) : int ` .. _function-strudel_sf2_sf2_mod_src_bipolar_int: .. das:function:: sf2_mod_src_bipolar(src: int) : bool Return true if the modulator source polarity is bipolar (bit 9 set). :Arguments: * **src** : int .. _function-strudel_sf2_sf2_mod_src_cc_int: .. das:function:: sf2_mod_src_cc(src: int) : bool Return true if the modulator source is a MIDI CC (bit 7 set). :Arguments: * **src** : int .. _function-strudel_sf2_sf2_mod_src_index_int: .. das:function:: sf2_mod_src_index(src: int) : int Extract the source index (bits 0-6) from a packed modulator source operand. :Arguments: * **src** : int .. _function-strudel_sf2_sf2_mod_src_negative_int: .. das:function:: sf2_mod_src_negative(src: int) : bool Return true if the modulator source direction is negative (bit 8 set). :Arguments: * **src** : int .. _function-strudel_sf2_sf2_mod_src_type_int: .. das:function:: 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