Library Reference

class pico_synth_sandbox.display.Display(board)

Bases: Task

Control the connected 16x2 character display (aka 1602). Hardware connections are abstracted and text writing and cursor management is simplified.

clear()

Remove all text from display and hide and reset cursor position

hide_cursor()

A quick method to hide the cursor.

set_cursor_blink(value)

Set whether or not the cursor should blink.

Parameters:

value (bool) – The blinking state of the cursor.

set_cursor_enabled(value)

Set whether or not the cursor should be displayed.

Parameters:

value (bool) – The visibility of the cursor.

set_cursor_position(column=0, row=0, force=False)

Set the position of the cursor.

Parameters:

• column (int|tuple) – The x-position or column of the cursor which should be between 0 and 15. Can use a tuple of (x,y) to set both column and row.

• row (int) – The y-position or row of the cursor which should be between 0 and 1.

• force (bool) – Force the display to update the cursor position even if it hasn’t changed.

show_cursor(column=0, row=0)

A quick method to ensure that the cursor is being displayed and set the position. Will not cause unnecessary display writes if called multiple times.

Parameters:

• column (int) – The x-position or column of the cursor which should be between 0 and 15.

• row (int) – The y-position or row of the cursor which should be between 0 and 1.

async update(reset_cursor=True)

Write buffer to display. Must be called after any changes are made to the display for those changes to be visible.

Parameters:

reset_cursor (bool) – It is required to manipulate the cursor position in order to make writes to the display. By default, the cursor is reset to the previous position if needed for other applications. If you would like to keep the cursor at it’s newly written location, set this value as False.

write(value, position=(0, 0), length=None, right_aligned=False)

Display a string or number on the display at the designated position. Can be truncated to a specified length and right-aligned.

Parameters:

• value (string, float) – The message or number you would like to display. Any part of the string beyond the first 16 characters or the defined length will not be displayed.

• position (tuple) – Use a tuple of two 0-based integers for the column and row of that you would like to write the value to. Ie: (x,y). The column (x) should be between 0 and 15 and the row (y) should be between 0 and 1.

• length (int) – The length of the message you would like to write. By default, the length will be 16 or the length to the last column of the row from the designated x-position.

• right_aligned – Whether or not you would like to align the data to the right padded by spaces as determined by the designated length.

class pico_synth_sandbox.encoder.Encoder(board, index=0)

Bases: Task

Use the on-board encoder to control your program with simple function callbacks. Supports increment, decrement, click, double click, and long press actions.

set_click(callback)

Set the callback method you would like to be called when the encoder is pressed with a short click (at least 200ms).

Parameters:

callback (function) – The callback method. No callback parameters are defined.

set_decrement(callback)

Set the callback method you would like to be called when the encoder is decremented (turned left).

Parameters:

callback (function) – The callback method. No callback parameters are defined.

set_double_click(callback)

Set the callback method you would like to be called when the encoder is pressed with two short clicks.

Parameters:

callback (function) – The callback method. No callback parameters are defined.

set_increment(callback)

Set the callback method you would like to be called when the encoder is incremented (turned right).

Parameters:

callback (function) – The callback method. No callback parameters are defined.

set_long_press(callback)

Set the callback method you would like to be called when the encoder is pressed with a single long press (at least 500ms).

Parameters:

callback (function) – The callback method. No callback parameters are defined.

async update()

Update the encoder logic and call any pre-defined callbacks if triggered.

class pico_synth_sandbox.keyboard.DebouncerKey(io_or_predicate, invert=False)

Bases: Key

An abstract layer to debouncer sensor input to use physical key objects with the pico_synth_sandbox.keyboard.Keyboard class.

Parameters:

io_or_predicate (ROValueIO | Callable[[], bool]) – The input pin or arbitrary predicate to debounce

NONE = 0

Indicates that the key hasn’t been activated in any way

PRESS = 1

Indicates that the key has been pressed

RELEASE = 2

Indicates that the key has been released

check()

Updates the input pin or arbitraary predicate with basic debouncing and returns the current key state.

Returns:

Key state constant

Return type:

int

get_velocity()

Get the current velocity (0.0-1.0). Typically hard-coded at 1.0.

Returns:

Key velocity

Return type:

float

class pico_synth_sandbox.keyboard.Key

Bases: object

An abstract layer to use physical key objects with the pico_synth_sandbox.keyboard.Keyboard class.

NONE = 0

Indicates that the key hasn’t been activated in any way

PRESS = 1

Indicates that the key has been pressed

RELEASE = 2

Indicates that the key has been released

check()

Updates any necessary logic and returns the current state of the key object.

Returns:

Key state constant

Return type:

int

get_velocity()

Get the current velocity (0.0-1.0). Typically hard-coded at 1.0.

Returns:

Key velocity

Return type:

float

class pico_synth_sandbox.keyboard.Keyboard(keys=[], max_voices=1, root=None)

Bases: Task

Manage note allocation, arpeggiator assignment, sustain, and note callbacks using this class. The root of the keyboard (lowest note) is designated by the KEYBOARD_ROOT variable in settings.toml. The default note allocation mode is defined by the KEYBOARD_MODE variable in settings.toml. This class is inherited by the pico_synth_sandbox.keyboard.TouchKeyboard class.

Parameters:

• keys (array) – An array of Key objects used to include physical key inputs as notes during the update routine.

• max_voices (int) – The maximum number of voices/notes to be played at once.

• root (int) – Set the base note number of the physical key inputs. If left as None, the KEYBOARD_ROOT settings.toml value will be used instead.

• update_frequency (float) – The rate at which the keyboard keys will be polled.

MODE_HIGH = 0

When the keyboard is set as this mode, it will prioritize the highest note value.

MODE_LAST = 2

When the keyboard is set as this mode, it will prioritize notes by the order in when they were played/appended.

MODE_LOW = 1

When the keyboard is set as this mode, it will prioritize the lowest note value.

NUM_MODES = 3

The number of available keyboard note allocation modes.

append(notenum, velocity=1.0, keynum=None, update=True)

Add a note to the keyboard buffer. Useful when working with MIDI input or another note source. Any previous notes with the same notenum value will be removed automatically.

Parameters:

• notenum (int) – The number of the note. Can be defined by MIDI notes, a designated sample index, etc. When using MODE_HIGH or MODE_LOW, the value of this parameter will affect the order.

• velocity (float) – The velocity of the note from 0.0 through 1.0.

• keynum (int) – An additional index reference typically used to associate the note with a physical pico_synth_sandbox.keyboard.Key object. Not required for use of the keyboard.

• update (bool) – Whether or not to update the keyboard logic and potentially trigger any associated callbacks.

get(count=None)

Retrieve the current note allocated according to the keyboard mode. Only a single monophonic note is currently supported, but polyphony up to the initial max_voices value will be added in the future.

Returns:

list of pico_synth_sandbox.keyboard.Note

Return type:

list

get_mode()

Get the current note allocation mode of this object.

Returns:

keyboard mode

Return type:

int

get_notes(include_sustained=True)

Get all active notes in the keyboard object. Notes are tuples with 3 elements of (notenum, velocity, keynum). keynum may be set as None if note came from an external source instead of a pico_synth_sandbox.keyboard.Key object.

Parameters:

include_sustained (bool) – If set as True, any sustained notes will be included in the returned value.

Returns:

note tuples

Return type:

array

get_sustain()

Get the current sustain state of the keyboard.

Returns:

sustain

Return type:

bool

has_note(notenum, include_sustained=True)

Check whether the keyboard has an active note of a particular note value.

Parameters:

include_sustained (bool) – If set as True, any sustained notes (if sustain is active) will be included in the check.

Returns:

has note

Return type:

bool

has_notes(include_sustained=True)

Check whether the keyboard has any active notes.

Parameters:

include_sustained (bool) – If set as True, any sustained notes (if sustain is active) will be included in the check.

Returns:

has notes

Return type:

bool

remove(notenum, update=True, remove_sustained=False)

Remove a note from the keyboard buffer. Useful when working with MIDI input or another note source. If the note is found (and the keyboard isn’t being sustained or remove_sustained is set as True), the release callback will trigger automatically regardless of the update parameter.

Parameters:

• notenum (int) – The number of the note that you would like to removed. All notes in the buffer with this value will be removed. Can be defined by MIDI notes, a designated sample index, etc.

• update (bool) – Whether or not to update the keyboard logic and potentially trigger any associated callbacks.

• remove_sustained (bool) – Whether or not you would like to override the current sustained state of the keyboard and release any notes that are being sustained.

set_arpeggiator(arpeggiator)

Assign an arpeggiator class to the keyboard. Must be of type pico_synth_sandbox.arpeggiator.Arpeggiator or a child of that class. When notes are appended to this object, the arpeggiator will automatically be updated. Callbacks from the arpeggiator will also be routed through the press and release callbacks of this object.

