M5Unified Speaker Class

• Speaker Class
  • config
  • begin
  • end
  • isRunning
  • isEnabled
  • isPlaying
  • getPlayingChannels
  • setVolume
  • getVolume
  • setAllChannelVolume
  • setChannelVolume
  • getChannelVolume
  • stop
  • tone
  • playRaw
  • playWav

config

Syntax:

speaker_config_t config(void);

Description:

• Get the current Speaker configuration information

Parameters:

• null

Return:

• speaker_config_t: Speaker configuration information

  struct speaker_config_t
  {
    /// i2s_data_out (for spk)
    int pin_data_out = I2S_PIN_NO_CHANGE;
    /// i2s_bck
    int pin_bck = I2S_PIN_NO_CHANGE;
    /// i2s_ws (lrck)
    int pin_ws = I2S_PIN_NO_CHANGE;
    /// output sampling rate (Hz)
    uint32_t sample_rate = 48000;
    /// use stereo output
    bool stereo = false;
    /// use single gpio buzzer, ( need only pin_data_out )
    bool buzzer = false;
    /// use DAC speaker, ( need only pin_data_out ) ( for ESP32, only GPIO_NUM_25 or GPIO_NUM_26 )
    /// ※ for ESP32, need `i2s_port = I2S_NUM_0`. ( DAC+I2S_NUM_1 is not available )
    bool use_dac = false;
    /// Zero level reference value when using DAC ( 0=Dynamic change )
    uint8_t dac_zero_level = 0;
    /// multiplier for output value
    uint8_t magnification = 16;
    /// for I2S dma_buf_len (max 1024)
    size_t dma_buf_len = 256;
    /// for I2S dma_buf_count
    size_t dma_buf_count = 8;
    /// background task priority
    uint8_t task_priority = 2;
    /// background task pinned core
    uint8_t task_pinned_core = ~0;
    /// I2S port
    i2s_port_t i2s_port = i2s_port_t::I2S_NUM_0;
  };

Syntax:

void config(const speaker_config_t& cfg);

Description:

• Configure the Speaker configuration information

Parameters:

• speaker_config_t& cfg:
  • Reference to the configuration information

Return:

• null

begin

Syntax:

bool begin(void);

Description:

• Initialize the Speaker

Parameters:

• null

Return:

• null

end

Syntax:

void end(void);

Description:

• Reverse initialization

Parameters:

• null

Return:

• null

isRunning

Syntax:

bool isRunning(void);

Description:

• Determine if the current Speaker background task is running

Parameters:

• null

Return:

• bool:
  • true: Running
  • false: Not running

isEnabled

Syntax:

bool isEnabled(void);

Description:

• Determine if the current Speaker is initialized

Parameters:

• null

Return:

• bool:
  • true: Initialized
  • false: Not initialized

isPlaying

Syntax:

bool isPlaying(void);

Description:

• Determine if the current Speaker is in the playing state

Parameters:

• null

Return:

• bool:
  • true: In playing state
  • false: Not in playing state

Syntax:

size_t isPlaying(uint8_t channel);

Description:

• Determine if a specific virtual channel of the current Speaker is in the playing state

Parameters:

• uint8_t channel:
  • Virtual channel: 0-7

Return:

