audiotap – Look at audio as it plays

The audiotap module contains Tap, which goes into an audio chain like the effects in audiofilters and audiodelays. Audio passes through it unchanged, and the program can read a copy of it and its levels, for meters, waveforms, spectrum analysis or recording, while it plays.

Available on these boards
  • 0xCB Gemini
  • 0xCB Helios
  • 42. Keebs Frood
  • 8086 RP2040 Interfacer
  • 8086 USB Interposer
  • Adafruit Feather RP2040
  • Adafruit Feather RP2040 Adalogger
  • Adafruit Feather RP2040 CAN
  • Adafruit Feather RP2040 DVI
  • Adafruit Feather RP2040 Prop-Maker
  • Adafruit Feather RP2040 RFM
  • Adafruit Feather RP2040 Scorpio
  • Adafruit Feather RP2040 ThinkInk
  • Adafruit Feather RP2040 USB Host
  • Adafruit Feather RP2350
  • Adafruit Feather RP2350 Adalogger
  • Adafruit Floppsy RP2040
  • Adafruit Fruit Jam
  • Adafruit ItsyBitsy RP2040
  • Adafruit KB2040
  • Adafruit Macropad RP2040
  • Adafruit Metro ESP32-P4
  • Adafruit Metro RP2040
  • Adafruit Metro RP2350
  • Adafruit QT Py RP2040
  • Adafruit QT2040 Trinkey
  • Adafruit Tinychad RP2350
  • Archi RP2040
  • Arduino Nano RP2040 Connect
  • BBQ20KBD
  • BLOK
  • Bradán Lane STUDIO Explorer Badge
  • COSMO-Pico
  • Challenger NB RP2040 WiFi
  • Challenger RP2040 LTE
  • Challenger RP2040 LoRa
  • Challenger RP2040 NFC
  • Challenger RP2040 SD/RTC
  • Challenger RP2040 SubGHz
  • Challenger RP2040 WiFi
  • Challenger RP2040 WiFi/BLE
  • Challenger+ RP2350 BConnect
  • Challenger+ RP2350 WiFi6/BLE5
  • Cytron EDU PICO 2
  • Cytron EDU PICO W
  • Cytron IRIV IO Controller
  • Cytron MOTION 2350 Pro
  • Cytron Maker Nano RP2040
  • Cytron Maker Pi RP2040
  • Cytron Maker Sumo RP2350
  • Cytron Maker Uno RP2040
  • Datanoise PicoADK
  • Datanoise PicoADK V2
  • E-Fidget
  • ELECFREAKS PICO:ED
  • Electrolama minik
  • EncoderPad RP2040
  • Fig Pi
  • HEIA-FR Picomo V2
  • HEIA-FR Picomo V3
  • HXR.DK SAO Digital Multimeter
  • Hack Club Sprig
  • IDE-TUDelft RealPicoExpander
  • LILYGO T-DISPLAY
  • Maple Computing Elite-Pi
  • Melopero Shake RP2040
  • MoonYard Equinox
  • Music Thing Modular Workshop Computer
  • Noise Nugget 2040
  • Oak Dev Tech BREAD2040
  • Oak Dev Tech Cast-Away RP2040
  • Oak Dev Tech RPGA Feather
  • Orpheus Pico
  • PCBCupid Glyph Mini 2040
  • PROVES Kit v4
  • Pimoroni Badger 2040
  • Pimoroni Badger 2040 W
  • Pimoroni Badger 2350
  • Pimoroni Explorer
  • Pimoroni Inky Frame 5.7
  • Pimoroni Inky Frame 7.3
  • Pimoroni Interstate 75
  • Pimoroni Keybow 2040
  • Pimoroni Motor 2040
  • Pimoroni PGA2040
  • Pimoroni PGA2350
  • Pimoroni Pico LiPo (16MB)
  • Pimoroni Pico LiPo (4MB)
  • Pimoroni Pico Plus 2
  • Pimoroni Pico Plus 2 W
  • Pimoroni Pico dv Base
  • Pimoroni PicoSystem
  • Pimoroni Plasma 2040
  • Pimoroni Plasma 2040W
  • Pimoroni Plasma 2350
  • Pimoroni Plasma 2350W
  • Pimoroni Servo 2040
  • Pimoroni Tiny 2040 (2MB)
  • Pimoroni Tiny 2040 (8MB)
  • Pimoroni Tiny 2350
  • Pimoroni Tiny FX
  • PyKey 18 Numpad
  • PyKey 44 Ergo
  • PyKey 60
  • PyKey 87 TKL
  • RF.Guru RP2040
  • RP2.65-F
  • RP2040 Stamp
  • RP2350 Stamp
  • RP2350 Stamp XL
  • Raspberry Breadstick
  • Raspberry Pi Pico
  • Raspberry Pi Pico 2
  • Raspberry Pi Pico 2 W
  • Raspberry Pi Pico W
  • SecuringHardware.com Xiaomao
  • Seeeduino XIAO RP2040
  • Seeeduino XIAO RP2350
  • Silicognition LLC RP2040-Shim
  • SparkFun MicroMod RP2040 Processor
  • SparkFun Pro Micro RP2040
  • SparkFun Pro Micro RP2350
  • SparkFun Thing Plus - RP2040
  • SparkFun Thing Plus RP2350
  • Teenage Engineering SP-1
  • Teenage Engineering ting fx EP-2350
  • TinyCircuits Thumby
  • TinyCircuits Thumby Color
  • VCC-GND Studio YD RP2040
  • W5100S-EVB-Pico
  • W5100S-EVB-Pico2
  • W5500-EVB-Pico
  • W5500-EVB-Pico2
  • W55RP20-EVB-Pico
  • WK-50 Trackball Keyboard
  • Waveshare RP2040-GEEK
  • Waveshare RP2040-LCD-0.96
  • Waveshare RP2040-LCD-1.28
  • Waveshare RP2040-One
  • Waveshare RP2040-PiZero
  • Waveshare RP2040-Plus (16MB)
  • Waveshare RP2040-Plus (4MB)
  • Waveshare RP2040-TOUCH-LCD-1.28
  • Waveshare RP2040-Tiny
  • Waveshare RP2040-Zero
  • Waveshare RP2350-GEEK
  • Waveshare RP2350-LCD-0.96
  • Waveshare RP2350-LCD-1.28
  • Waveshare RP2350-One
  • Waveshare RP2350-Plus
  • Waveshare RP2350-TOUCH-LCD-1.28
  • Waveshare RP2350-Tiny
  • Waveshare RP2350-Zero
  • WeAct Studio Pico
  • WeAct Studio Pico 16MB
  • WeAct Studio RP2350B Core
  • WisdPi Ardu2040M
  • WisdPi Tiny RP2040
  • nullbits Bit-C PRO
  • splitkb.com Liatris
  • takayoshiotake Octave RP2040
  • uGame22