Parameters:

arpeggiator – The arpeggiator object to be assigned ot the keyboard. If this class is called multiple times, the callbacks of the previously allocated arpeggiator will be unassigned.

set_key_press(callback)

Set the callback method you would like to be called when a key is pressed.

Parameters:

callback (function) – The callback method. Must have 3 parameters for keynum, note value, velocity (0.0-1.0), and keynum. Ie: def press(keynum, notenum, velocity):.

set_key_release(callback)

Set the callback method you would like to be called when a key is released.

Parameters:

callback (function) – The callback method. Must have 2 parameters for keynum and note value. Velocity is always assumed to be 0.0. Ie: def release(keynum, notenum):.

set_mode(value)

Set the note allocation mode of this object. Use one of the mode constants of this class such as pico_synth_sandbox.Keyboard.MODE_HIGH. Note allocation won’t be updated until the next update call.

Parameters:

value (int) – The desired mode type.

set_sustain(value, update=True)

Set the sustain state of the keyboard. If sustain is set as True, it will prevent current and future notes from being released until sustain is set as False.

Parameters:

• value (bool) – The desired state of sustain. If sustain is set as False, any notes that are no longer being held will be released immediately.

• update – Whether or not you would like to update the current list notes after changing the sustained state. This may trigger a new note press according to the note allocation rules immediately.

set_voice_press(callback)

Set the callback method you would like to be called when a voice is pressed.

Parameters:

callback (function) – The callback method. Must have 4 parameters for voice index, note value, velocity (0.0-1.0), and keynum (if sourced from a pico_synth_sandbox.keyboard.Key class). Ie: def press(voice, notenum, velocity, keynum=None):.

set_voice_release(callback)

Set the callback method you would like to be called when a voice is released.

Parameters:

callback (function) – The callback method. Must have 3 parameters for voice index, note value, and keynum (if sourced from a pico_synth_sandbox.keyboard.Key class). Velocity is always assumed to be 0.0. Ie: def release(voice, notenum, keynum=None):.

async update()

Update the keyboard logic and call any pre-defined callbacks if triggered. If any pico_synth_sandbox.keyboard.Key objects (during initialization) or an pico_synth_sandbox.arpeggiator.Arpeggiator object (using the set_arpeggiator method) were associated with this object, it will also be updated in this process.

pico_synth_sandbox.keyboard.get_keyboard_driver(board, max_voices=1, root=None)

Automatically generate the proper pico_synth_sandbox.keyboard.Keyboard object based on the device’s settings.toml configuration.

Parameters:

• max_voices (int) – The maximum number of voices/notes to be played at once.

• root (int) – Set the base note number of the physical key inputs. If left as None, the KEYBOARD_ROOT settings.toml value will be used instead.

class pico_synth_sandbox.keyboard.touch.TouchKeyboard(board, max_voices=1, root=None)

Bases: Keyboard

Use the built-in 12 capacitive touch inputs as a pico_synth_sandbox.keyboard.Keyboard object.

Parameters:

• max_voices (int) – The maximum number of voices to be played at once.

• root (int) – Set the base note number of the physical key inputs. If left as None, the KEYBOARD_ROOT settings.toml value will be used instead.

MODE_HIGH = 0

When the keyboard is set as this mode, it will prioritize the highest note value.

MODE_LAST = 2

When the keyboard is set as this mode, it will prioritize notes by the order in when they were played/appended.

MODE_LOW = 1

When the keyboard is set as this mode, it will prioritize the lowest note value.

NUM_MODES = 3

The number of available keyboard note allocation modes.

append(notenum, velocity=1.0, keynum=None, update=True)

Add a note to the keyboard buffer. Useful when working with MIDI input or another note source. Any previous notes with the same notenum value will be removed automatically.

Parameters:

• notenum (int) – The number of the note. Can be defined by MIDI notes, a designated sample index, etc. When using MODE_HIGH or MODE_LOW, the value of this parameter will affect the order.

• velocity (float) – The velocity of the note from 0.0 through 1.0.

• keynum (int) – An additional index reference typically used to associate the note with a physical pico_synth_sandbox.keyboard.Key object. Not required for use of the keyboard.

• update (bool) – Whether or not to update the keyboard logic and potentially trigger any associated callbacks.

get(count=None)

