Speaker

The Speaker is used to control the built-in speaker inside the host device. Below is the detailed support for Speaker on the host:

Controller	NS4168	AW88298	Buzzer
AirQ			✔
Atom Echo	✔
Atom Lite
Atom Martrix
AtomS3
AtomS3 Lite
AtomS3U
AtomU
Basic
Capsule			✔
Cardputer	✔
Core2	✔
CoreInk	✔
CoreS3		✔
Dial	✔
DinMeter	✔
Fire
Paper
Stamp PICO
StampS3
Station
StickC			✔
StickC PLUS			✔
StickC PLUS2			✔
TOUGH	✔

Micropython Example:

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

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


circle0 = None
label0 = None


x = None
y = None


def setup():
    global circle0, label0, x, y

    M5.begin()
    Widgets.fillScreen(0x222222)
    circle0 = Widgets.Circle(160, 120, 60, 0xFFFFFF, 0xFFFFFF)
    label0 = Widgets.Label("Play", 141, 110, 1.0, 0x222222, 0xFFFFFF, Widgets.FONTS.DejaVu18)

    Speaker.begin()
    Speaker.playWavFile("/flash/res/audio/poweron_2_5s.wav")


def loop():
    global circle0, label0, x, y
    M5.update()
    if M5.Touch.getCount():
        x = M5.Touch.getX()
        y = M5.Touch.getY()
        if x >= 130 and x <= 190 and y >= 90 and y <= 150:
            circle0.setColor(color=0xFF0000, fill_c=0xFF0000)
            label0.setColor(0xFFFFFF, 0xFF0000)
            label0.setText(str("Play..."))
            Speaker.playWavFile("/flash/res/audio/poweron_2_5s.wav")
            label0.setText(str("Play"))
            circle0.setColor(color=0xFFFFFF, fill_c=0xFFFFFF)
            label0.setColor(0x000000, 0xFFFFFF)


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

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

UIFLOW2 Example:

cores3_speaker_example.m5f2

poweron_2_5s.wav

class Speaker

Important

Methods of the Speaker Class heavily rely on M5.begin() and M5.update() .

All calls to methods of Speaker objects should be placed after M5.begin() , and M5.update() should be called in the main loop.

Methods

Speaker.config([cfg])

Speaker.config('param')

Speaker.config(param=value)

Get or set the parameters of the Speaker object.

UIFLOW2:

Read property:

Parameter	Type	Description
pin_data_out	(integer)	Serial data line of I2S, representing audio data in binary complement.
pin_bck	(integer)	Serial clock line of I2S, corresponding to each bit of digital audio data.
pin_ws	(integer)	Frame clock of I2S, used to switch left and right channel data.
sample_rate	(integer)	Target sampling rate of output audio.
stereo	(boolean)	Use stereo output.
buzzer	(boolean)	Use single GPIO buzzer.
use_dac	(boolean)	Use DAC speaker.
dac_zero_level	(integer)	Zero level reference value when using DAC.
magnification	(integer)	Multiplier of the input value.
dma_buf_len	(integer)	DMA buffer length of I2S.
dma_buf_count	(integer)	Number of DMA buffers of I2S.
task_priority	(integer)	Priority of background tasks.
task_pinned_core	(integer)	CPU used by background tasks.
i2s_port	(integer)	I2S port.

Python:

Speaker.config("pin_data_in")

Set property:

Python:

Speaker.config(pin_data_in=1)

Speaker.begin() → bool

Start the Speaker function. Returns True if successful.

UIFLOW2:

Speaker.end() → None

Disable the Speaker.

UIFLOW2:

Speaker.isRunning() → bool

Check if the Speaker is running. Returns a boolean value.

UIFLOW2:

Speaker.isEnabled() → bool

Check if the Speaker is enabled. Returns a boolean value.

UIFLOW2:

Speaker.isPlaying([channel]) → bool

Check if the Speaker is playing sound. Returns a boolean value.

If the parameter channel is provided, it checks the playback status of the specified channel. channel accepts values from 0 to 7.

UIFLOW2:

Speaker.getPlayingChannels() → int

Get the number of channels currently playing.

UIFLOW2:

Speaker.setVolume(volume: int) → None

Set the master volume level for audio output. volume accepts volume levels from 0 to 255.

UIFLOW2:

Speaker.getVolume() → int

Get the master volume level for audio output. Returns volume levels from 0 to 255.

UIFLOW2:

Speaker.setVolumePercentage(percentage: float) → None

Set the master volume level for audio output as a percentage. percentage ranges from 0% to 100%.

UIFLOW2:

Speaker.getVolumePercentage() → float

Get the master volume level for audio output as a percentage. Returns volume levels from 0% to 100%.

UIFLOW2:

Speaker.setAllChannelVolume(volume: int) → None

Set the volume level for all virtual channels. volume accepts volume levels from 0 to 255.

UIFLOW2:

Speaker.setChannelVolume(channel: int, volume: int) → None

Set the volume level for a specific virtual channel.

Parameters:

• volume accepts volume levels from 0 to 255.

• channel is the channel to play, ranging from 0 to 7.

UIFLOW2:

Speaker.getChannelVolume(channel) → int

Get the volume level for a specific virtual channel. channel ranges from 0 to 7.

UIFLOW2:

Speaker.stop([channel]) → None

Stop sound output. If channel is not specified, stop sound output for all channels. channel accepts values from 0 to 7.

UIFLOW2:

Speaker.tone(frequency, duration[, channel[, stop_current_sound]]) → None

Play a simple tone.

Parameters:

• frequency is the frequency of the tone in Hz.

• duration is the duration of the tone in milliseconds.

• channel is the channel to play, ranging from 0 to 7. By default, it is -1, which means using an available channel.

• stop_current_sound controls whether to wait for the previous audio playback to finish. If True, start the new output without waiting for the current output to finish.

UIFLOW2:

Speaker.playRaw(wav_data: bytes|bytearray[, sample_rate: int[, stereo: bool[, repeat: int[, channel: int[, stop_current_sound: bool]]]]]) → bool

Play PCM data.

Parameters:

• wav_data is the buffer of audio data.

• sample_rate is the sample rate of the audio data.

• stereo specifies if the audio is stereo.

• repeat is the number of times to repeat the audio. Default is 1.

• channel is the channel to play, ranging from 0 to 7. By default, it is -1, which means using an available channel.

• stop_current_sound controls whether to wait for the previous audio playback to finish. If True, start the new output without waiting for the current output to finish.

UIFLOW2:

Speaker.playWav(wav_data: bytes|bytearray[, repeat: int[, channel: int[, stop_current_sound: bool]]]) → None

Play audio data in WAV format. Requires passing the raw data of the entire audio file.

Parameters:

• wav_data is the buffer of audio data.

• repeat is the number of times to repeat the audio. Default is 1.

• channel is the channel to play, ranging from 0 to 7. By default, it is -1, which means using an available channel.

• stop_current_sound controls whether to wait for the previous audio playback to finish. If True, start the new output without waiting for the current output to finish.

UIFLOW2:

Speaker.playWavFile(path: str[, repeat: int[, channel: int[, stop_current_sound: bool]]]) → None

Play audio data in WAV format. Requires passing the raw data of the entire audio file.

Parameters:

• path is the path to the audio file.

• repeat is the number of times to repeat the audio. Default is 1.

• channel is the channel to play, ranging from 0 to 7. By default, it is -1, which means using an available channel.

• stop_current_sound controls whether to wait for the previous audio playback to finish. If True, start the new output without waiting for the current output to finish.

UIFLOW2: