Table of Contents

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, and Bonsai.StarterPack packages 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).

UpdateSoundWaveform operator

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 - The UpdateSoundWaveform operator accepts byte[] and Mat type inputs. For these exercises, we will use Mat, 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.

Upload waveform pure tone

  • Insert a KeyDown source and set the Filter property to A.
  • Insert a FunctionGenerator source and configure the following properties:
    • Amplitude - Set the volume in 32-bit range (e.g. 2147483647 for max value).
    • BufferLength - Set the number of samples (e.g. 192000 for a 2 s sound at 96 kHz sample rate).
    • Depth - Select S32 for 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 - Select Sine for pure tones.
  • Insert a UpdateSoundWaveform operator 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.

Upload waveform white noise

  • Insert a CreateDiscreteUniform source and set the Lower and Upper properties to the volume in 32-bit range.
  • Insert a SampleArray operator and set the Count property to the number of samples to draw (e.g. 192000 for a 2 s sound at 96 kHz sample rate).
  • Insert a Sample operator.
  • Insert a KeyDown source and set the Filter property to A.
  • Insert a ConvertFromArray transform and set the Depth property to S32.
  • Insert a UpdateSoundWaveform operator 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.

Upload waveform WAV file

  • Insert a KeyDown source and set the Filter property to A.
  • Insert an AudioReader source and configure the following properties:
    • BufferLength - Set 0 to load the entire file into a single buffer (SampleRate is ignored here).
    • FileName - Set the file path of the WAV file to load.
  • Insert a ConvertScale transform and configure the following properties:
    • Depth - Select S32 for 32-bit signed integers.
    • Scale - Set the scaling factor to fit the S32 range (e.g. 65536 for a 1:1 conversion from a 16-bit WAV file).
  • Insert a UpdateSoundWaveform operator 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).

Upload waveform BIN file

  • Insert a KeyDown source and set the Filter property to A.
  • Insert a MatrixReader source and configure the following properties:
    • BufferLength - Set 0 to load the entire file into a single buffer (SampleRate is ignored here).
    • ChannelCount - Set the number of channels in the file (1 for mono or 2 for stereo).
    • Depth - Select the bit depth of the input file (e.g. S32).
    • Layout - For mono files, this has no effect. For stereo files, select RowMajor if the channels are stored sequentially, or ColumnMajor if the channels are interleaved.
    • Path - Set the file path of the *.bin file to load.
  • Insert a UpdateSoundWaveform operator 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