Retrieve the current note allocated according to the keyboard mode. Only a single monophonic note is currently supported, but polyphony up to the initial max_voices value will be added in the future.

Returns:

list of pico_synth_sandbox.keyboard.Note

Return type:

list

get_mode()

Get the current note allocation mode of this object.

Returns:

keyboard mode

Return type:

int

get_notes(include_sustained=True)

Get all active notes in the keyboard object. Notes are tuples with 3 elements of (notenum, velocity, keynum). keynum may be set as None if note came from an external source instead of a pico_synth_sandbox.keyboard.Key object.

Parameters:

include_sustained (bool) – If set as True, any sustained notes will be included in the returned value.

Returns:

note tuples

Return type:

array

get_sustain()

Get the current sustain state of the keyboard.

Returns:

sustain

Return type:

bool

has_note(notenum, include_sustained=True)

Check whether the keyboard has an active note of a particular note value.

Parameters:

include_sustained (bool) – If set as True, any sustained notes (if sustain is active) will be included in the check.

Returns:

has note

Return type:

bool

has_notes(include_sustained=True)

Check whether the keyboard has any active notes.

Parameters:

include_sustained (bool) – If set as True, any sustained notes (if sustain is active) will be included in the check.

Returns:

has notes

Return type:

bool

remove(notenum, update=True, remove_sustained=False)

Remove a note from the keyboard buffer. Useful when working with MIDI input or another note source. If the note is found (and the keyboard isn’t being sustained or remove_sustained is set as True), the release callback will trigger automatically regardless of the update parameter.

Parameters:

• notenum (int) – The number of the note that you would like to removed. All notes in the buffer with this value will be removed. Can be defined by MIDI notes, a designated sample index, etc.

• update (bool) – Whether or not to update the keyboard logic and potentially trigger any associated callbacks.

• remove_sustained (bool) – Whether or not you would like to override the current sustained state of the keyboard and release any notes that are being sustained.

set_arpeggiator(arpeggiator)

Assign an arpeggiator class to the keyboard. Must be of type pico_synth_sandbox.arpeggiator.Arpeggiator or a child of that class. When notes are appended to this object, the arpeggiator will automatically be updated. Callbacks from the arpeggiator will also be routed through the press and release callbacks of this object.

Parameters:

arpeggiator – The arpeggiator object to be assigned ot the keyboard. If this class is called multiple times, the callbacks of the previously allocated arpeggiator will be unassigned.

set_key_press(callback)

Set the callback method you would like to be called when a key is pressed.

Parameters:

callback (function) – The callback method. Must have 3 parameters for keynum, note value, velocity (0.0-1.0), and keynum. Ie: def press(keynum, notenum, velocity):.

set_key_release(callback)

Set the callback method you would like to be called when a key is released.

Parameters:

callback (function) – The callback method. Must have 2 parameters for keynum and note value. Velocity is always assumed to be 0.0. Ie: def release(keynum, notenum):.

set_mode(value)

Set the note allocation mode of this object. Use one of the mode constants of this class such as pico_synth_sandbox.Keyboard.MODE_HIGH. Note allocation won’t be updated until the next update call.

Parameters:

value (int) – The desired mode type.

set_sustain(value, update=True)

Set the sustain state of the keyboard. If sustain is set as True, it will prevent current and future notes from being released until sustain is set as False.

Parameters:

• value (bool) – The desired state of sustain. If sustain is set as False, any notes that are no longer being held will be released immediately.

• update – Whether or not you would like to update the current list notes after changing the sustained state. This may trigger a new note press according to the note allocation rules immediately.

set_voice_press(callback)

Set the callback method you would like to be called when a voice is pressed.

Parameters:

callback (function) – The callback method. Must have 4 parameters for voice index, note value, velocity (0.0-1.0), and keynum (if sourced from a pico_synth_sandbox.keyboard.Key class). Ie: def press(voice, notenum, velocity, keynum=None):.

set_voice_release(callback)

Set the callback method you would like to be called when a voice is released.

Parameters:

callback (function) – The callback method. Must have 3 parameters for voice index, note value, and keynum (if sourced from a pico_synth_sandbox.keyboard.Key class). Velocity is always assumed to be 0.0. Ie: def release(voice, notenum, keynum=None):.

async update()

Update the keyboard logic and call any pre-defined callbacks if triggered. If any pico_synth_sandbox.keyboard.Key objects (during initialization) or an pico_synth_sandbox.arpeggiator.Arpeggiator object (using the set_arpeggiator method) were associated with this object, it will also be updated in this process.

