WaveViz: Plot a synthio Wave Table or Envelope

Last updated July 03, 2024

Save

I See What You Did There
Simple Test Example Code

Getting Started

Adafruit Playground is a wonderful and safe place to share your interests with Adafruit's vibrant community of makers and doers. Have a cool project you are working on? Have a bit of code that you think others will find useful? Want to show off your electronics workbench? You have come to the right place.

The goal of Adafruit Playground is to make it as simple as possible to share your work. On the Adafruit Playground users can create Notes. A note is a single-page space where you can document your topic using Adafruit's easy-to-use editor. Notes are like Guides on the Adafruit Learning System but guides are high-fidelity content curated and maintained by Adafuit. Notes are whatever you want them to be. Have fun and be kind.

Click here to learn more about Adafruit Playground and how to get started.

Now including ADSR envelope widgets!

WaveViz is a CircuitPython class to create a positionable displayio.TileGrid graphics widget from a synthio.waveformwave table or synthio.Envelope object (or any one-dimensional list for that matter). The class also makes the underlying bitmap and palette objects available for other uses such as saving the widget to an image file.

The WaveViz class currently resides in its GitHub repository and is included in the CircuitPython Community Bundle. The update utility circup can be used to install cedargrove_waveviz.

WaveViz API

Multiple Synthetic Harmonica Waveform Images of Various Sizes Created by WaveViz

The long-term objective is to be able to save and import sounds and ADSR envelopes from a library of synthio wave table files and envelope objects. The first step in the process is to create a visualizer to help characterize the sounds graphically. We'll worry about saving and retrieving waveform and envelope objects sometime in the future (watch for a new class, WaveStore to appear soon). For now, let's work on getting images of wave tables and envelopes.

Todbot investigated and deployed wave table file retrieval in a couple of projects and covers it nicely on his hints page: https://github.com/todbot/circuitpython-synthio-tricks

The WaveStore class (in development) will create and manage a file-based collection of synthio object assets and graphic widgets. The goal is to create a managed library of synthio sounds and voices that can be included in CircuitPython code with simple import statements.

I See What You Did There

When instantiated, WaveViz is given a waveform or envelope object, the screen origin pixel coordinates (x, y), an image size (width, height) in pixels, as well as RGB 24-bit colors for the waveform, border, and background. Internally, the class creates a bitmap image where:

a waveform wave table fills the image with positive and negative sample values above and below a baseline, or
an envelope object representing the four phases of attack, decay, sustain, and release with 0.0 to 1.0 amplitude values on the y-axis and relative phase timing on the x-axis.

After the image is created, the class instance becomes a displayio.TileGrid object. The image is also available as a bitmap (WaveViz.bitmap, WaveViz.pixel_shader).

The resultant image can be plotted anywhere on the display in any aspect ratio. If nested layering is required, the background color can also be specified as transparent (back_color=None).

Simple Test Example Code

The following is a simple test that used a FeatherS2 attached to a 2.4-inch TFT FeatherWing display. The code imports WaveBuilder to construct a synthetic harmonica wave table from five oscillators.

Download File

Copy Code

# SPDX-FileCopyrightText: Copyright (c) 2024 JG for Cedar Grove Maker Studios
# SPDX-License-Identifier: MIT

import board
import displayio
import synthio
import adafruit_ili9341
from cedargrove_wavebuilder import WaveBuilder, WaveShape
from cedargrove_waveviz import WaveViz

# Define wave table parameters
WAVE_TABLE_LENGTH = 512  # The wave table length in samples
SAMPLE_MAXIMUM = 32700  # The maximum value of a sample

# Instantiate a built-in display
# display = board.DISPLAY

# Instantiate the FeatherS2 with 2.4-inch TFT FeatherWing display
displayio.release_displays()  # Release display resources
display_bus = displayio.FourWire(
    board.SPI(), command=board.D6, chip_select=board.D5, reset=None
)
display = adafruit_ili9341.ILI9341(display_bus, width=320, height=240)
display.rotation = 0

splash = displayio.Group()
display.root_group = splash

# Define the Harmonica wave shape, overtone ratio, and amplitude
tone = [
    (WaveShape.Sine, 1.00, 0.10),
    (WaveShape.Sine, 2.00, 0.48),
    (WaveShape.Sine, 3.00, 0.28),
    (WaveShape.Sine, 4.00, 0.02),
    (WaveShape.Sine, 5.00, 0.12),
]

# Create the wave table (wave.wave_table)
wave = WaveBuilder(
    oscillators=tone,
    table_length=WAVE_TABLE_LENGTH,
    sample_max=SAMPLE_MAXIMUM,
    lambda_factor=1.0,
    loop_smoothing=True,
    debug=False,
)

# Create a synthio.Envelope object
env = synthio.Envelope(
    attack_time=0.05,
    attack_level=1.0,
    decay_time=0.1,
    release_time=0.1,
    sustain_level=0.5,
)

# Display a small version on the bottom layer
splash.append(
    WaveViz(wave.wave_table, x=20, y=80, width=25, height=25, back_color=0x0000A0)
)

# Display a full-sized version on the middle layer
splash.append(
    WaveViz(wave.wave_table, x=0, y=0, width=300, height=240, back_color=None)
)

# Display the envelope object on the top layer
splash.append(
    WaveViz(
        env,
        x=150,
        y=170,
        width=80,
        height=40,
        plot_color=0xFFFFFF,
        back_color=0x800080,
    )
)

while True:
    pass

# SPDX-FileCopyrightText: Copyright (c) 2024 JG for Cedar Grove Maker Studios
# SPDX-License-Identifier: MIT

import board
import displayio
import synthio
import adafruit_ili9341
from cedargrove_wavebuilder import WaveBuilder, WaveShape
from cedargrove_waveviz import WaveViz

# Define wave table parameters
WAVE_TABLE_LENGTH = 512  # The wave table length in samples
SAMPLE_MAXIMUM = 32700  # The maximum value of a sample

# Instantiate a built-in display
# display = board.DISPLAY

# Instantiate the FeatherS2 with 2.4-inch TFT FeatherWing display
displayio.release_displays()  # Release display resources
display_bus = displayio.FourWire(
    board.SPI(), command=board.D6, chip_select=board.D5, reset=None
)
display = adafruit_ili9341.ILI9341(display_bus, width=320, height=240)
display.rotation = 0

splash = displayio.Group()
display.root_group = splash

# Define the Harmonica wave shape, overtone ratio, and amplitude
tone = [
    (WaveShape.Sine, 1.00, 0.10),
    (WaveShape.Sine, 2.00, 0.48),
    (WaveShape.Sine, 3.00, 0.28),
    (WaveShape.Sine, 4.00, 0.02),
    (WaveShape.Sine, 5.00, 0.12),
]

# Create the wave table (wave.wave_table)
wave = WaveBuilder(
    oscillators=tone,
    table_length=WAVE_TABLE_LENGTH,
    sample_max=SAMPLE_MAXIMUM,
    lambda_factor=1.0,
    loop_smoothing=True,
    debug=False,
)

# Create a synthio.Envelope object
env = synthio.Envelope(
    attack_time=0.05,
    attack_level=1.0,
    decay_time=0.1,
    release_time=0.1,
    sustain_level=0.5,
)

# Display a small version on the bottom layer
splash.append(
    WaveViz(wave.wave_table, x=20, y=80, width=25, height=25, back_color=0x0000A0)
)

# Display a full-sized version on the middle layer
splash.append(
    WaveViz(wave.wave_table, x=0, y=0, width=300, height=240, back_color=None)
)

# Display the envelope object on the top layer
splash.append(
    WaveViz(
        env,
        x=150,
        y=170,
        width=80,
        height=40,
        plot_color=0xFFFFFF,
        back_color=0x800080,
    )
)

while True:
    pass

WaveViz simpletest display showing two waveforms and one envelope widget

This page (WaveViz: Plot a synthio Wave Table or Envelope) was last updated on July 03, 2024.