`audiopwmio` – Audio output via digital PWM¶

The audiopwmio 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. See Lifetime and ContextManagers for more info.

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

Available on these boards

ARAMCON Badge 2019
ARAMCON2 Badge
Adafruit CLUE nRF52840 Express
Adafruit Circuit Playground Bluefruit
Adafruit Feather Bluefruit Sense
Adafruit Feather RP2040
Adafruit Feather STM32F405 Express
Adafruit Feather nRF52840 Express
Adafruit ItsyBitsy RP2040
Adafruit ItsyBitsy nRF52840 Express
Adafruit KB2040
Adafruit LED Glasses Driver nRF52840
Adafruit Macropad RP2040
Adafruit Metro nRF52840 Express
Adafruit QT Py RP2040
Adafruit QT2040 Trinkey
Arduino Nano 33 BLE
Arduino Nano RP2040 Connect
AtelierDuMaker nRF52840 Breakout
BLE-SS dev board Multi Sensor
BastBLE
BlueMicro833
BlueMicro840
Challenger NB RP2040 WiFi
Challenger RP2040 LTE
Challenger RP2040 WiFi
Cytron Maker Nano RP2040
Cytron Maker Pi RP2040
ELECFREAKS PICO:ED
Electronut Labs Blip
Electronut Labs Papyr
EncoderPad RP2040
HiiBot BlueFi
IkigaiSense Vita nRF52840
MDBT50Q-DB-40
MDBT50Q-RX Dongle
MEOWBIT
MakerDiary nRF52840 MDK
MakerDiary nRF52840 MDK USB Dongle
Makerdiary M60 Keyboard
Makerdiary Pitaya Go
Makerdiary nRF52840 M.2 Developer Kit
Melopero Shake RP2040
Oak Dev Tech BREAD2040
Oak Dev Tech Cast-Away RP2040
Open Hardware Summit 2020 Badge
PCA10056 nRF52840-DK
PCA10059 nRF52840 Dongle
PCA10100 nRF52833 DK
Particle Argon
Particle Boron
Particle Xenon
Pimoroni Badger 2040
Pimoroni Interstate 75
Pimoroni Keybow 2040
Pimoroni Motor 2040
Pimoroni PGA2040
Pimoroni Pico LiPo (16MB)
Pimoroni Pico LiPo (4MB)
Pimoroni PicoSystem
Pimoroni Plasma 2040
Pimoroni Servo 2040
Pimoroni Tiny 2040 (2MB)
Pimoroni Tiny 2040 (8MB)
PyKey 18 Numpad
PyKey 44 Ergo
PyKey 60
PyKey 87 TKL
PyboardV1_1
RP2.65-F
RP2040 Stamp
Raspberry Pi Pico
SSCI ISP1807 Dev Board
SSCI ISP1807 Micro Board
STM32F412G_DISCO
STM32F4_DISCO
Seeed XIAO nRF52840 Sense
Seeeduino XIAO RP2040
Simmel
SparkFun MicroMod RP2040 Processor
SparkFun MicroMod nRF52840 Processor
SparkFun Pro Micro RP2040
SparkFun Pro nRF52840 Mini
SparkFun STM32 MicroMod Processor
SparkFun Thing Plus - RP2040
SparkFun Thing Plus - STM32
Swan R5
TG-Watch
THUNDERPACK_v11
THUNDERPACK_v12
Teknikio Bluebird
TinkeringTech ScoutMakes Azul
W5100S-EVB-Pico
WarmBit BluePixel nRF52840
Waveshare RP2040-Zero
iLabs Challenger 840
micro:bit v2
nice!nano
stm32f411ce-blackpill-with-flash

class audiopwmio.PWMAudioOut(left_channel: microcontroller.Pin, *, right_channel: Optional[microcontroller.Pin] = None, quiescent_value: int = 32768)¶

Output an analog audio signal by varying the PWM duty cycle.

Create a PWMAudioOut object associated with the given pin(s). This allows you to play audio signals out on the given pin(s). In contrast to mod:audioio, the pin(s) specified are digital pins, and are driven with a device-dependent PWM signal.

Parameters

left_channel (Pin) – The pin to output the left channel to
right_channel (Pin) – The pin to output the right channel to
quiescent_value (int) – The output value when no signal is present. Samples should start and end with this value to prevent audible popping.

Simple 8ksps 440 Hz sin wave:

import audiocore
import audiopwmio
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 = audiopwmio.PWMAudioOut(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 audiocore
import audiopwmio
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 = audiopwmio.PWMAudioOut(board.SPEAKER)

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

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

paused :bool¶: True when playback is paused. (read-only)

deinit() → None¶: Deinitialises the PWMAudioOut and releases any hardware resources for reuse.

__enter__() → PWMAudioOut¶: No-op used by Context Managers.

__exit__() → None¶: Automatically deinitializes the hardware when exiting a context. See Lifetime 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.

stop() → None¶: Stops playback and resets to the start of the sample.

pause() → None¶: Stops playback temporarily while remembering the position. Use resume to resume playback.

resume() → None¶: Resumes sample playback after pause().

audiopwmio – Audio output via digital PWM¶

`audiopwmio` – Audio output via digital PWM¶