class pico_synth_sandbox.keyboard.touch.TouchPad(pin)

Bases: DebouncerKey

This class is used by the pico_synth_sandbox.keyboard.touch.TouchKeyboard class to handle logic related to the capacitive touch inputs of the hardware platform.

Parameters:

pin (microcontroller.Pin) – The GPIO pin of the capacitive touch input. Must use a pull-down resistor of around 1M ohms.

NONE = 0

Indicates that the key hasn’t been activated in any way

PRESS = 1

Indicates that the key has been pressed

RELEASE = 2

Indicates that the key has been released

check()

Updates the input pin or arbitraary predicate with basic debouncing and returns the current key state.

Returns:

Key state constant

Return type:

int

get_velocity()

Get the current velocity (0.0-1.0). Typically hard-coded at 1.0.

Returns:

Key velocity

Return type:

float

class pico_synth_sandbox.arpeggiator.Arpeggiator(bpm=120, steps=2.0, mode=0, octaves=0, probability=1.0)

Bases: Timer

STEP_DOTTED_QUARTER = 1.5

Dotted quarter note beat division

STEP_EIGHTH = 2.0

Eighth note beat division

STEP_HALF = 0.5

Half note beat division

STEP_QUARTER = 1.0

Quarter note beat division

STEP_SIXTEENTH = 4.0

Sixteenth note beat division

STEP_THIRTYSECOND = 8.0

Thirtysecond note beat division

STEP_TRIPLET = 3.0

Triplet note beat division

STEP_WHOLE = 0.25

Whole note beat division

disable()

Disable the timer object and immediately release any pressed notes.

enable()

Enable the timer object to start timing beat steps and triggering note press and release callbacks. The first step will immediately trigger.

get_bpm()

Get the beats per minute.

Returns:

Beats per minute

Return type:

int

get_gate()

Get the note gate within a step of a beat. This value is a ratio from 0.0 to 1.0.

Returns:

gate

Return type:

float

get_steps()

Get the number of steps per beat (or the beat division).

Returns:

Steps per beat

Return type:

float

is_enabled()

Whether or not the timer object is enabled (running).

Returns:

enabled state

Return type:

bool

set_bpm(value)

Set the beats per minute.

Parameters:

value (int) – The desired beats per minute.

set_enabled(value: bool)

Directly set whether or not the timer object is enabled (running).

Parameters:

value (bool) – The state of the timer.

set_gate(value)

Set the note gate within a step of a beat.

Parameters:

value (float) – The duration of each pressed note per step to play before releasing. This value is a ratio from 0.0 to 1.0.

set_press(callback)

Set the callback method you would like to be called when a timed step note is pressed.

Parameters:

callback (function) – The callback method. Must have 2 parameters for note value and velocity (0.0-1.0). Ie: def press(notenum, velocity):.

set_release(callback)

Set the callback method you would like to be called when a timed step note is released.

Parameters:

callback (function) – The callback method. Must have 1 parameter for note value. Velocity is always assumed to be 0.0. Ie: def release(notenum):.

set_step(callback)

Set the callback method you would like to be called when a step is triggered. This callback will fire whether or not the step has pressed any notes. However, any pressed notes will occur before this callback is called.

Parameters:

callback (function) – The callback method without any parameters. Ie: def step():.

set_steps(value)

Set number of steps per beat (or the beat division). The pre-defined pico_synth_sandbox.Timer.STEP_… constants can be used here.

Parameters:

value (float) – The number of steps to divide a single beat. The minimum value allowed is 0.25, or a whole note.

toggle()

Toggle between the enabled and disabled timer states. Any relevant actions may occur during this process (note press and release callbacks).

async update()

Update the timer object and call any relevant callbacks if a new beat step or the end of the gate of a step is reached. The actual functionality of this method will depend on the child class that utilizes the pico_synth_sandbox.timer.Timer parent class.

class pico_synth_sandbox.sequencer.Sequencer(length=16, tracks=1, bpm=120)

Bases: Timer

Sequence notes using the pico_synth_sandbox.timer.Timer class to create a multi-track sixteenth note sequencer. By default, the Sequencer is set up for a single 4/4 measure of 16 notes with one track. Each note of each track can be assigned any note value and velocity. The length and number of tracks can be reassigned during runtime.

Parameters:

• length (int) – The number of sixteenth note steps of each track. The minimum value allowed is 1.

