diff options
Diffstat (limited to 'docs/reference/class/audio.rst')
| -rw-r--r-- | docs/reference/class/audio.rst | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/docs/reference/class/audio.rst b/docs/reference/class/audio.rst new file mode 100644 index 000000000..6e86dff8c --- /dev/null +++ b/docs/reference/class/audio.rst @@ -0,0 +1,131 @@ +***** +Audio +***** + +Role: device only. TinyUSB supports USB Audio Class 1.0 and 2.0 streaming. +The descriptors define the topology, formats, channels, rates, controls, and +alternate settings; the application supplies or consumes the audio samples. + +Start from an example +===================== + +Audio descriptors and buffer sizes are tightly coupled. Copy the closest +example, confirm that it enumerates, and then change one property at a time: + +* :doc:`../../examples/device/audio_test` -- one-channel UAC2 microphone; +* :doc:`../../examples/device/audio_4_channel_mic` -- four-channel microphone; +* :doc:`../../examples/device/uac2_speaker_fb` -- speaker with feedback; +* :doc:`../../examples/device/uac2_headset` -- bidirectional headset; +* :doc:`../../examples/device/audio_test_multi_rate` -- UAC1 at full speed, + UAC2 at high speed, with multiple rates. + +Configuration +============= + +Set ``CFG_TUD_AUDIO`` to the number of audio functions. The principal options +are: + +.. list-table:: + :header-rows: 1 + :widths: 37 16 47 + + * - Option + - Default + - What it controls + * - ``CFG_TUD_AUDIO_CTRL_BUF_SZ`` + - ``64`` bytes + - Largest class control payload, such as a RANGE or channel-cluster + response. Increase it to fit the largest advertised control. + * - ``CFG_TUD_AUDIO_ENABLE_EP_IN`` + - ``0`` + - Enables microphone/device-to-host streaming. + * - ``CFG_TUD_AUDIO_ENABLE_EP_OUT`` + - ``0`` + - Enables speaker/host-to-device streaming. + * - ``CFG_TUD_AUDIO_FUNC_n_EP_IN_SZ_MAX`` / + ``CFG_TUD_AUDIO_FUNC_n_EP_OUT_SZ_MAX`` + - Required per enabled direction + - Maximum endpoint packet size across that function's alternate settings. + * - ``CFG_TUD_AUDIO_FUNC_n_EP_IN_SW_BUF_SZ`` / + ``CFG_TUD_AUDIO_FUNC_n_EP_OUT_SW_BUF_SZ`` + - ``0`` + - Software FIFO size. Set it to at least the corresponding maximum + endpoint size when using the FIFO APIs. + * - ``CFG_TUD_AUDIO_EP_IN_FLOW_CONTROL`` + - ``1`` + - Adapts IN packet consumption to the FIFO fill level to reduce + underruns/overruns. + * - ``CFG_TUD_AUDIO_ENABLE_FEEDBACK_EP`` + - ``0`` + - Enables an explicit feedback endpoint, normally required by an + asynchronous speaker. + * - ``CFG_TUD_AUDIO_ENABLE_INTERRUPT_EP`` + - ``0`` + - Enables the AudioControl interrupt endpoint for status notifications. + +For each enabled direction, define the maximum endpoint size used by any +advertised alternate setting, for example +``CFG_TUD_AUDIO_FUNC_1_EP_IN_SZ_MAX``. A software FIFO such as +``CFG_TUD_AUDIO_FUNC_1_EP_IN_SW_BUF_SZ`` must be at least that large. Use +``TUD_AUDIO_EP_SIZE()`` as the examples do; high-speed audio has more service +intervals per millisecond than full-speed audio. + +Data path +========= + +.. list-table:: + :header-rows: 1 + :widths: 34 66 + + * - Operation + - Main API + * - ``tud_audio_mounted()`` / ``tud_audio_version()`` + - Tests whether function zero is configured and returns its negotiated + Audio Class version. + * - ``tud_audio_available()`` / ``tud_audio_read()`` + - Reports and removes speaker bytes from the OUT software FIFO. The read + count can be shorter than requested. + * - ``tud_audio_write()`` + - Copies microphone bytes into the IN software FIFO and returns the number + accepted. + * - ``tud_audio_clear_ep_*_ff()`` + - Discards queued samples in the selected endpoint FIFO, useful when a + streaming alternate setting closes. + * - ``tud_audio_get_ep_*_ff()`` + - Returns the underlying FIFO object for advanced zero-copy or DMA + integration; the application must preserve its invariants. + * - ``tud_audio_n_fb_set()`` + - Supplies the feedback value for one audio function when application + feedback mode is used. Pass 16.16 samples per frame; TinyUSB converts + it to full-speed 10.14 format when required. + * - ``tud_audio_feedback_update()`` + - Updates internally calculated feedback from elapsed master-clock cycles + and returns the current 16.16 value, or zero on error. + * - ``tud_audio_n_*()`` + - Selects a function explicitly with ``func_id``; helpers without ``n`` + operate on function zero. + +The host starts and stops a stream by selecting interface alternate settings. +Use ``tud_audio_set_itf_cb()`` and ``tud_audio_set_itf_close_ep_cb()`` to start +or stop the application-side I2S/DMA path. Do not produce or consume samples +merely because the device is mounted; wait until the streaming interface is +active. + +Control requests +================ + +Implement the ``tud_audio_get_req_*_cb()`` and ``tud_audio_set_req_*_cb()`` +callbacks for every control advertised by the descriptors, such as clock +frequency, clock validity, mute, and volume. A descriptor that advertises a +control but stalls its normal requests is likely to be rejected or behave +poorly on a host. + +Asynchronous speakers normally need a feedback endpoint. Enable +``CFG_TUD_AUDIO_ENABLE_FEEDBACK_EP`` and either configure the feedback method +through ``tud_audio_feedback_params_cb()`` or provide feedback with +``tud_audio_n_fb_set()``. Begin with the speaker-feedback example; incorrect +feedback causes periodic underruns or overruns even when the nominal sample +rates match. + +Specifications used: *USB Device Class Definition for Audio Devices*, Release +1.0 and Release 2.0, plus *Audio Data Formats*, Release 2.0. |