.. include:: /keyword.rst

=====
Audio
=====

.. contents:: Sections
    :local:
    :depth: 3

.. toctree::
    :hidden:

    Genio 350-EVK <audio-i350-evk>
    Genio 510/700-EVK <audio-g700-evk>
    Genio 1200-EVK <audio-g1200-evk>

--------------------------------

This chapter describes the common information and instructions of Audio on |IOT-YOCTO|, such as listing the audio hardware, using a USB audio device, and so on.
Audio on different platforms may have some platform-specific instructions or test results.
For example, you will have different audio interfaces on different platforms.
Please refer to the platform-specific section for more details.

- :doc:`Genio 350-EVK Audio </sw/yocto/app-dev/audio/audio-i350-evk>`.
- :doc:`Genio 510/700-EVK Audio </sw/yocto/app-dev/audio/audio-g700-evk>`.
- :doc:`Genio 1200-EVK Audio </sw/yocto/app-dev/audio/audio-g1200-evk>`.

--------------------------------

ALSA
----

Audio System Overview
^^^^^^^^^^^^^^^^^^^^^

.. figure:: /_asset/sw_rity_app-dev_audio_evk_alsa-overview.svg
    :align: center
    :scale: 100%

    ALSA framework on Yocto Linux

- ALSA Application

    ALSA applications are audio software based on the Linux system, utilizing ALSA-provided drivers and libraries for sound recording, playback, and management.
    For detailed information, please refer to `ALSA Applications <https://www.alsa-project.org/main/index.php/Applications>`_.

- ALSA Library

    The ALSA library API is the interface to the ALSA drivers.
    For detailed information, please refer to `ALSA Library API <https://www.alsa-project.org/wiki/ALSA_Library_API>`_.

- ALSA Framework Layer

    This layer comprises the PCM interface, MIDI interface, and Control interface. Please refer to the
    links below for detailed information.

    - `PCM Interface <https://www.kernel.org/doc/html/v5.15/sound/kernel-api/writing-an-alsa-driver.html#pcm-interface>`_.
    - `Control Interface <https://www.kernel.org/doc/html/v5.15/sound/kernel-api/writing-an-alsa-driver.html#control-interface>`_.
    - `MIDI Interface <https://www.kernel.org/doc/html/v5.15/sound/kernel-api/writing-an-alsa-driver.html#midi-mpu401-uart-interface>`_.

- ASoC Framework Layer

    ASoC layer enhances audio support for embedded systems by enabling codec independence for driver
    reuse, simplifying I2S/PCM setup between codecs and SoCs, and providing DAPM for optimal power
    efficiency.
    For detailed information, please refer to `ASoC Layer <https://www.kernel.org/doc/html/v5.15/sound/soc/index.html>`_.

Hardware Driver
~~~~~~~~~~~~~~~

- Codec Driver

    For detailed information, please refer to `ASoC Codec Class Driver <https://www.kernel.org/doc/html/v5.15/sound/soc/codec.html>`_.

    - `MT6357 codec driver <https://gitlab.com/mediatek/aiot/bsp/linux/-/blob/mtk-v5.15-dev/sound/soc/codecs/mt6357.c?ref_type=heads>`_.

    - `MT6365 codec driver <https://gitlab.com/mediatek/aiot/bsp/linux/-/blob/mtk-v5.15-dev/sound/soc/codecs/mt6359.c?ref_type=heads>`_.

- Platform Driver

    For detailed information, please refer to `ASoC Platform Driver <https://www.kernel.org/doc/html/v5.15/sound/soc/platform.html>`_.

    - `MT8365 platform driver <https://gitlab.com/mediatek/aiot/bsp/linux/-/blob/mtk-v5.15-dev/sound/soc/mediatek/mt8365/mt8365-afe-pcm.c?ref_type=heads>`_.

    - `MT8370/MT8390 platform driver <https://gitlab.com/mediatek/aiot/bsp/linux/-/blob/mtk-v5.15-dev/sound/soc/mediatek/mt8188/mt8188-afe-pcm.c?ref_type=heads>`_.

    - `MT8395 platform driver <https://gitlab.com/mediatek/aiot/bsp/linux/-/blob/mtk-v5.15-dev/sound/soc/mediatek/mt8195/mt8195-afe-pcm.c?ref_type=heads>`_.