• tracks (int) – The number of tracks to create and sequence. The minimum value allowed is 1.

• bpm (int) – The beats per minute of timer.

STEP_DOTTED_QUARTER = 1.5

Dotted quarter note beat division

STEP_EIGHTH = 2.0

Eighth note beat division

STEP_HALF = 0.5

Half note beat division

STEP_QUARTER = 1.0

Quarter note beat division

STEP_SIXTEENTH = 4.0

Sixteenth note beat division

STEP_THIRTYSECOND = 8.0

Thirtysecond note beat division

STEP_TRIPLET = 3.0

Triplet note beat division

STEP_WHOLE = 0.25

Whole note beat division

disable()

Disable the timer object and immediately release any pressed notes.

enable()

Enable the timer object to start timing beat steps and triggering note press and release callbacks. The first step will immediately trigger.

get_bpm()

Get the beats per minute.

Returns:

Beats per minute

Return type:

int

get_gate()

Get the note gate within a step of a beat. This value is a ratio from 0.0 to 1.0.

Returns:

gate

Return type:

float

get_length()

Get the number of sixteenth notes for each track.

Returns:

track length

Return type:

int

get_note(position, track=0)

Get the note data for a specified track and step position. If a note isn’t defined at specific index, a value of None will be returned.

Parameters:

• position (int) – Index of the step (0-based). Will be limited to the track length.

• track (int) – Index of the track (0-based). Will be limited to the track count.

Returns:

note data (notenum, velocity)

Return type:

tuple

get_position()

Get the current position of the sequencer within the track length (0-based).

Returns:

sequencer position

Return type:

int

get_steps()

Get the number of steps per beat (or the beat division).

Returns:

Steps per beat

Return type:

float

get_track(track=0)

Get list of note data for a specified track index (0-based). If the track isn’t available, a value of None will be returned.

Returns:

track data list of note tuples as (notenum, velocity)

Return type:

list

get_tracks()

Get the number tracks being sequenced.

Returns:

track count

Return type:

int

has_note(position, track=0)

Check whether or note a specific step within a track has been set with note data.

Parameters:

• position (int) – Index of the step (0-based). Will be limited to the track length.

• track (int) – Index of the track (0-based). Will be limited to the track count.

Returns:

if the track step has a note

Return type:

bool

is_enabled()

Whether or not the timer object is enabled (running).

Returns:

enabled state

Return type:

bool

remove_note(position, track=0)

Remove the note data as a specific step within a track.

Parameters:

• position (int) – Index of the step (0-based). Will be limited to the track length.

• track (int) – Index of the track (0-based). Will be limited to the track count.

set_bpm(value)

Set the beats per minute.

Parameters:

value (int) – The desired beats per minute.

set_enabled(value: bool)

Directly set whether or not the timer object is enabled (running).

Parameters:

value (bool) – The state of the timer.

set_gate(value)

Set the note gate within a step of a beat.

Parameters:

value (float) – The duration of each pressed note per step to play before releasing. This value is a ratio from 0.0 to 1.0.

set_length(value)

Set the number of sixteenth notes for each track. If the length is shortened, all of the step data beyond the new length will be deleted, and if the sequencer is also currently running, it should loop back around automatically to the start of the track data.

Parameters:

value (int) – The number of sixteenth note steps of each track. The minimum value allowed is 1.

set_note(position, notenum, velocity=1.0, track=0)

Set the note value and velocity of a track at a specific step index.

Parameters:

• position (int) – Index of the step (0-based). Will be limited to the track length.

• notenum (int) – Value of the note.

• velocity (float) – Velocity of the note (0.0-1.0).

• track (int) – Index of the track (0-based). Will be limited to the track count.

set_press(callback)

Set the callback method you would like to be called when a timed step note is pressed.

Parameters:

callback (function) – The callback method. Must have 2 parameters for note value and velocity (0.0-1.0). Ie: def press(notenum, velocity):.

set_release(callback)

Set the callback method you would like to be called when a timed step note is released.

Parameters:

callback (function) – The callback method. Must have 1 parameter for note value. Velocity is always assumed to be 0.0. Ie: def release(notenum):.

set_step(callback)

Set the callback method you would like to be called when a step is triggered. This callback will fire whether or not the step has pressed any notes. However, any pressed notes will occur before this callback is called.

Parameters:

callback (function) – The callback method without any parameters. Ie: def step():.

set_steps(value)

