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
- 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
audiofiltersandaudiodelaysdo, 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
capacityseconds of it in a buffer, whichreadintocopies out of without waiting, and measures itspeakandrmslevels. 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
playa sample with the tap before anything plays the tap.The tap only sees audio that is played through it: something, such as an
audiomixer.Mixervoice 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 alevelof 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
overflowturns 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 measurespeakandrms.
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_descriptorslibrary finds the microphone and its format, andusb.corestarts its stream; seeusb_host_audio.USBIn. DVI audio plays at 32, 44.1 or 48 kHz, so anaudiospeed.Resamplerconverts 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)
- __exit__() None
Automatically deinitializes when exiting a context. See Lifetime and ContextManagers for more info.
- overflow: bool
True if audio was dropped since the last time this was checked, because
readintodid not keep up. Reading this clears it. (read-only)
- readinto(buffer: circuitpython_typing.WriteableBuffer) int
Copies the oldest audio waiting into
bufferand 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
bufferis usually anarray.arrayof typecode'h'for 16 bit signed samples. Abytearrayworks 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 amemoryviewof it.
- clear() None
Discards the audio waiting, so that
readintoreturns only audio that passes through after this. Use it to skip ahead to the live audio, for example after anoverflow.
- 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
playingto 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: