Skip to main content

Overview

The UAC microphone methods allow you to capture audio data from USB audio devices connected to your ESP32.

mic_frame_t Structure

Represents a microphone audio frame received from the USB device.
typedef struct {
    void *data;                 // Pointer to mic audio data
    uint32_t data_bytes;        // Size of audio data in bytes
    uint16_t bit_resolution;    // Bit resolution of the audio
    uint32_t samples_frequence; // Sample frequency in Hz
} mic_frame_t;

Methods

uacMicRegisterCb()

Registers a callback function to handle incoming microphone audio frames.

Syntax

void uacMicRegisterCb(mic_callback_t callback, void *cb_arg)

Parameters

  • callback (mic_callback_t) - Callback function of type void (*)(mic_frame_t *frame, void *user_ptr)
  • cb_arg (void*) - User-defined pointer passed to the callback function

Example

static void onMicFrameCallback(mic_frame_t *frame, void *ptr) {
    Serial.printf("Mic frame: %u bits, %u Hz, %u bytes\n",
        frame->bit_resolution,
        frame->samples_frequence,
        frame->data_bytes);
    
    // Process audio data in frame->data
    uint8_t *audio_data = (uint8_t *)frame->data;
    // Your audio processing here...
}

usb->uacMicRegisterCb(&onMicFrameCallback, NULL);

uacReadMic()

Reads audio data from the internal microphone buffer.

Syntax

void uacReadMic(uint8_t *buffer, size_t buf_size, size_t *data_bytes, size_t timeout_ms)

Parameters

  • buffer (uint8_t*) - Pointer to buffer to store the received audio data
  • buf_size (size_t) - Size of the buffer in bytes
  • data_bytes (size_t*) - Pointer to store the actual number of bytes read
  • timeout_ms (size_t) - Timeout for the read operation in milliseconds

Example

uint8_t mic_buffer[4096];
size_t bytes_read = 0;

usb->uacReadMic(mic_buffer, sizeof(mic_buffer), &bytes_read, 1000);

if (bytes_read > 0) {
    Serial.printf("Read %d bytes from microphone\n", bytes_read);
    // Process mic_buffer data
}

uacMicSuspend()

Suspends USB microphone streaming.

Syntax

void uacMicSuspend(void *ctrl_value)

Parameters

  • ctrl_value (void*) - Control value (typically NULL)

Example

usb->uacMicSuspend(NULL);

uacMicResume()

Resumes USB microphone streaming.

Syntax

void uacMicResume(void *ctrl_value)

Parameters

  • ctrl_value (void*) - Control value (typically NULL)

Example

usb->uacMicResume(NULL);

uacMicMute()

Mutes the USB microphone.

Syntax

void uacMicMute(void *ctrl_value)

Parameters

  • ctrl_value (void*) - Mute control value (0 = unmute, non-zero = mute)

Example

// Mute microphone
usb->uacMicMute((void *)1);

// Unmute microphone
usb->uacMicMute((void *)0);

uacMicVolume()

Controls the microphone volume.

Syntax

void uacMicVolume(void *ctrl_value)

Parameters

  • ctrl_value (void*) - Volume level value (device-specific range)

Example

// Set microphone volume to 60
usb->uacMicVolume((void *)60);

uacMicGetFrameSize()

Gets the frame size list of the currently connected microphone.

Syntax

uac_frame_size_t* uacMicGetFrameSize(uac_frame_size_t *frame_size)

Parameters

  • frame_size (uac_frame_size_t*) - Pointer to store the frame size information

Returns

Pointer to the frame size structure, or NULL on error.

uac_frame_size_t Structure

typedef struct {
    uint8_t ch_num;                 // Channel numbers
    uint16_t bit_resolution;        // Bit resolution in buffer
    uint32_t samples_frequence;     // Sample frequency
    uint32_t samples_frequence_min; // Minimum sample frequency
    uint32_t samples_frequence_max; // Maximum sample frequency
} uac_frame_size_t;

Example

uac_frame_size_t frame_info;
if (usb->uacMicGetFrameSize(&frame_info) != NULL) {
    Serial.printf("Mic format: %d ch, %d bits, %u Hz\n",
        frame_info.ch_num,
        frame_info.bit_resolution,
        frame_info.samples_frequence);
}

uacMicGetFrameListSize()

Gets the frame list size of the currently connected microphone.

