Upload waveforms with Bonsai
The Harp.SoundCard Bonsai package supports preload and update of sound waveforms during runtime. The following exercises will demonstrate how to generate and load various waveforms for upload to the Sound Card in Bonsai. To read sound metadata or delete the sounds stored on the device, refer to the Manage stored sounds article.
Tip
Alternatively, you can generate and upload waveforms with the Sound Card app without building a workflow.
Before beginning:
- Install the
Harp.SoundCard,Bonsai.Numerics, andBonsai.StarterPackpackages from the Bonsai package manager. - Connect an amplifier and speaker to an output channel by following the audio connection instructions.
- Connect the power supply and both USB cables by following the power and PC connection instructions. Uploading needs the USB (Soundbank) cable.
- Install the driver.
- Launch "Bonsai" from the Windows Start menu.
UpdateSoundWaveform
Uploading of waveforms is done with the UpdateSoundWaveform operator, which interfaces directly with the Sound Card onboard memory via libusb (not HarpMessage commands).
For each of the following exercises, configure these properties for the UpdateSoundWaveform operator:
Description- Set the description of the sound to be stored in the device. This field is optional.DeviceIndex- Set the index of the Sound Card to update. If no index is specified, the first Sound Card will be used.SampleRate- Set the sample rate used for playback. Only 96 kHz or 192 kHz are supported.SoundIndex- Set the index of the sound to update. The Sound Card onboard memory is partitioned into 32 indices, of which index 2–31 can be used for storing waveforms.SoundName- Set the name of the sound to be stored in the device. This field is optional.
Continuous streaming of sample buffers is not supported, so the entire waveform must be sent during upload. Dynamic update of waveforms when another sound is playing is only possible for waveforms with a 96 kHz sample rate.
Waveform requirements
Type- TheUpdateSoundWaveformoperator acceptsbyte[]andMattype inputs. For these exercises, we will useMat, a matrix format commonly used for audio data in Bonsai, where rows represent channels and columns represent samples.Bit Depth- Waveforms must be encoded as 32-bit signed integers (S32).Channels- Both mono and stereo waveforms are supported.Size- Each sound index on the Sound Card memory can store an 8 MiB file, corresponding to ~2 million samples. Mono waveforms are duplicated for dual-channel playback and occupy the same amount of storage space as stereo waveforms.
Given these parameters, sounds are limited to a length of 10.922 s at a 96 kHz sample rate, or 5.461 s at 192 kHz.
Generate periodic waveform
Pure tones and other periodic waveforms can be generated using a function generator. Sound length is determined by the number of samples in combination with the sampling rate.
- Insert a
KeyDownsource and set theFilterproperty toA. - Insert a
FunctionGeneratorsource and configure the following properties:Amplitude- Set the volume in 32-bit range (e.g.2147483647for max value).BufferLength- Set the number of samples (e.g.192000for a 2 s sound at 96 kHz sample rate).Depth- SelectS32for 32-bit signed integers.Frequency- Set the frequency of the pure tone, in Hz (e.g.2000).SampleRate- Set the sample rate, in Hz (e.g.96000).Waveform- SelectSinefor pure tones.
- Insert a
UpdateSoundWaveformoperator and configure the relevant properties.
Run the workflow and press the A key to upload the waveform. Play it back with the sound index.
Warning
FunctionGenerator should always be connected to another trigger source to prevent continuous buffer generation. KeyDown can be replaced with other operators, such as a one-shot Timer.
Generate white noise waveform
White noise can be generated by randomly sampling from a discrete uniform distribution.
- Insert a
CreateDiscreteUniformsource and set theLowerandUpperproperties to the volume in 32-bit range. - Insert a
SampleArrayoperator and set theCountproperty to the number of samples to draw (e.g.192000for a 2 s sound at 96 kHz sample rate). - Insert a
Sampleoperator. - Insert a
KeyDownsource and set theFilterproperty toA. - Insert a
ConvertFromArraytransform and set theDepthproperty toS32. - Insert a
UpdateSoundWaveformoperator and configure the relevant properties.
Run the workflow and press the A key to upload the waveform. Play it back with the sound index.
Load waveform from WAV file
Waveforms can be loaded from uncompressed WAV files, but will require bit depth conversion and scaling.
- Insert a
KeyDownsource and set theFilterproperty toA. - Insert an
AudioReadersource and configure the following properties:BufferLength- Set0to load the entire file into a single buffer (SampleRateis ignored here).FileName- Set the file path of the WAV file to load.
- Insert a
ConvertScaletransform and configure the following properties:Depth- SelectS32for 32-bit signed integers.Scale- Set the scaling factor to fit theS32range (e.g.65536for a 1:1 conversion from a 16-bit WAV file).
- Insert a
UpdateSoundWaveformoperator and configure the relevant properties.
Run the workflow and press the A key to upload the waveform. Play it back with the sound index.
Warning
24-bit (or higher) and WAVE_FORMAT_EXTENSIBLE WAV files are not currently supported by AudioReader.
Load waveform from raw binary matrix file
Waveforms can also be loaded from raw binary matrix files (*.bin).
- Insert a
KeyDownsource and set theFilterproperty toA. - Insert a
MatrixReadersource and configure the following properties:BufferLength- Set0to load the entire file into a single buffer (SampleRateis ignored here).ChannelCount- Set the number of channels in the file (1for mono or2for stereo).Depth- Select the bit depth of the input file (e.g.S32).Layout- For mono files, this has no effect. For stereo files, selectRowMajorif the channels are stored sequentially, orColumnMajorif the channels are interleaved.Path- Set the file path of the*.binfile to load.
- Insert a
UpdateSoundWaveformoperator and configure the relevant properties.
Run the workflow and press the A key to upload the waveform. Play it back with the sound index.
Tip
Add a ConvertScale after MatrixReader if the *.bin bit depth is not S32.
Documentation for release v3.0.0