audioio – Support for audio output — Adafruit CircuitPython 1 documentation (original) (raw)

Adafruit CircuitPython

The audioio module contains classes to provide access to audio IO.

All classes change hardware state and should be deinitialized when they are no longer needed if the program continues after use. To do so, either call deinit() or use a context manager. SeeLifetime and ContextManagers for more info.

For more information on working with this module, refer to theCircuitPython Essentials Learn Guide.

Since CircuitPython 5, RawSample and WaveFile are moved to audiocore, and Mixer is moved to audiomixer.

Available on these boards

class audioio.AudioOut(left_channel: microcontroller.Pin, *, right_channel: microcontroller.Pin | None = None, quiescent_value: int = 32768)

Output an analog audio signal

Create a AudioOut object associated with the given pin(s). This allows you to play audio signals out on the given pin(s).

Parameters:

Note

On ESP32 and ESP32-S2, the DAC channels are usually designated as DAC_1 (right stereo channel) and DAC_2 (left stereo channel). These pins are sometimes labelled as A0 and A1, but they may be assigned in either order. Check your board’s pinout to verify which pin is which channel.

Simple 8ksps 440 Hz sin wave:

import audiocore import audioio import board import array import time import math

Generate one period of sine wav.

length = 8000 // 440 sine_wave = array.array("H", [0] * length) for i in range(length): sine_wave[i] = int(math.sin(math.pi * 2 * i / length) * (2 ** 15) + 2 ** 15)

dac = audioio.AudioOut(board.SPEAKER) sine_wave = audiocore.RawSample(sine_wave, sample_rate=8000) dac.play(sine_wave, loop=True) time.sleep(1) dac.stop()

Playing a wave file from flash:

import board import audioio import digitalio

Required for CircuitPlayground Express

speaker_enable = digitalio.DigitalInOut(board.SPEAKER_ENABLE) speaker_enable.switch_to_output(value=True)

data = open("cplay-5.1-16bit-16khz.wav", "rb") wav = audiocore.WaveFile(data) a = audioio.AudioOut(board.A0)

print("playing") a.play(wav) while a.playing: pass print("stopped")

deinit() → None

Deinitialises the AudioOut and releases any hardware resources for reuse.

__enter__() → AudioOut

No-op used by Context Managers.

__exit__() → None

Automatically deinitializes the hardware when exiting a context. SeeLifetime and ContextManagers for more info.

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

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

Sample must be an audiocore.WaveFile, audiocore.RawSample, audiomixer.Mixer or audiomp3.MP3Decoder.

The sample itself should consist of 16 bit samples. Microcontrollers with a lower output resolution will use the highest order bits to output. For example, the SAMD21 has a 10 bit DAC that ignores the lowest 6 bits when playing 16 bit samples.

stop() → None

Stops playback and resets to the start of the sample.

playing_: bool_

True when an audio sample is being output even if paused. (read-only)

pause() → None

Stops playback temporarily while remembering the position. Use resume to resume playback.

resume() → None

Resumes sample playback after pause().

paused_: bool_

True when playback is paused. (read-only)