- Machine Driver

    For detailed information, please refer to `ASoC Machine Driver <https://www.kernel.org/doc/html/v5.15/sound/soc/machine.html>`_.

    - `Genio 350 machine driver <https://gitlab.com/mediatek/aiot/bsp/linux/-/blob/mtk-v5.15-dev/sound/soc/mediatek/mt8365/mt8365-evk.c?ref_type=heads>`_.

    - `Genio 510/700 machine driver <https://gitlab.com/mediatek/aiot/bsp/linux/-/blob/mtk-v5.15-dev/sound/soc/mediatek/mt8188/mt8390-evk.c?ref_type=heads>`_.
    
    - `Genio 1200 driver <https://gitlab.com/mediatek/aiot/bsp/linux/-/blob/mtk-v5.15-dev/sound/soc/mediatek/mt8195/mt8395-evk.c?ref_type=heads>`_.

For more ALSA information, please refer to `ALSA project <https://www.alsa-project.org/wiki/Main_Page>`_ and `ALSA unofficial wiki <https://alsa.opensrc.org/>`_.

ALSA Mixer Control
^^^^^^^^^^^^^^^^^^

ALSA mixer control is a component of the ALSA sound system in Linux that provides an interface for
adjusting sound settings on a software level. It allows users and applications to control the audio
hardware's mixer settings, such as volume levels, mute states, and other audio parameters that the
sound card's physical or software mixer supports.

Below are the tools for interacting with ALSA mixer controls.

- ``alsamixer``

  A text-based user interface tool that provides a visual representation of mixer controls. Users can 
  navigate through different controls and adjust them using keyboard commands.

- ``amixer``

  A command-line tool that allows users to modify mixer settings using command-line arguments. It is 
  useful for scripting and automation of audio settings.

- ``alsactl``

  A system utility for managing sound card settings. It can be used to save and restore mixer settings 
  across system reboots.

ALSA mixer controls are usually linked to specific components of the audio hardware. For instance, 
a sound card may feature distinct controls for headphone output and speaker output. Each control may 
contain one or more elements representing adjustable parameters, like volume sliders or mute/unmute 
switches. Each control element has a unique identifier (``ID``) that can be specified in the mixer 
command.

In the ALSA system, the mixer control names typically follow a naming convention that divides a control
name into three main components: **source**, **flow**, and **function**. 
This naming convention assists in clarifying the function and operation of sound card mixer controls, 
making it easier for users to understand and manipulate them. However, this is not mandatory. The sound
card manufacturers and driver developers might have their own styles.

.. table:: Mixer controls naming rules

  ========= =============================================================================================== ===================================================================================================================
  Component Description                                                                                     Common Example
  ========= =============================================================================================== ===================================================================================================================
  Source    Describes the origin of the audio signal. It usually identifies where the sound is coming from. ``Master``: The main volume control.
                                                                                                            
                                                                                                            ``PCM``: Digital audio signal, such as sound transmitted through the audio chip's PCM interface.
                                                                                                            
                                                                                                            ``Line``: Analog signal source, like a line input.
  Flow      Defines the direction of the audio signal flow related to the control.                          ``Playback``: Also known as output, it's the path of audio flowing to speakers or headphones.
                                                                                                            
                                                                                                            ``Capture``: Also known as input, it's the path of audio coming from microphones or other input sources being recorded.
                                                                                                            
                                                                                                            ``Bypass``: Typically refers to directing the input audio straight to the output without any processing.
  Function  Describes the control's action or purpose.                                                      ``Switch``: A toggle control used to mute or enable the corresponding audio path.
                                                                                                            
                                                                                                            ``Volume``: A volume control that increase or decrease the amplitude of the audio signal.
                                                                                                            
                                                                                                            ``Mux``: Multiplexer, often used to select one active input source among multiple audio sources.
  ========= =============================================================================================== ===================================================================================================================

Here are the examples on |G700-EVK|:

- ``Headset Volume``, ``Lineout Volume``: control the audio device's volume

- ``HDMI_OUT_MUX``, ``DPTX_OUT_MUX``: select the output device

- ``O176 I070 Switch``, ``O177 I071 Switch``: configure the audio data path

The ``asound.state`` file functions as a storage for ALSA's mixer control settings. It contains the 
current configurations or default values for all mixer controls on the sound card, enabling the system 
to restore these settings during boot or when a user wants to reload specific audio configurations.

Typically, the configuration syntax looks like this.

