feat(audio): add USB Audio Host (UAC 1.0) support - #3774
Conversation
Add TinyUSB Host Audio class driver supporting UAC 1.0 devices. Features: - Support multiple Audio Streaming (AS) interfaces with independent format storage - Support both IN (Microphone) and OUT (Speaker) endpoints - Per-AS interface format info: channels, sample rate, bit resolution - Support Feature Unit volume control - Support sampling frequency get/set - Add host/audio_host example for STM32F407 discovery board - 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.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
zjzhang-cn
changed the title
There was a problem hiding this comment.
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_hostexample + 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.
|
…sync control transfer buffer - Stop parsing at first non-Audio interface in audioh_open to avoid claiming unrelated interfaces - Call usbh_driver_set_config_complete for AS and unknown interfaces to allow enumeration to continue - Add global ctrl endpoint buffer to audioh_epbuf_t to fix use-after-return in feature_unit_set - Add sampling_freq NULL check and initialize to 0 in tuh_audio_get_sampling_freq - Change BOARD_TUH_RHPORT from 1 to 0 in audio_host example - Add only.txt with supported MCU/family list for audio_host example
Hardware-in-the-loop (HIL) Test Reporthfp.json✅ 56 passed · ❌ 0 failed · ⚪ 0 skipped · blank not run
tinyusb-esp.json✅ 22 passed · ❌ 2 failed · ⚪ 0 skipped · blank not run
tinyusb.json✅ 332 passed · ❌ 49 failed · ⚪ 17 skipped · blank not run
|
…audio host - Fix missing tu_htole16() conversions for wValue and wIndex in tuh_audio_set_sampling_freq, tuh_audio_get_sampling_freq, tuh_audio_feature_unit_set, and tuh_audio_feature_unit_get - Fix incorrect wIndex parameter order in feature unit requests (unit_id and itf_num were swapped) - Replace static freq_buf with per-endpoint ctrl buffer in tuh_audio_set_sampling_freq to avoid concurrency issues - Update audio_host README to match actual example behavior
…nify const style Rename descriptor pointer variables to use desc_ prefix for consistency with audio_device.c: - it -> desc_input_terminal - ot -> desc_output_terminal - fu -> desc_feature_unit - itf -> desc_interface - p_ep -> desc_endpoint Unify const qualifier placement to type_t const * style. Add file header comment describing UAC 1.0 host driver capabilities. Switch license header to SPDX identifier.
There was a problem hiding this comment.
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
|
Thank you for your work, beside auto reviews, there is a need of some architectural changes: API shaping
Buffering and packet schedulingSimilar to device driver, FIFO should be included in host driver. |
This commit refactors the TUH_AUDIO (USB Audio Host) class driver to
simplify its public API and improve multi-AS (Audio Streaming) interface
support. The changes are focused on three files: the core driver
(audio_host.c/h) and the example application (audio_app.c).
Key changes in src/class/audio/audio_host.h:
- Remove tuh_audio_descriptor_cb_t and tuh_audio_mount_cb_t structures.
The mount callback no longer passes a large descriptor-info struct;
applications query per-AS info via tuh_audio_as_get_info().
- Add tuh_audio_get_dev_addr() and tuh_audio_get_feature_unit_id()
accessors to retrieve device address and feature-unit ID from an
interface index.
- Simplify control-transfer APIs by replacing (daddr, itf_num, unit_id)
parameters with a single idx parameter:
tuh_audio_set_sampling_freq(idx, as_idx, ...)
tuh_audio_get_sampling_freq(idx, as_idx, ...)
tuh_audio_feature_unit_set(idx, control_selector, channel, ...)
tuh_audio_feature_unit_get(idx, control_selector, channel, ...)
- Add synchronous wrapper APIs using TU_API_SYNC macro:
tuh_audio_get_sampling_freq_sync()
tuh_audio_set_sampling_freq_sync()
tuh_audio_feature_unit_set_sync()
tuh_audio_feature_unit_get_sync()
- Update isochronous endpoint APIs to use (idx, as_idx) instead of
(daddr, idx):
tuh_audio_receive(idx, as_idx, buffer, len)
tuh_audio_send(idx, as_idx, buffer, len)
- Remove tuh_audio_descriptor_cb() weak callback.
- Update tuh_audio_mount_cb() signature from mount_cb(param) to no param.
- Update tuh_audio_rx_cb()/tuh_audio_tx_cb() first parameter from idx to
dev_addr for consistency with other class drivers.
Key changes in src/class/audio/audio_host.c:
- Delete tuh_audio_descriptor_cb weak stub.
- Refactor get_idx_by_ep_addr() to iterate all AS interfaces per device
instead of relying on single ep_in/ep_out fields.
- Add audioh_get_ep_addr_by_dir() helper to find an endpoint address by
direction across multiple AS interfaces.
- Simplify audioh_close() cleanup: remove now-removed single-endpoint
fields (ep_in, ep_out) and rely on tu_memclr(p_audio->as, ...).
- Update audioh_xfer_cb() to pass dev_addr (not idx) to rx/tx callbacks,
matching the new callback signature.
- Simplify audioh_open(): remove descriptor-callback emission and the
temporary desc_cb structure; store only ac_itf_num instead of
bInterfaceNumber + iInterface + as_interface_num.
- Rename local descriptor pointers for clarity:
desc_input_terminal (was desc_it)
desc_output_terminal (was desc_ot)
Key changes in examples/host/audio_host/src/audio_app.c:
- Remove now-unnecessary globals: audio_ep_in, audio_ep_out, audio_ac_itf,
audio_feature_unit_id.
- Initialize audio_dev_addr, audio_idx, audiostream_in_idx,
audiostream_out_idx to 0xFF (TUSB_INDEX_INVALID_8) instead of 0.
- Update print_as_interfaces() to use tuh_audio_as_get_count() and
tuh_audio_as_get_info() instead of accessing mount_cb_data.
- Update all callback signatures and API calls to match the new driver API.
|
I've first completed the API design modifications. Please see if it works |
|
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 Proposed APIOnly 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);
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 exampleThe 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
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. |
|
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. |
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 ? |
Provide a high-level audio streaming API over UAC 1.0 devices while
keeping the USB topology private: applications select supported
{format, sample_rate, channels} configurations per logical stream, and
the driver owns the mapping to AS interface, alternate setting, and
endpoint.
- One logical stream per direction per instance; multiple AS interfaces
and alternate settings in a direction are merged into the stream's
configuration list (discrete tuples; continuous ranges exposed as a
single configuration at the top rate)
- Asynchronous tuh_audio_configure(): SET_INTERFACE to the selected
alternate setting, open/reconfigure the endpoint, set the sampling
frequency when supported, initialize the FIFO and packet scheduler,
then invoke the completion callback
- Frame-based FIFO streaming: tuh_audio_read()/tuh_audio_write() queue
whole frames; the driver owns transfer replenishment and fractional
packet scheduling (44.1 kHz pays back the 0.1 frame/ms remainder via
an accumulator for exact average pacing)
- tuh_audio_start()/tuh_audio_stop() activate/deactivate the stream
interface through SET_INTERFACE (alt n / alt 0)
Driver correctness fixes:
- Parse only the AC header's interface collection; MIDI Streaming and
other subclasses are skipped
- Keep every discrete format as a separate configuration; endpoints are
opened only for the alternate setting selected by tuh_audio_configure()
- Check tuh_interface_set() return values and SET_INTERFACE transfer
results instead of ignoring failures
- Validate instance state, direction, buffers, and frame counts in every
transfer API
- Feature Unit requests use the control's real width (mute/AGC/loudness
1 byte, others 2 bytes) and convert multibyte values to host order
- Failed/stalled/aborted isochronous transfers reach only the error
callback, never the capture/playback callbacks
The audio_host example uses the new API: 48 kHz stereo by default,
automatic stream restart on error callbacks, a sine test tone on the
playback stream, and periodic mic-only / spk-only / echo phase switching.
|
Running on STM32F4 requires PR 3815 |
Add the missing preset and shared declarations, remove duplicate initialization, and correct callback call sites so the new example builds through the normal CMake flow. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Record terminal and Feature Unit links while parsing the AudioControl block, then resolve the stream association after all entities are known. Common capture and playback descriptor orders are both supported. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Add a Ceedling harness for Audio Host descriptor parsing, stream configuration, controls, and packet scheduling. The suite provides regression coverage for the review fixes. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Look up the playback Feature Unit in the host example and set its master volume after configuration. The output also reports when a stream has no controllable Feature Unit. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Bring the audio work onto the current host core and build files before applying the remaining review fixes. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Keep capture and playback transfers continuously armed from their completion callbacks. Capture overwrites the oldest complete frames when full, while playback sends silence on underrun without consuming partial queued audio. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Make configuration a synchronous local operation that selects and opens the endpoint. Start now activates the alternate setting and sets the sampling frequency afterward, including every restart, so devices cannot reset the selected rate with SET_INTERFACE. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Enter the microphone-only phase before starting playback when both directions exist. This avoids briefly selecting the playback alternate setting and immediately returning it to alt 0. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Replace the six-sample waveform with a 64-entry sine table and phase accumulator. The example now generates a continuous 1 kHz tone at the selected rate and packs the configured channel count correctly. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Parse the contiguous AudioStreaming interfaces by class and subclass instead of copying baInterfaceNr. This removes the UAC1-only collection limit and prevents MIDI AudioControl interfaces from leaving a half-allocated Audio Host instance. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Collect one audio data endpoint for each alternate setting and ignore explicit feedback endpoints until feedback scheduling is implemented. Validate the maximum packet for every discrete rate against the endpoint, transfer buffer, and FIFO. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Route asynchronous activation and sampling-frequency failures through the stream error callback. Keep a running stream active when SET_INTERFACE alt 0 cannot be submitted so stop can be retried without diverging from device state. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Require the UAC1 AudioControl protocol before allocating an instance. The current parser assumes UAC1 descriptor layouts, so accepting UAC2 would misinterpret entities and consume a host slot. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Keep one unresolved Feature Unit candidate per stream direction while parsing AudioControl entities. Duplex functions are now associated correctly even when both Feature Units precede their USB terminals. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Continue draining the capture FIFO but skip channel conversion and writes when playback is unavailable or intentionally stopped. This keeps capture running safely in microphone-only phases. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Retain an audio function when at least one direction has a supported configuration, but release the tentative instance when neither direction does. Unsupported and MIDI-only functions no longer consume host slots or emit mount callbacks. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Treat isochronous bInterval as a power-of-two exponent for both full and high speed, using the appropriate frame unit. Packet sizing and fractional scheduling now use the actual service interval. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Keep the sampling-frequency control flag in the alternate-setting parser state shared by its single data endpoint. This supports either descriptor order without separate pending and unassigned endpoint flags. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Check descriptor bounds, minimum lengths, frequency counts, and interface types with the host validation helpers before accessing fields. Malformed UAC1 functions now fail enumeration without out-of-bounds reads. Signed-off-by: HiFiPHile <admin@hifiphile.com>
Inspect each associated Feature Unit during mount, cache master mute support and the common MIN, MAX, and RES volume range, and ignore units with neither control. Add typed asynchronous and synchronous mute and volume APIs and demonstrate them in the host example. Signed-off-by: HiFiPHile <admin@hifiphile.com>
8324156 to
d0bbcad
Compare
Signed-off-by: HiFiPHile <admin@hifiphile.com>
d0bbcad to
1b53f8a
Compare
|
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 I'm planning to add feedback and UAC2 support. |
Signed-off-by: HiFiPHile <admin@hifiphile.com>
There was a problem hiding this comment.
🟡 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
Signed-off-by: HiFiPHile <admin@hifiphile.com>
Add TinyUSB Host Audio class driver supporting UAC 1.0 devices.
Features:
Changes:
Tested with Jabra USB headset (stereo speaker + mono microphone) on STM32F407 disco.