Audio Module

The AudioModule class implements playback and recording functions and supports resampling.

It is used to play audio files and streams, record audio from the microphone, and convert between different sample rates.

Support the following products:

UiFlow2 Example

Play WAV file

Open the cores3_play_wav_example.m5f2 project in UiFlow2.

66.wav

This example reads an audio file from the file system and plays it.

UiFlow2 Code Block:

Example output:

None

Playback Controls

Open the cores3_playback_controls_example.m5f2 project in UiFlow2.

66.wav

This example demonstrates how to control playback using the AudioModule class.

Play the audio for 1 second, pause for 1 second, and then resume playing.

UiFlow2 Code Block:

Example output:

None

Record Audio

Open the cores3_record_audio_example.m5f2 project in UiFlow2.

This example records audio from the microphone and saves it to a PCM buffer, then plays it out through the speaker.

UiFlow2 Code Block:

Example output:

None

MicroPython Example

Play WAV file

This example reads an audio file from the file system and plays it.

MicroPython Code Block:

# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
#
# SPDX-License-Identifier: MIT

import os, sys, io
import M5
from M5 import *
from module import AudioModule
import time


audio_0 = None


def setup():
    global audio_0

    M5.begin()
    Widgets.fillScreen(0x222222)

    audio_0 = AudioModule(
        0,
        16000,
        i2s_sck=7,
        i2s_ws=6,
        i2s_di=14,
        i2s_do=13,
        i2s_mclk=0,
        work_mode=AudioModule.MODE_HEADPHONE,
        offset=False,
        mux=AudioModule.MUX_NATIONAL,
    )
    audio_0.play_wav_file("/flash/res/audio/66.wav")
    time.sleep(1)
    audio_0.pause()
    time.sleep(1)
    audio_0.resume()


def loop():
    global audio_0
    M5.update()


if __name__ == "__main__":
    try:
        setup()
        while True:
            loop()
    except (Exception, KeyboardInterrupt) as e:
        try:
            audio_0.deinit()
            from utility import print_error_msg

            print_error_msg(e)
        except ImportError:
            print("please update to latest firmware")

Example output:

None

Playback Controls

This example demonstrates how to control playback using the AudioModule class.

Play the audio for 1 second, pause for 1 second, and then resume playing.

MicroPython Code Block:

# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
#
# SPDX-License-Identifier: MIT

import os, sys, io
import M5
from M5 import *
from module import AudioModule
import time


audio_0 = None


def setup():
    global audio_0

    M5.begin()
    Widgets.fillScreen(0x222222)

    audio_0 = AudioModule(
        0,
        16000,
        i2s_sck=7,
        i2s_ws=6,
        i2s_di=14,
        i2s_do=13,
        i2s_mclk=0,
        work_mode=AudioModule.MODE_HEADPHONE,
        offset=False,
        mux=AudioModule.MUX_NATIONAL,
    )
    audio_0.play_wav_file("/flash/res/audio/66.wav")
    time.sleep(1)
    audio_0.pause()
    time.sleep(1)
    audio_0.resume()


def loop():
    global audio_0
    M5.update()


if __name__ == "__main__":
    try:
        setup()
        while True:
            loop()
    except (Exception, KeyboardInterrupt) as e:
        try:
            audio_0.deinit()
            from utility import print_error_msg

            print_error_msg(e)
        except ImportError:
            print("please update to latest firmware")

Example output:

None

Record Audio

This example records audio from the microphone and saves it to a PCM buffer, then plays it out through the speaker.

MicroPython Code Block:

# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
#
# SPDX-License-Identifier: MIT

import os, sys, io
import M5
from M5 import *
from module import AudioModule


audio_0 = None


def setup():
    global audio_0

    M5.begin()
    Widgets.fillScreen(0x222222)

    audio_0 = AudioModule(
        0,
        16000,
        i2s_sck=7,
        i2s_ws=6,
        i2s_di=14,
        i2s_do=13,
        i2s_mclk=0,
        work_mode=AudioModule.MODE_HEADPHONE,
        offset=False,
        mux=AudioModule.MUX_NATIONAL,
    )
    audio_0.record(rate=16000, bits=16, channel=AudioModule.STEREO, duration=3000)
    audio_0.play_raw(
        audio_0.pcm_buffer, rate=16000, bits=16, channel=AudioModule.STEREO, duration=-1
    )


def loop():
    global audio_0
    M5.update()


if __name__ == "__main__":
    try:
        setup()
        while True:
            loop()
    except (Exception, KeyboardInterrupt) as e:
        try:
            audio_0.deinit()
            from utility import print_error_msg

            print_error_msg(e)
        except ImportError:
            print("please update to latest firmware")

Example output:

None

API

Class AudioModule

class module.audio.AudioModule(i2s_port, sample_rate=16000, i2s_sck=19, i2s_ws=27, i2s_di=34, i2s_do=2, i2s_mclk=0, work_mode=1, offset=1, mux=0)

Bases: object

Initialize the audio module.

Parameters:

i2s_port – I2S port number.
sample_rate – Sample rate (default is 16000).
i2s_sck – I2S clock pin.
i2s_ws – I2S word select pin.
i2s_di – I2S data input pin.
i2s_do – I2S data output pin.
i2s_mclk – I2S master clock pin.
work_mode – Work mode (0: headphone, 1: line in).
offset – Generally speaking, when using line in, offset is False; if the input is connected to an ADC microphone, offset is True. (Only valid in line in mode).
mux – Select the TRRS plug to be used. (default is MUX_NATIONAL).