.. prompt:: bash # auto
    
    state.[CARD_NAME] {
        control.[CONTROL_NUM] {
            iface [INTERFACE_TYPE]
            name ['CONTROL_NAME']
            value [CONTROL_VALUE]
            comment {
                access ['ACCESS_TYPE']
                type ['VALUE_TYPE']
                count [COUNT]
                ...
            }
        }
        control.[ANOTHER_CONTROL_NUM] {
            ...
        }
        ...
    }

The elements here can be interpreted as:

- ``CARD_NAME``: Name or identifier of the sound card.

- ``CONTROL_NUM``: A unique numeric ID for the control.

- ``INTERFACE_TYPE``: Such as MIXER or PCM, indicating the type of interface the control is on.

- ``CONTROL_NAME``: The name of the control.

- ``CONTROL_VALUE``: The actual value set for the control, which might be numeric for volume controls or on/off for switches.

- ``ACCESS_TYPE``: The access permissions of the control, for example, read/write.

- ``VALUE_TYPE``: The type of value, for example, INTEGER, BOOLEAN, ENUMERATED.

- ``COUNT``: Indicates how many independent values the control has; for example, a stereo control would have two values, one for left and one for right, thus the count would be 2.

The image below shows the appearance of the 'Headset Volume' mixer control on |G700-EVK| in the ``asound.state`` file.

.. figure:: /_asset/sw_rity_app-dev_audio_evk_asound-state.svg
        :align: center
        :scale: 80%

        **Headset Volunme** mixer control

Mixer Control Usage Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- To view or modify the ``asound.state``:

    .. prompt:: bash # auto

        # cat /var/lib/alsa/asound.state

- To store the current mixer state in the ``/var/lib/alsa/asound.state`` configuration file.

    .. prompt:: bash # auto

        # alsactl store

- To restore the mixer state from the ``/var/lib/alsa/asound.state`` configuration file and to apply it to the system.

    .. prompt:: bash # auto

        # alsactl restore

Audio Interfaces
----------------

The audio system provides audio data exchange between the device and external audio components.
Audio interfaces play a crucial role in enabling high-quality sound recording and playback.
This section aims to offer a thorough guide to the integrated audio interface on the SoC. The `dai-link`
name is the name used by the software driver during integration.

The following table will show the interfaces present on the SoC MT8370/MT8390.

.. csv-table:: MT8370/MT8390 Audio Interfaces
    :file: /_asset/tables/audio-mt8390-interfaces.csv
    :width: 90%
    :header-rows: 1

The following table will show the interfaces present on the SoC MT8395.

.. csv-table:: MT8395 Audio Interfaces
    :file: /_asset/tables/audio-mt8395-interfaces.csv
    :width: 90%
    :header-rows: 1

MT6365 is a power management system chip optimized for handsets and smart phones. This codec is
used with the MT8370, MT8390, or MT8395 on the MediaTek platform. The following table will show the
interfaces present on the PMIC MT6365.

.. csv-table:: MT6365 Audio Interfaces
    :file: /_asset/tables/audio-mt6365-interfaces.csv
    :width: 90%
    :header-rows: 1

List Sound Devices
------------------

You can use ``aplay`` and ``arecord`` to list available sound devices.

.. note::

    The following commands will use |G700-EVK| as an example.

.. prompt:: bash # auto

    # aplay -l
    **** List of PLAYBACK Hardware Devices ****
    card 0: mt8390evk [mt8390-evk], device 0: DL2 Playback (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0
    card 0: mt8390evk [mt8390-evk], device 1: DL3 Playback (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0
    card 0: mt8390evk [mt8390-evk], device 2: DL6 Playback (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0
    card 0: mt8390evk [mt8390-evk], device 3: DL7 Playback (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0
    card 0: mt8390evk [mt8390-evk], device 4: DL8 Playback (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0
    card 0: mt8390evk [mt8390-evk], device 5: DL10 Playback (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0
    card 0: mt8390evk [mt8390-evk], device 6: DL11 Playback (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0

.. prompt:: bash # auto

    # arecord -l
    **** List of CAPTURE Hardware Devices ****
    card 0: mt8390evk [mt8390-evk], device 7: UL1 Capture (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0
    card 0: mt8390evk [mt8390-evk], device 8: UL2 Capture (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0
    card 0: mt8390evk [mt8390-evk], device 9: UL3 Capture (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0
    card 0: mt8390evk [mt8390-evk], device 10: UL4 Capture (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0
    card 0: mt8390evk [mt8390-evk], device 11: UL5 Capture (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0
    card 0: mt8390evk [mt8390-evk], device 12: UL6 Capture (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0
    card 0: mt8390evk [mt8390-evk], device 13: UL8 Capture (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0
    card 0: mt8390evk [mt8390-evk], device 14: UL9 Capture (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0
    card 0: mt8390evk [mt8390-evk], device 15: UL10 Capture (*) []
      Subdevices: 1/1
      Subdevice #0: subdevice #0

You can find the corresponding device nodes under ``/dev/snd/``.

.. prompt:: bash # auto

    # ls -l /dev/snd
    total 0
    drwxr-xr-x 2 root root       60 Apr 28 18:24 by-path
    crw-rw---- 1 root audio 116, 18 Apr 28 18:24 controlC0
    crw-rw---- 1 root audio 116,  2 Apr 28 18:24 pcmC0D0p
    crw-rw---- 1 root audio 116, 12 Apr 28 18:24 pcmC0D10c
    crw-rw---- 1 root audio 116, 13 Apr 28 18:24 pcmC0D11c
    crw-rw---- 1 root audio 116, 14 Apr 28 18:24 pcmC0D12c
    crw-rw---- 1 root audio 116, 15 Apr 28 18:24 pcmC0D13c
    crw-rw---- 1 root audio 116, 16 Apr 28 18:24 pcmC0D14c
    crw-rw---- 1 root audio 116, 17 Apr 28 18:24 pcmC0D15c
    crw-rw---- 1 root audio 116,  3 Apr 28 18:24 pcmC0D1p
    crw-rw---- 1 root audio 116,  4 Apr 28 18:24 pcmC0D2p
    crw-rw---- 1 root audio 116,  5 Apr 28 18:24 pcmC0D3p
    crw-rw---- 1 root audio 116,  6 Apr 28 18:24 pcmC0D4p
    crw-rw---- 1 root audio 116,  7 Apr 28 18:24 pcmC0D5p
    crw-rw---- 1 root audio 116,  8 Apr 28 18:24 pcmC0D6p
    crw-rw---- 1 root audio 116,  9 Apr 28 18:24 pcmC0D7c
    crw-rw---- 1 root audio 116, 10 Apr 28 18:24 pcmC0D8c
    crw-rw---- 1 root audio 116, 11 Apr 28 18:24 pcmC0D9c
    crw-rw---- 1 root audio 116, 33 Apr 28 18:24 timer

There are some default plugin devices specified in ``/etc/asound.conf``. Please refer to `Asoundrc <https://www.alsa-project.org/wiki/Asoundrc>`_ for more details.
For example, the following configuration creates an alias name, ``jack_speaker``, which represents ``/dev/pcmC0D0p``.
Then, you can play the music with the name ``jack_speaker`` by ``aplay -D jack_speaker``.

.. code-block::

    pcm.jack_speaker {
           type plug
           slave {
                   pcm "hw:mt8390evk,0,0"
                   channels 2
           }
    }

For examples of playback and capture, please refer to each platform section.

USB Audio
---------

On the IoT platform, it supports USB audio.
You can simply plug in a USB audio device (e.g. USB headset) and check its ID and name before playing or recording something.

.. prompt:: bash # auto

    # aplay -l
    **** List of PLAYBACK Hardware Devices ****
    card 1: H540 [Logitech USB Headset H540], device 0: USB Audio [USB Audio]
      Subdevices: 1/1
      Subdevice #0: subdevice #0

.. prompt:: bash # auto

    # arecord -l
    **** List of CAPTURE Hardware Devices ****
    card 1: H540 [Logitech USB Headset H540], device 0: USB Audio [USB Audio]
      Subdevices: 1/1
      Subdevice #0: subdevice #0

You can see there is ``card 1`` with the CAPTURE device and the PLAYBACK device.

To play the music:

.. prompt:: bash # auto

    # aplay -D hw:1,0 sample.wav

To record the voice:

.. prompt:: bash # auto

    # arecord -D hw:1,0 -r 48000 -f S16_LE -c 2 sample.wav

Loopback Test
-------------

There's a loopback audio test that directly transfers the input voice to the output audio.

For instance, you can use it to transfer sound from the Earphone-In Jack to the Earphone-Out Jack.

.. prompt:: bash # auto

    # arecord -D jack_mic -r 48000 -f S32_LE | aplay -D jack_speaker -r 48000 -f S32_LE