SoundFont instruments

soundfont plays a SoundFont 2 bank’s melodic presets, and soundfont_drums plays its kits. Both go through audioinstruments._rack.adapter.create() like the synths, and both answer the audio component contract, so a host that plays one plays the other.

import audioinstruments._rack.adapter as adapter

piano = adapter.create(48000, voice="soundfont", bank="/path/to/bank.sf2")
kit = adapter.create(48000, voice="soundfont_drums", bank="/path/to/bank.sf2")
audio_out.play(piano.output)
piano.program_change(48)        # Strings, in a General MIDI bank
piano.note_on(60, 100)

the rack does not ship a bank, and nothing here downloads one. Without bank= the instrument looks at $SOUNDFONT, then at the first .sf2 in ~/soundfonts/ (%USERPROFILE%\soundfonts on Windows), and raises an OSError that names all three when it finds none. Two instruments made from one file share the open bank and the samples read from it.

Voices, and sharing them

The bank’s samples play on an audiosampler.Sampler. voices= is how many voices it is made with (32 by default); a note takes one voice per zone it resolves to, so a stereo pair takes two. The count can change while you play:

piano.voices = 16        # settable up to what the pool was made with

For room to grow, make the pool yourself and share it, which is also how a General MIDI module’s sixteen parts share one sampler:

from audioinstruments._rack.soundfont import Voices

pool = Voices(48000, 2, voice_count=16, max_voice_count=128)
piano = adapter.create(48000, voice="soundfont", bank=path, voice_pool=pool)
kit = adapter.create(48000, voice="soundfont_drums", bank=path, voice_pool=pool)
audio_out.play(pool.output)       # one output for both

On MicroPython a bank resolves a preset’s zones on its first note, not when it opens. Resolving all of a General MIDI bank’s presets at once leaves the heap in pieces too small for a second instrument’s voice table, so a second create() after a large bank raised MemoryError with megabytes free. Now the first note on a preset takes a moment more, and the bank leaves its room whole. On a desktop the presets are still resolved at open; soundfont.INDEX_AT_OPEN says which.

The ceiling is audiosampler.MAX_VOICES, 128 with audiodsp 0.6.8 or later. A pool’s sampler has only the voices it was asked for, because a voice costs memory whether or not it sounds. A new note with every voice busy steals the oldest releasing voice, then the oldest. inst.voice_pool is the pool an instrument plays on.

The sustain pedal

Control Change 64 at 64 or more holds the notes you let go of until it drops below 64, then releases each with its own release envelope. Keys still held keep sounding. A key struck again while its note is held starts a new note.

Bend range and tuning

The pitch bend moves a note two semitones at full deflection, either way. Set bend_range (in semitones, zero to 48) to change that, and tuning (in semitones, cents as decimals, minus 72 to 72) to tune every note up or down:

inst.bend_range = 12
inst.tuning = -0.5

Notes already sounding follow, and so do the ones still to come. tuning adds to the bend and to the Tune macro. reset() puts them back to 2.0 and 0.0, and each instrument on a shared Voices has its own. A sound module sets them from the registered parameters Pitch Bend Sensitivity, Channel Fine Tuning and Channel Coarse Tuning.

Drum kits

soundfont_drums has one patch per kit in bank 128, named from the bank, and answers General MIDI’s percussion keys 35 to 81. The sixteen pad keys 36 to 51 each sound: a pad the kit has no zone for plays the nearest of the sixteen it does have (the lower on a tie). Two options change that:

adapter.create(48000, voice="soundfont_drums", bank=path, strict_pads=True)
adapter.create(48000, voice="soundfont_drums", bank=path, pad_map={40: 36, 41: 42})

strict_pads=True answers only the keys the kit has a zone for, and pad_map= (a dict, or pairs of keys) replaces the rule with your own table. The two cannot be combined, and kit.strict_pads reports which you have.

Playing from MIDI

audioinstruments._rack.midi_dispatch.MidiDispatcher turns MIDI bytes, adafruit_midi messages or a Standard MIDI File into calls on instruments, by channel. General MIDI’s percussion channel is channel 10 (9 when counted from 0), and drums= takes that channel; nothing treats a controller’s default channel specially.

from audioinstruments._rack.midi_dispatch import MidiDispatcher, read_midi_file

midi = MidiDispatcher(piano, drums=kit)   # channel 10 to the kit, the rest to the piano
midi.feed(buf, n)                          # raw bytes, as a port's readinto() leaves them
for seconds, status, data1, data2 in read_midi_file("song.mid"):
    ...                                    # wait, or render, until `seconds`
    midi.send(status, data1, data2)

examples/soundfont_demo.py plays two bars of drums on channel 10 and then brings a piano in, and writes wav_exports/soundfont_demo.wav.

audioinstruments._rack.midi_cc holds a scaler for each of the 128 Control Change codes, from the host’s 0.0 to 1.0 to the control’s own terms: floats for magnitudes, exactly 0.0 at the middle for bipolar controls, booleans for switches and integers for bank and program numbers.

Step sequencing

audioinstruments._rack.sequencer.Sequencer keeps a pattern’s time in frames on an audiopump.Events queue, so the groove does not move when your timer is late. It plays instruments that can put a note on a frame (inst.schedulable), and none of the rack’s can yet: the SoundFont instruments and the synths take their notes at a block boundary, through sample_position. The sequencer’s tests run against a stand-in that answers the same calls.

Tests

tests/test_sampler_adapter.py and the rest need no bank: they write a small SoundFont of their own. The tests that need a real General MIDI bank (tests/test_soundfont_gm.py, and the last test of tests/test_sampler_adapter.py) look for $FLUIDR3_GM or $SOUNDFONT, then ~/soundfonts/, and skip when there is none. No .sf2 belongs in this repository, and .gitignore keeps one out.