Set number of steps per beat (or the beat division). The pre-defined pico_synth_sandbox.Timer.STEP_… constants can be used here.

Parameters:

value (float) – The number of steps to divide a single beat. The minimum value allowed is 0.25, or a whole note.

set_tracks(value)

Set the number of note tracks to sequence. If the number of tracks is shortened, the tracks at an index greater to or equal than the number will be deleted. If a larger number of tracks is provided, the newly created tracks will be empty.

Parameters:

value (int) – The number of tracks to sequence. The minimum value allowed is 1.

toggle()

Toggle between the enabled and disabled timer states. Any relevant actions may occur during this process (note press and release callbacks).

async update()

Update the timer object and call any relevant callbacks if a new beat step or the end of the gate of a step is reached. The actual functionality of this method will depend on the child class that utilizes the pico_synth_sandbox.timer.Timer parent class.

class pico_synth_sandbox.audio.Audio(output, voice_count=1, channel_count=2, sample_rate=None, buffer_size=None)

Bases: object

This class helps manage audio output and mixing.

Parameters:

• output (class:audioio.AudioOut) – An audioio.AudioOut object

• voice_count (int) – The number of voices to create for the audio mixer

play(source, index=0)

Play an audio source through a selected mixer voice.

Parameters:

• source (class:circuitpython_typing.AudioSample) – The audio source you would like to play

• index (int) – The voice you would like to play the audio source from.

set_level(value, index=-1)

Set the level of output of all or a single mixer voice.

Parameters:

• value (float) – The level of the voice from 0.0 to 1.0

• index (int) – If you are changing the level of a specific mixer voice, provide the index of that voice. If you’d like to change the level of all available voices, leave this parameter unset or provide an integer less than 0.

class pico_synth_sandbox.audio.I2SAudio(board, voice_count=1)

Bases: Audio

This class helps manage audio output and mixing using an audioio.AudioOut object of type audiobusio.I2SOut.

Parameters:

count (int) – The number of voices to create for the audio mixer

play(source, index=0)

Play an audio source through a selected mixer voice.

Parameters:

• source (class:circuitpython_typing.AudioSample) – The audio source you would like to play

• index (int) – The voice you would like to play the audio source from.

set_level(value, index=-1)

Set the level of output of all or a single mixer voice.

Parameters:

• value (float) – The level of the voice from 0.0 to 1.0

• index (int) – If you are changing the level of a specific mixer voice, provide the index of that voice. If you’d like to change the level of all available voices, leave this parameter unset or provide an integer less than 0.

class pico_synth_sandbox.audio.PWMAudio(board, voice_count=1)

Bases: Audio

This class helps manage audio output and mixing using an audioio.AudioOut object of type audiopwmio.PWMAudioOut.

Parameters:

count (int) – The number of voices to create for the audio mixer

play(source, index=0)

Play an audio source through a selected mixer voice.

Parameters:

• source (class:circuitpython_typing.AudioSample) – The audio source you would like to play

• index (int) – The voice you would like to play the audio source from.

set_level(value, index=-1)

Set the level of output of all or a single mixer voice.

Parameters:

• value (float) – The level of the voice from 0.0 to 1.0

• index (int) – If you are changing the level of a specific mixer voice, provide the index of that voice. If you’d like to change the level of all available voices, leave this parameter unset or provide an integer less than 0.

pico_synth_sandbox.audio.get_audio_driver(board, voice_count=1)

Automatically generate the proper audioio.AudioOut object based on the device’s settings.toml configuration.

Parameters:

count (int) – The number of voices to create for the audio mixer, defaults to 1

pico_synth_sandbox.waveform.get_amplitude()

Retrieve the maximum level peak-to-peak (+/-) of waveform sample values as defined by WAVE_AMPLITUDE in the settings.toml file.

Returns:

waveform amplitude level

Return type:

int

pico_synth_sandbox.waveform.get_noise()

Generate a white (random) noise

Returns:

waveform

Return type:

numpy array

pico_synth_sandbox.waveform.get_offset_sine()

Generate a sine waveform offset by a quarter period (PI/2).

Returns:

waveform

Return type:

numpy array

pico_synth_sandbox.waveform.get_offset_sine_noise()

Generate a sine waveform offset by a quarter period (PI/2) with white noise added. Useful for percussion synthesis.

Returns:

waveform

Return type:

numpy array

pico_synth_sandbox.waveform.get_samples()

Retrieve the number of samples in a waveform as defined by WAVE_SAMPLES in the settings.toml file.