UiFlow2 Code Block:

MicroPython Code Block:

from module import AudioModule

audio_0 = AudioModule(0, 16000, i2s_sck=7, i2s_ws=6, i2s_di=14, i2s_do=13, i2s_mclk=0, work_mode=AudioModule.MODE_HEADPHONE, offset=False, mux=AudioModule.MUX_NATIONAL)

MUX_NATIONAL = 0: National Standard audio mode (OMTP)

MUX_AMERICAN = 1: American Standard audio mode (CTIA)

MODE_LINE = 0: Line in mode

MODE_HEADPHONE = 1: Headphone mode

MONO = 1: Mono

STEREO = 2: Stereo

play_wav_file(file)

Play a WAV file.

Parameters:: file (str) – The path of the WAV file to play.
Returns:: None
Return type:: None

UiFlow2 Code Block:

MicroPython Code Block:

audio_0.play_wav_file("/flash/res/audio/test.wav")

tone(freq, duration)

Play simple tone sound.

Parameters:

freq (int) – Frequency of the tone in Hz.
duration (int) – Duration of the tone in milliseconds.

Returns:

None

Return type:

None

UiFlow2 Code Block:

MicroPython Code Block:

audio_0.tone(2000, 50)

play_wav(buf, duration=-1)

Play a WAV buffer.

Parameters:

buf (bytes) – The WAV buffer to play.
duration (int) – Duration of the WAV buffer in milliseconds. when duration is -1, it will play until stopped. (default is -1).

Returns:

None

Return type:

None

UiFlow2 Code Block:

MicroPython Code Block:

audio_0.play_wav(wav_buffer, duration=1000)

play_raw(buf, rate=16000, bits=16, channel=2, duration=-1)

Play a pcm buffer.

Parameters:

buf (bytes) – The PCM buffer to play.
rate (int) – Sample rate (default is 16000).
bits (int) – Bit depth (default is 16).
channel (int) – Number of channels (default is 2).
duration (int) – Duration of the PCM buffer in milliseconds. when duration is -1, it will play until stopped. (default is -1).

Returns:

None

Return type:

None

UiFlow2 Code Block:

MicroPython Code Block:

audio_0.play_raw(pcm_buffer, rate=16000, bits=16, channel=2, duration=1000)

pause()

Pause the playback.

UiFlow2 Code Block:

MicroPython Code Block:

audio.tone(2000, 100)
time.sleep(0.05)
audio_0.pause()
time.sleep(0.05)
audio_0.resume()

Return type:: None

resume()

Resume the playback.

UiFlow2 Code Block:

MicroPython Code Block:

audio.tone(2000, 100)
time.sleep(0.05)
audio_0.pause()
time.sleep(0.05)
audio_0.resume()

stop()

Stop the playback.

UiFlow2 Code Block:

MicroPython Code Block:

audio.tone(2000, 100)
time.sleep(0.05)
audio_0.stop()

get_volume()

Get the speaker volume level.

Returns:: The volume level (0-100).
Return type:: int

UiFlow2 Code Block:

MicroPython Code Block:

audio_0.get_volume()

set_volume(volume)

Set the speaker volume level.

Parameters:: volume (int) – The volume level (0-100).

UiFlow2 Code Block:

MicroPython Code Block:

audio_0.set_volume(50)

record_wav_file(path, rate=16000, bits=16, channel=2, duration=3000)

Record audio to a WAV file.

Parameters:

path (str) – The path to save the WAV file.
rate (int) – Sample rate (default is 16000).
bits (int) – Bit depth (default is 16).
channel (int) – Number of channels (default is 2).
duration (int) – Duration of the recording in milliseconds (default is 3000).

UiFlow2 Code Block:

MicroPython Code Block:

audio_0.record_wav_file("/flash/res/audio/test.wav", rate=16000, bits=16, channel=2, duration=3000)

record(rate=16000, bits=16, channel=2, duration=3000)

Record audio to a PCM buffer.

Parameters:

rate (int) – Sample rate (default is 16000).
bits (int) – Bit depth (default is 16).
channel (int) – Number of channels (default is 2).
duration (int) – Duration of the recording in milliseconds (default is 3000).

UiFlow2 Code Block:

MicroPython Code Block:

audio_0.record(rate=16000, bits=16, channel=2, duration=3000)

property pcm_buffer: bytes

Get the PCM buffer.

Returns:: The PCM buffer.

UiFlow2 Code Block:

MicroPython Code Block:

audio_0.pcm_buffer

set_color(num, color)

Set the RGB LED color.

Parameters:

num (int) – The LED number (0-2).
color (int) – The color value (0xRRGGBB).

UiFlow2 Code Block:

MicroPython Code Block:

audio_0.set_color(0, 0xFF0000)

fill_color(color)

Fill all RGB LEDs with the same color.

Parameters:: color (int) – The color value (0xRRGGBB).

UiFlow2 Code Block:

MicroPython Code Block:

audio_0.fill_color(0xFF0000)

set_brightness(br)

Set the RGB LED brightness.

Parameters:: br (int) – The brightness level (0-100).

UiFlow2 Code Block:

MicroPython Code Block:

audio_0.set_brightness(50)