feat(audio): add USB Audio Host (UAC 1.0/2.0) support

[zjzhang-cn]

Add TinyUSB Host Audio class driver supporting UAC 1.0/2.0 devices.

Features:

• Support multiple Audio Streaming (AS) interfaces with independent format storage
• Support both IN (Microphone) and OUT (Speaker) endpoints
• Support Explicit feedback
• Per-AS interface format info: channels, sample rate, bit resolution
• Support Feature Unit volume/mute control
• Add host/audio_host example
• Support mono-to-stereo conversion for loopback

Changes:

• Add src/class/audio/audio_host.c and audio_host.h
• Register AUDIO driver in usbh.c
• Add CFG_TUH_AUDIO macro in tusb_option.h
• Add host/audio_host example with CMake and Makefile build support

Tested with Jabra USB headset (stereo speaker + mono microphone) on STM32F407 disco.

[Copilot]

Pull request overview

This PR introduces initial USB Audio Class (UAC 1.0) Host support to TinyUSB by adding a new host class driver (audio_host.c/.h), wiring it into the host driver registry, and providing a new host-side example application demonstrating enumeration and basic streaming/control requests.

Changes:

• Add a new TUH Audio (UAC 1.0) host class driver and public host API header.
• Integrate the new class driver into the host stack and build systems (CMake + Make).
• Add a new examples/host/audio_host example + README.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
src/tusb.h	Expose TUH audio host API when CFG_TUH_AUDIO is enabled.
src/tusb_option.h	Add default CFG_TUH_AUDIO option.
src/tinyusb.mk	Compile new audio host class driver.
src/host/usbh.c	Register audio host class driver in the host class driver table.
src/CMakeLists.txt	Add class/audio/audio_host.c to TinyUSB core sources.
src/class/audio/audio_host.h	New TUH audio host public API + callback types.
src/class/audio/audio_host.c	New UAC1 host driver implementation (enumeration, set_config, transfers, control requests).
examples/host/audio_host/src/tusb_config.h	New example configuration enabling TUH audio.
examples/host/audio_host/src/main.c	New host example main loop.
examples/host/audio_host/src/audio_app.c	New example “loopback” style audio logic and callbacks.
examples/host/audio_host/src/app.h	Example app header.
examples/host/audio_host/README.md	Example documentation.
examples/host/audio_host/Makefile	Make-based build for the new example.
examples/host/audio_host/CMakeLists.txt	CMake-based build for the new example.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

MemBrowse Memory Report

No memory changes detected across 2530 targets. View Project Dashboard →

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 11 comments.

[github-actions]

Hardware-in-the-loop (HIL) Test Report

hfp.json

✅ 55 passed · ❌ 1 failed · ⚪ 0 skipped · blank not run

Board	usbtest	cdc_msc_throughput	audio_test_freertos	cdc_dual_ports	cdc_msc	cdc_msc_freertos	dfu	dfu_runtime	hid_boot_interface	hid_generic_inout	midi_test	msc_dual_lun	mtp	printer_to_cdc	duration
lpcxpresso43s67	❌ 0/30	✅ C 12/10.5M M 33/30.7M	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	85s
stm32l412nucleo	✅ 30/30	✅ C 501/502k M 511/511k	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	95s
stm32f746disco	✅ 30/30	✅ C 13.7/12.4M M 23.4/31.3M	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	97s
stm32f746disco-DMA	✅ 30/30	✅ C 15/13.7M M 26.1/34M	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	86s

tinyusb-esp.json

✅ 0 passed · ❌ 24 failed · ⚪ 0 skipped · blank not run

Board	usbtest	msc_file_explorer_freertos	audio_test_freertos	cdc_msc_freertos	device_info	hid_composite_freertos	duration
espressif_p4_function_ev	❌	❌	❌	❌	❌	❌	3s
espressif_p4_function_ev-DMA	❌	❌	❌	❌	❌	❌	3s
espressif_s3_devkitm	❌	❌	❌	❌	❌	❌	3s
espressif_s3_devkitm-DMA	❌	❌	❌	❌	❌	❌	3s

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 8 comments.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 9 comments.

Comments suppressed due to low confidence (1)

examples/host/audio_host/README.md:99

• The Notes section says the example sends a "simple sine wave", but the implementation actually loops back received microphone data to the speaker (with optional mono-to-stereo conversion). This is misleading for users trying to understand the example's behavior.

## Notes

- This example uses isochronous transfers which require precise timing
- For production applications, synchronize audio transfers with the device's audio clock
- The example sends a simple sine wave for testing; replace with actual audio data in real applications

[HiFiPhile]

Thank you for your work, beside auto reviews, there is a need of some architectural changes:

API shaping

tuh_audio_descriptor_cb and tuh_audio_mount_cb_t should be removed as these are class specific details, we can't expect every user to read UAC specification.
Instead we should provide a list of supported format and sample frequency , similar to aplay --dump-hw-params or Windows audio device properties tab, then the class driver select the corresponding alt settings and sample frequency based user input.
It also makes later UAC2 support easier.
Anyway tuh_descriptor_get_configuration exist if someone needs the detail.

Buffering and packet scheduling

Similar to device driver, FIFO should be included in host driver.
Packet scheduling should be implemented for OUT terminal, when non-integer sample rate is selected eg. 44.1k, the driver should send 9* 44 slots packets and 1* 45 slots packet.
(Optional) feedback support - feedback can be implemented in the same time as packet scheduling, using device feedback sample rate as reference.

[zjzhang-cn]

I've first completed the API design modifications. Please see if it works

[HiFiPhile]

As I commented earlier, the class driver should provide a WASAPI/ALSA-like high-level API for audio streaming, while keeping the USB Audio topology private.

We can keep the limitation that there is only one logical stream in each direction per instance (AC interface), which is the most common case.

If an instance has multiple Audio Streaming interfaces or alternate settings in one direction, their supported configurations can be combined into the corresponding logical stream. The driver keeps the mapping from each configuration to its interface, alternate setting, and endpoint.

This follows the general WASAPI exclusive-mode and ALSA hw: model: applications select channel count, sample format, and sample rate, while the driver performs the hardware-specific mapping.

Proposed API

Only discrete configurations need to be supported initially. Continuous sample-rate ranges can be rejected or ignored explicitly.

typedef enum {
  TUH_AUDIO_FORMAT_S8,
  TUH_AUDIO_FORMAT_S16_LE,
  TUH_AUDIO_FORMAT_S24_3LE,
  TUH_AUDIO_FORMAT_S24_LE,
  TUH_AUDIO_FORMAT_S32_LE
} tuh_audio_format_t;

typedef struct {
  tuh_audio_format_t format;
  uint32_t sample_rate;
  uint8_t channels;
} tuh_audio_stream_config_t;

typedef void (*tuh_audio_configure_cb_t)(
  uint8_t idx,
  tusb_dir_t direction,
  tusb_xfer_result_t result,
  uintptr_t user_data);

Each entry is a complete supported tuple, avoiding invalid combinations between independent format, rate, and channel lists.

bool tuh_audio_stream_exists(uint8_t idx, tusb_dir_t direction);

uint8_t tuh_audio_config_count(uint8_t idx, tusb_dir_t direction);

bool tuh_audio_config_get(
  uint8_t idx,
  tusb_dir_t direction,
  uint8_t config_idx,
  tuh_audio_stream_config_t* config);

bool tuh_audio_configure(
  uint8_t idx,
  tusb_dir_t direction,
  tuh_audio_stream_config_t const* config,
  tuh_audio_configure_cb_t complete_cb,
  uintptr_t user_data);

tuh_audio_configure() should require an exact supported tuple and asynchronously:

1. Find its AS interface and alternate setting.
2. Issue SET_INTERFACE.
3. Open or reconfigure the selected endpoint.
4. Set the endpoint sampling frequency when supported.
5. Initialize the FIFO and packet scheduler.
6. Invoke complete_cb after the stream is ready or an operation fails.

Streaming should be frame-based:

uint32_t tuh_audio_write(uint8_t idx, void const* buffer, uint32_t frame_count);
uint32_t tuh_audio_read(uint8_t idx, void* buffer, uint32_t frame_count);

uint32_t tuh_audio_write_available(uint8_t idx);
uint32_t tuh_audio_read_available(uint8_t idx);

bool tuh_audio_start(uint8_t idx, tusb_dir_t direction);
bool tuh_audio_stop(uint8_t idx, tusb_dir_t direction);

The class driver should own endpoint selection, FIFO management, transfer replenishment, fractional packet scheduling, and optional feedback processing.

Basic microphone example

The application selects a supported 48 kHz, mono, 16-bit capture configuration without accessing USB interfaces, alternate settings, or endpoint addresses.

static uint8_t mic_idx = TUSB_INDEX_INVALID_8;
static bool mic_ready;
static int16_t mic_samples[48];

static void mic_configured(uint8_t idx, tusb_dir_t direction,
                           tusb_xfer_result_t result, uintptr_t user_data) {
  (void) user_data;

  if (direction == TUSB_DIR_IN && result == XFER_RESULT_SUCCESS) {
    mic_ready = tuh_audio_start(idx, TUSB_DIR_IN);
  }
}

void tuh_audio_mount_cb(uint8_t idx) {
  if (!tuh_audio_stream_exists(idx, TUSB_DIR_IN)) {
    return;
  }

  for (uint8_t i = 0; i < tuh_audio_config_count(idx, TUSB_DIR_IN); i++) {
    tuh_audio_stream_config_t config;
    if (tuh_audio_config_get(idx, TUSB_DIR_IN, i, &config) &&
        config.format == TUH_AUDIO_FORMAT_S16_LE &&
        config.sample_rate == 48000 &&
        config.channels == 1) {
      mic_idx = idx;
      (void) tuh_audio_configure(idx, TUSB_DIR_IN, &config, mic_configured, 0);
      return;
    }
  }
}