Returns:

waveform buffer size

Return type:

int

pico_synth_sandbox.waveform.get_saw()

Generate a decrementing sawtooth

Returns:

waveform

Return type:

numpy array

pico_synth_sandbox.waveform.get_sine()

Generate a sine

Returns:

waveform

Return type:

numpy array

pico_synth_sandbox.waveform.get_sine_noise()

Generate a sine waveform with white noise added. Useful for percussion synthesis.

Returns:

waveform

Return type:

numpy array

pico_synth_sandbox.waveform.get_square()

Generate a square

Returns:

waveform

Return type:

numpy array

pico_synth_sandbox.waveform.get_triangle()

Generate a triangle

Returns:

waveform

Return type:

numpy array

class pico_synth_sandbox.midi.Midi(board)

Bases: Task

Send and receive both hardware UART and USB MIDI messages using adafruit_midi.MIDI. UART can be enabled with the MIDI_UART variable and USB can be enabled with the MIDI_USB variable in settings.toml. The midi channel is limited to a single value for both input and output and is determined by the MIDI_CHANNEL variable in settings.toml with a range of 0-15. However, the channel can be changed once a pico_synth_sandbox.midi.Midi object is created by calling the set_channel function. By default, the onboard led will be used to indicate incoming midi messages. At the moment, this feature cannot be disabled.

send_control_change(control, value, channel=None)

Send an adafruit_midi.control_change.ControlChange message through the enabled midi outputs.

Parameters:

• control (int) – The number of the midi control to send.

• value (float) – The value to set of the desired control from 0.0 through 1.0.

• channel (int) – The midi channel to transmit the message on.

send_message(msg)

Send an adafruit_midi.midi_message.MIDIMessage message through the enabled midi outputs.

Parameters:

msg (adafruit_midi.midi_message.MIDIMessage) – The message you would like to trasmit

send_note_off(notenum, channel=None)

Send an adafruit_midi.note_off.NoteOff message through the enabled midi outputs.

Parameters:

• notenum (int) – The value of the midi note to send.

• channel (int) – The midi channel to transmit the message on.

send_note_on(notenum, velocity=1.0, channel=None)

Send an adafruit_midi.note_on.NoteOn message through the enabled midi outputs.

Parameters:

• notenum (int) – The value of the midi note to send.

• velocity (float) – The velocity of the note from 0.0 through 1.0.

• channel (int) – The midi channel to transmit the message on.

send_program_change(patch, channel=None)

Send an adafruit_midi.program_change.ProgramChange message through the enabled midi outputs.

Parameters:

• patch (int) – The program/patch you would like to change to from 0 through 127.

• channel (int) – The midi channel to transmit the message on.

set_channel(value)

Set the midi channel for messages to be received and sent from.

Parameters:

value (int) – The desired channel from 0 to 16. 0 will accept all midi messages.

set_control_change(callback)

Set the callback method you would like to be called when a adafruit_midi.control_change.ControlChange message is received.

Parameters:

callback (function) – The callback method. Must have 2 parameters for control number and control value (0.0-1.0). Ie: def control_change(control, value):.

set_note_off(callback)

Set the callback method you would like to be called when a adafruit_midi.note_off.NoteOff message is received.

Parameters:

callback (function) – The callback method. Must have 1 parameter for the note value. Ie: def note_off(notenum):.

set_note_on(callback)

Set the callback method you would like to be called when a adafruit_midi.note_on.NoteOn message is received.

Parameters:

callback (function) – The callback method. Must have 2 parameters for note value and velocity (0.0-1.0). Ie: def note_on(notenum, velocity):.

set_pitch_bend(callback)

Set the callback method you would like to be called when a adafruit_midi.pitch_bend.PitchBend message is received.

Parameters:

callback (function) – The callback method. Must have 1 parameter for the pitch bend value (-1.0-1.0). Ie: def pitch_bend(value):.

set_program_change(callback)

Set the callback method you would like to be called when a adafruit_midi.program_change.ProgramChange message is received.

Parameters:

callback (function) – The callback method. Must have 1 parameter for the patch number requested. Ie: def program_change(patch):.

set_thru(value)

Set whether you would like to forward incoming midi messages through the enabled outputs automatically.

Parameters:

value (bool) – Whether or not you would like to enable midi thru.

async update()

Process any incoming midi messages from the enabled midi devices. Will trigger any pre-defined callbacks if the appropriate messages are received.