Syntax

void uacMicGetFrameListSize(size_t *frame_size, size_t *frame_index)

Parameters

  • frame_size (size_t*) - Pointer to store the frame list size
  • frame_index (size_t*) - Pointer to store the current frame index

Example

size_t list_size = 0;
size_t current_index = 0;

usb->uacMicGetFrameListSize(&list_size, &current_index);
Serial.printf("Frame list size: %d, current index: %d\n", list_size, current_index);

uacMicFrameReset()

Resets microphone audio channel number, bit resolution, and sample frequency. Call this when streaming is in suspend state. The new configuration becomes effective after streaming resumes.

Syntax

void uacMicFrameReset(uint8_t ch_num, uint16_t bit_resolution, uint32_t samples_frequency)

Parameters

  • ch_num (uint8_t) - Audio channel numbers (1-2)
  • bit_resolution (uint16_t) - Audio bit resolution (8-24)
  • samples_frequency (uint32_t) - Audio sample frequency in Hz (1000-48000)

Example

// Suspend microphone first
usb->uacMicSuspend(NULL);

// Reset to stereo, 16-bit, 48kHz
usb->uacMicFrameReset(2, 16, 48000);

// Resume with new settings
usb->uacMicResume(NULL);

Complete Microphone Example

#include <Arduino.h>
#include "USB_STREAM.h"

// Microphone callback function
static void onMicFrameCallback(mic_frame_t *frame, void *ptr) {
    Serial.printf("Mic frame: bit_resolution=%u, samples_frequence=%u, data_bytes=%u\n",
        frame->bit_resolution,
        frame->samples_frequence,
        frame->data_bytes);
    
    // Process audio data
    uint8_t *audio_data = (uint8_t *)frame->data;
    // Add your audio processing logic here
}

void setup() {
    Serial.begin(115200);
    
    // Create USB_STREAM instance
    USB_STREAM *usb = new USB_STREAM();
    
    // Configure microphone (accept any format, 6400 byte buffer)
    usb->uacConfiguration(
        UAC_CH_ANY,          // Accept any mic channels
        UAC_BITS_ANY,        // Accept any mic bit resolution
        UAC_FREQUENCY_ANY,   // Accept any mic frequency
        6400,                // 6400 byte mic buffer
        UAC_CH_ANY,          // No speaker
        UAC_BITS_ANY,
        UAC_FREQUENCY_ANY,
        0                    // No speaker buffer
    );
    
    // Register microphone callback
    usb->uacMicRegisterCb(&onMicFrameCallback, NULL);
    
    // Start USB streaming
    usb->start();
    
    // Wait for device connection
    usb->connectWait(1000);
    delay(1000);
    
    // Get microphone frame information
    uac_frame_size_t frame_info;
    if (usb->uacMicGetFrameSize(&frame_info) != NULL) {
        Serial.printf("Microphone format: %d channels, %d bits, %u Hz\n",
            frame_info.ch_num,
            frame_info.bit_resolution,
            frame_info.samples_frequence);
    }
    
    // Unmute microphone
    usb->uacMicMute((void *)0);
    
    // Set volume to 60
    usb->uacMicVolume((void *)60);
    
    // Example: Suspend and resume
    delay(5000);
    usb->uacMicSuspend(NULL);
    Serial.println("Microphone suspended");
    
    delay(2000);
    usb->uacMicResume(NULL);
    Serial.println("Microphone resumed");
}

void loop() {
    // Alternative: Read microphone data directly
    uint8_t mic_buffer[2048];
    size_t bytes_read = 0;
    
    // Read with 100ms timeout
    USB_STREAM *usb = USB_STREAM::getInstance(); // Get instance
    usb->uacReadMic(mic_buffer, sizeof(mic_buffer), &bytes_read, 100);
    
    if (bytes_read > 0) {
        Serial.printf("Read %d bytes from microphone\n", bytes_read);
        // Process mic_buffer
    }
    
    delay(100);
}

Notes

  • Register the microphone callback before calling start().
  • The callback function should execute quickly to avoid blocking audio streaming.
  • Use higher baud rates (e.g., 115200 or higher) when printing from the callback to reduce blocking time.
  • You can use either the callback method (uacMicRegisterCb) or polling method (uacReadMic) to receive audio data.
  • Frame reset must be performed while streaming is suspended.

Build docs developers (and LLMs) love