class audiotap.Tap(capacity: float = 0.1)

Passes audio through unchanged and keeps a copy that the program can read

Create a Tap. It plays a sample like the effects in audiofilters and audiodelays do, so it can go anywhere in an audio chain. Whatever plays the tap gets the sample’s audio unchanged.

As the audio passes through, the tap keeps up to capacity seconds of it in a buffer, which readinto copies out of without waiting, and measures its peak and rms levels. The program can look at the audio this way, at the point in the chain where the tap is, while it plays.

The tap takes its sample rate, channel count, bits per sample and signedness from the first sample it plays, and allocates the buffer then. So play a sample with the tap before anything plays the tap.

The tap only sees audio that is played through it: something, such as an audiomixer.Mixer voice playing to an audio output, must play it or a chain that it is part of. To look at audio without hearing it, play it at a level of 0. When its sample is stopped or ends, the tap plays silence and keeps nothing.

When the program reads too slowly, the buffer fills up, the tap keeps the audio it has and drops the newer audio until there is room again, and overflow turns True. The audio that passes through is never affected.

Parameters:

capacity (float) – How many seconds of audio are kept for readinto. 0 keeps none, for a tap that only measures peak and rms.

Showing the level of a USB microphone while it is heard through the DVI output, and keeping the audio for a spectrum display. The adafruit_usb_host_descriptors library finds the microphone and its format, and usb.core starts its stream; see usb_host_audio.USBIn. DVI audio plays at 32, 44.1 or 48 kHz, so an audiospeed.Resampler converts other sample rates:

import array
import time

import adafruit_usb_host_descriptors
import audiomixer
import audiospeed
import audiotap
import displayio
import supervisor
import usb_host_audio
import vectorio

device = adafruit_usb_host_descriptors.find_microphone()
if device is None:
    raise RuntimeError("Plug a USB microphone or webcam into the USB host port")
formats = adafruit_usb_host_descriptors.find_microphone_formats(device)
mic_format = adafruit_usb_host_descriptors.choose_microphone_format(formats, sample_rate=48000)
sample_rate = mic_format.nearest_rate(48000)

device.set_configuration()
# SET_INTERFACE to the format's alternate setting starts the stream, then
# SET_CUR of the endpoint's sampling frequency picks the rate.
device.ctrl_transfer(0x01, 11, mic_format.alternate, mic_format.interface, None)
if mic_format.rate_control:
    device.ctrl_transfer(
        0x22, 0x01, 0x0100, mic_format.endpoint, sample_rate.to_bytes(3, "little")
    )

mic = usb_host_audio.USBIn(
    device,
    mic_format.endpoint,
    sample_rate=sample_rate,
    channel_count=mic_format.channel_count,
    bit_depth=8 * mic_format.bytes_per_sample,
    samples_signed=mic_format.samples_signed,
    max_packet_size=mic_format.max_packet_size,
)
# Keep a quarter second, more than arrives between reads of the loop below.
tap = audiotap.Tap(capacity=0.25)
mixer = audiomixer.Mixer(voice_count=1, sample_rate=48000, channel_count=mic.channel_count)
supervisor.runtime.audio.play(mixer)
mixer.voice[0].play(audiospeed.Resampler(tap.play(mic)))

# Bars for the peak (top) and RMS (bottom) levels. Showing them hides the
# console, whose scrolling stalls the microphone's stream. print() still
# goes to the serial console.
display = supervisor.runtime.display
palette = displayio.Palette(1)
palette[0] = 0x00FF00
peak_bar = vectorio.Rectangle(pixel_shader=palette, width=1, height=40, x=0, y=60)
rms_bar = vectorio.Rectangle(pixel_shader=palette, width=1, height=40, x=0, y=140)
meter = displayio.Group()
meter.append(peak_bar)
meter.append(rms_bar)
display.root_group = meter

samples = array.array("h", [0] * 1024)
while True:
    # Read the audio that is waiting. A spectrum display would use these samples.
    while tap.available >= len(samples):
        tap.readinto(samples)
    peak = tap.peak
    rms = tap.rms
    peak_bar.width = max(1, int(peak * display.width))
    rms_bar.width = max(1, int(rms * display.width))
    print(f"peak {peak:.3f} rms {rms:.3f}")
    time.sleep(0.1)
deinit() → None

Deinitialises the Tap.

__enter__() → Tap

No-op used by Context Managers.

__exit__() → None

Automatically deinitializes when exiting a context. See Lifetime and ContextManagers for more info.

playing: bool

True when the tap is playing a sample. (read-only)

available: int

The number of samples waiting to be read with readinto. (read-only)

overflow: bool

True if audio was dropped since the last time this was checked, because readinto did not keep up. Reading this clears it. (read-only)

readinto(buffer: circuitpython_typing.WriteableBuffer) → int

Copies the oldest audio waiting into buffer and returns the number of samples copied, which is 0 when none is waiting. Does not wait for audio. Copies whole frames only: a stereo frame is two samples, left then right.

The samples are copied as they are played, so buffer is usually an array.array of typecode 'h' for 16 bit signed samples. A bytearray works for any format and holds half as many 16 bit samples as its length. To read into part of a buffer, pass a slice of a memoryview of it.

clear() → None

Discards the audio waiting, so that readinto returns only audio that passes through after this. Use it to skip ahead to the live audio, for example after an overflow.

peak: float

The largest magnitude of the audio that passed through since this was last read, from 0.0 to 1.0 of full scale. Reading this starts a new measurement. 0.0 when no audio passed through. The channels of stereo audio are measured together. (read-only)

rms: float

The RMS level of the audio that passed through since this was last read, from 0.0 to 1.0 of full scale. Reading this starts a new measurement, separate from peak’s. 0.0 when no audio passed through. The channels of stereo audio are measured together. (read-only)

play(sample: circuitpython_typing.AudioSample, *, loop: bool = False) → Tap

Plays the sample once when loop=False and continuously when loop=True. Does not block. Use playing to block.

The first sample sets the tap’s format. Later samples must match it.

Returns:

The tap itself. Can be used for chaining, ie: audio.play(tap.play(sample)).

Return type:

Tap

stop() → None

Stops playback of the sample. The audio already kept can still be read.