• size_t:
  • Not playing: 0
  • Playing (There's room in the queue): 1
  • Playing (There's no room in the queue.): 2

getPlayingChannels

Syntax:

size_t getPlayingChannels(void);

Description:

• Get the number of virtual channels that are currently in the playing state

Parameters:

• null

Return:

• size_t: Number of virtual channels

setVolume

Syntax:

void setVolume(uint8_t master_volume);

Description:

• Set the playback volume

Parameters:

• uint8_t master_volume:
  • 0-255

Return:

• null

getVolume

Syntax:

uint8_t getVolume(void);

Description:

• Get the playback volume

Parameters:

• null

Return:

• uint8_t volume:
  • Playback volume

setAllChannelVolume

Syntax:

void setAllChannelVolume(uint8_t volume);

Description:

• Set the playback volume for all virtual channels

Parameters:

• uint8_t volume:
  • 0-255

Return:

• null

setChannelVolume

Syntax:

void setChannelVolume(uint8_t channel, uint8_t volume);

Description:

• Set the playback volume for a specific virtual channel

Parameters:

• uint8_t channel:
  • Virtual channel: 0-7
• uint8_t volume:
  • 0-255

Return:

• null

getChannelVolume

Syntax:

uint8_t getChannelVolume(uint8_t channel);

Description:

• Get the playback volume for a specific virtual channel

Parameters:

• uint8_t channel:
  • Virtual channel: 0-7

Return:

• uint8_t volume:
  • Playback volume

stop

Syntax:

void stop(void);

Description:

• Stop playback

Parameters:

• null

Return:

• null

Syntax:

void stop(uint8_t channel);

Description:

• Stop playback on a specific virtual channel

Parameters:

• uint8_t channel:
  • Virtual channel: 0-7

Return:

• null

tone

Syntax:

bool tone(float frequency, uint32_t duration, int channel, bool stop_current_sound, const uint8_t* raw_data, size_t array_len, bool stereo = false);

Description:

• Play a tone at a specified frequency

Parameters:

• float frequency:
  • Tone frequency (Hz)
• uint32_t duration:
  • Tone duration in milliseconds
• int channel:
  • Virtual channel: 0-7
• bool stop_current_sound:
  • true: Stop the current playback and execute the new playback
  • false: Do not stop the current playback
• const uint8_t* raw_data:
  • Single amplitude audio, 8-bit unsigned WAV data.
• size_t array_len:
  • Size of raw_data
• bool stereo:
  • true: Stereo
  • false: Mono

Return:

• bool:
  • true: Successfully executed
  • false: Execution failed

Syntax:

bool tone(float frequency, uint32_t duration = UINT32_MAX, int channel = -1, bool stop_current_sound = true);

Description:

• Play a tone at a specified frequency

Parameters:

• float frequency:
  • Tone frequency (Hz)
• uint32_t duration:
  • Tone duration in milliseconds
• int channel:
  • Virtual channel: 0-7
• bool stop_current_sound:
  • true: Stop the current playback and execute the new playback
  • false: Do not stop the current playback

Return:

• bool:
  • true: Successfully executed
  • false: Execution failed

playRaw

Syntax:

bool playRaw(const int8_t* raw_data, size_t array_len, uint32_t sample_rate = 44100, bool stereo = false, uint32_t repeat = 1, int channel = -1, bool stop_current_sound = false);

bool playRaw(const uint8_t* raw_data, size_t array_len, uint32_t sample_rate = 44100, bool stereo = false, uint32_t repeat = 1, int channel = -1, bool stop_current_sound = false);

bool playRaw(const int16_t* raw_data, size_t array_len, uint32_t sample_rate = 44100, bool stereo = false, uint32_t repeat = 1, int channel = -1, bool stop_current_sound = false);

Description:

• Play unsigned 8-bit, signed 8-bit, signed 16-bit WAV raw audio data

Parameters:

• const uint8_t* raw_data / int8_t / int16_t:
  • Pointer to raw audio data
• size_t array_len:
  • Length of raw audio data
• uint32_t sample_rate:
  • Sampling rate of the raw audio data
• bool stereo:
  • true: Stereo
  • false: Mono
• uint32_t repeat:
  • Number of times to repeat playback. (Default = 1)
• int channel:
  • Virtual channel: 0-7
• bool stop_current_sound:
  • true: Stop the current playback and execute the new playback
  • false: Do not stop the current playback

Return:

• bool:
  • true: Successfully executed
  • false: Execution failed

playWav

Syntax:

bool playWav(const uint8_t* wav_data, size_t data_len = ~0u, uint32_t repeat = 1, int channel = -1, bool stop_current_sound = false);

Description:

• Play WAV format audio file data

Parameters:

• const uint8_t* wav_data:
  • WAV data. (Includes WAV format header)
• size_t data_len:
  • Data length
• uint32_t repeat:
  • Number of times to repeat playback. (Default = 1)
• int channel:
  • Virtual channel: 0-7
• bool stop_current_sound:
  • true: Stop the current playback and execute the new playback
  • false: Do not stop the current playback

Return:

• bool:
  • true: Successfully executed
  • false: Execution failed