usb_audio – Stream audio to a host computer via USB
This makes your CircuitPython device identify to the host computer as a USB Audio Class (UAC2) microphone: the board is the audio source and streams samples to the host over a USB isochronous IN endpoint.
This mode requires 1 IN endpoint and 2 interfaces. Generally, microcontrollers
have a limit on the number of endpoints. If you exceed the number of endpoints,
CircuitPython will automatically enter Safe Mode. Even in this case, you may be
able to enable USB audio by also disabling other USB functions, such as
usb_hid or usb_midi.
To enable this mode, you must configure the audio format in boot.py and then
use the usb_microphone singleton instance in code.py.
# boot.py
import usb_audio
usb_audio.enable(sample_rate=16000, channel_count=1, bits_per_sample=16)
# code.py
import time
import usb_audio
import synthio
# usb_audio.usb_microphone is a singleton instance (created by enable() above),
# not a class you construct. It is a consumer of an audio sample, just like
# audioio.AudioOut: the samples it pulls are streamed to the host PC instead
# of to a pin.
mic = usb_audio.usb_microphone
synth = synthio.Synthesizer(sample_rate=16000, channel_count=1)
mic.play(synth, loop=True)
c_major_scale = [60, 62, 64, 65, 67, 69, 71, 72]
try:
while True:
for note in c_major_scale:
synth.press(note)
time.sleep(0.1)
synth.release(note)
time.sleep(0.05)
except KeyboardInterrupt:
pass
mic.stop()
The sample_rate and channel_count of the sample played must match the
values passed to enable, and the sample must be 16-bit signed; otherwise
play raises a ValueError.
This interface is experimental and may change without notice even in stable versions of CircuitPython.
Available on these boards
- usb_audio.usb_microphone: USBMicrophone | None
The shared
USBMicrophonesingleton instance, orNoneuntilusb_audio.enable()has configured an input (microphone) stream inboot.py.USBMicrophoneis exposed only as a type; you do not construct it.
- usb_audio.usb_speaker: USBSpeaker | None
The shared
USBSpeakersingleton instance, orNoneuntilusb_audio.enable()has configured an output (speaker) stream inboot.py.USBSpeakeris exposed only as a type; you do not construct it.
- usb_audio.enable(sample_rate: int = 16000, channel_count: int = 1, bits_per_sample: int = 16, microphone: bool = True, speaker: bool = False) None
Enable the USB audio interface with the given PCM format.
This function may only be used from
boot.py.- Parameters:
sample_rate (int) – Samples per second of the streamed audio.
channel_count (int) – Number of channels. Only mono (1) is supported initially.
bits_per_sample (int) – Bits per signed PCM sample. Only 16 is supported initially.
microphone (bool) – Present a microphone (audio flows board -> host). Enabled by default.
speaker (bool) – Present a speaker (audio flows host -> board).
Enabling both
microphoneandspeakerpresents a combined headset. At least one of the two must be enabled.
- class usb_audio.USBMicrophone
Streams an audio sample to the host computer as a USB Audio Class microphone.
A
USBMicrophoneis a consumer of an audio sample, exactly likeaudioio.AudioOut,audiobusio.I2SOutandaudiopwmio.PWMAudioOut. The samples it pulls are streamed to the host PC over USB rather than to a pin, so the board appears as a microphone.You cannot create an instance of
usb_audio.USBMicrophone.There is a single shared instance, available as
usb_audio.usb_microphoneonceusb_audio.enable()has configured an input (microphone) stream inboot.py. Until thenusb_audio.usb_microphoneisNone.- __enter__() USBMicrophone
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
Streams the sample to the host once when loop=False and continuously when loop=True. Does not block. Use
playingto block.Sample must be an
audiocore.WaveFile,audiocore.RawSample,audiomixer.Mixer,audiomp3.MP3Decoderorsynthio.Synthesizer.
- class usb_audio.USBSpeaker
Plays audio streamed from the host computer as a USB Audio Class speaker.
A
USBSpeakeris a source of audio samples, exactly likeaudiocore.RawSampleoraudiocore.WaveFile. The host PC streams audio to the board over USB, and theUSBSpeakerhands that audio to a consumer such asaudiobusio.I2SOut,audiopwmio.PWMAudioOutoraudioio.AudioOut(optionally through the effect modules), so the board appears as a speaker.You cannot create an instance of
usb_audio.USBSpeaker.There is a single shared instance, available as
usb_audio.usb_speakeronceusb_audio.enable()has configured an output (speaker) stream inboot.py. Until thenusb_audio.usb_speakerisNone.# boot.py import usb_audio usb_audio.enable(sample_rate=16000, channel_count=1, bits_per_sample=16, microphone=False, speaker=True)
# code.py import board import usb_audio import audiobusio spk = usb_audio.usb_speaker out = audiobusio.I2SOut(board.I2S_BIT_CLOCK, board.I2S_WORD_SELECT, board.I2S_DATA) out.play(spk, loop=True) while True: pass
- read(destination: circuitpython_typing.WriteableBuffer, destination_length: int) int
Copies up to
destination_lengthof the most recent samples streamed from the host intodestination, for analysis such as an audio-reactive effect or VU meter. This does not block: it returns whatever the host has delivered so far, which may be fewer thandestination_lengthsamples (or zero when the host is not streaming).destinationmust be anarray.arrayof 16-bit signed samples (typecode"h"), matching the negotiated speaker format.Reading consumes the samples, so a
USBSpeakerbeing read this way should not also be passed to an output backend’splay()at the same time.- Returns:
The number of samples copied into
destination.
- __enter__() USBSpeaker
No-op used by Context Managers.
- __exit__() None
Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.