void tuh_audio_umount_cb(uint8_t idx) {
  if (idx == mic_idx) {
    mic_idx = TUSB_INDEX_INVALID_8;
    mic_ready = false;
  }
}

void audio_app_task(void) {
  const uint32_t frame_count = TU_ARRAY_SIZE(mic_samples);
  if (mic_ready && tuh_audio_read_available(mic_idx) >= frame_count) {
    (void) tuh_audio_read(mic_idx, mic_samples, frame_count);
    // Process 1 ms of 48 kHz mono audio here.
  }
}

Correctness issues

1. Audio Host can consume MIDI interfaces.
   audioh_open() continues across every TUSB_CLASS_AUDIO interface. MIDI Streaming uses the same class with another subclass, and Audio Host is registered first. Parse only associated Audio Streaming interfaces, preferably using the AC header’s interface collection.

2. Alternate settings are overwritten and opened prematurely.
   Every discrete format must remain a separate internal configuration. Do not open every endpoint during descriptor parsing; open or reconfigure only the alternate setting selected by tuh_audio_configure().

3. SET_INTERFACE failures are ignored.
   Check the return value of tuh_interface_set() and xfer->result. A submission failure currently stalls enumeration, while a failed transfer can still mount the device.

4. Transfer parameters are insufficiently validated.
   Validate instance state, direction, buffers, frame counts, and endpoint packet limits before submitting transfers.

5. Feature Unit request lengths are hard-coded.
   UAC1 mute uses a one-byte value while volume uses two bytes. The current generic API always transfers two bytes.

6. Failed isochronous transfers reach application callbacks.
   audioh_xfer_cb() should not report failed, stalled, or aborted transfers as valid audio data.

7. The example can overflow its TX buffer.
   Mono-to-stereo conversion doubles the received byte count without bounding it against the TX buffer and selected OUT packet size.

8. Control-transfer byte order is incomplete.
   Setup-packet multibyte fields require little-endian conversion. Three-byte sampling frequencies and Feature Unit values must be explicitly converted to host-order values.

This smaller API should be enough for a first UAC1 host implementation while leaving room for multiple streams, continuous rates, conversion, and channel mapping later.

[zjzhang-cn]

During the modification process, a phenomenon was discovered: when MIC and Speaker are both open, usbh_edpt_xfer performing write operations must be called after the TUSB_DIR_IN callback in audioh_xfer_cb; it causes issues in other places.
在修改的过程中发现一个现象，在同时打开MIC 和 Speaker后 usbh_edpt_xfer进行做写操作必须在audioh_xfer_cb的TUSB_DIR_IN回调后调用，其他的地方均有问题。

[HiFiPhile]

During the modification process, a phenomenon was discovered: when MIC and Speaker are both open, usbh_edpt_xfer performing write operations must be called after the TUSB_DIR_IN callback in audioh_xfer_cb; it causes issues in other places. 在修改的过程中发现一个现象，在同时打开MIC 和 Speaker后 usbh_edpt_xfer进行做写操作必须在audioh_xfer_cb的TUSB_DIR_IN回调后调用，其他的地方均有问题。

What kind of issue you met ? There could be some issues as DWC2 HCD hasn't been tested with ISO transfer yet, do you have a USB protocol analyzer ?
At a glance hcchar_bm->err_multi_count should be set to 1.
I may have some time to look into it during my holidays.
也可以给我发邮件.

[zjzhang-cn]

Running on STM32F4 requires PR 3815

[HiFiPhile]

Finally I've some time to visit audio host...

The general framework is good, I've made some adjustments and introduced volume/mute api. Now it works correctly with uac2_headset example.

I'm planning to add feedback and UAC2 support.

[Copilot]

🟡 Changes recommended

Transfer-submission failures can permanently stall streams, valid independent duplex rates are rejected, and the promised sampling-frequency get operation is absent.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

src/class/audio/audio_host.c:369

• A failed playback submission leaves the stream marked running with no transfer in flight, so it cannot make progress or be restarted; it also silently discards the frames removed from the FIFO above. Route submission failure through the stream-error path so the application is notified and can restart.

  TU_ASSERT(usbh_edpt_xfer(s->daddr, map->ep_addr, s->edpt.ep_buf, bytes), );

• Files reviewed: 23/23 changed files
• Comments generated: 4
• Review effort level: Balanced

[HiFiPhile]

I've finished explicit feedback and UAC2 work, spent most of the time on #3815.

Tested on Nucleo-U5A5 with a UAC2 high-speed headset.