Audio input과 output

물리 audio connector

Audio input과 output은 device의 물리 connector입니다. Video capture device는 input을, output device는 output을 가지며 각각 0개 이상일 수 있습니다.

Radio device에는 audio input이나 output이 없습니다. 정확히 하나의 tuner가 있고 실제로 audio source이지만, 이 API는 tuner를 video input 또는 output에만 연결하며 radio device에는 둘 다 없기 때문입니다.

TV card에서 수신 audio signal을 sound card로 loop back하는 connector는 audio output으로 간주하지 않습니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _audio:

************************
Audio Inputs and Outputs
************************

Audio inputs and outputs are physical connectors of a device. Video
capture devices have inputs, output devices have outputs, zero or more
each. Radio devices have no audio inputs or outputs. They have exactly
one tuner which in fact *is* an audio source, but this API associates
tuners with video inputs or outputs only, and radio devices have none of
these. [#f1]_ A connector on a TV card to loop back the received audio
signal to a sound card is not considered an audio output.

Video와 audio connector의 연결

Audio input/output은 video input/output과 연결됩니다. Video source를 선택하면 audio source도 함께 선택되며, video와 audio source가 tuner일 때 이 관계가 가장 분명합니다.

하나의 audio connector가 둘 이상의 video input 또는 output과 조합될 수도 있습니다. Composite video input 2개와 audio input 2개가 있다면 유효한 조합은 최대 4개입니다.

Video와 audio connector의 관계는 각각의 `struct v4l2_input` 또는 `struct v4l2_output`에 있는 `audioset` field로 정의됩니다. 각 bit는 0부터 시작하는 audio input 또는 output index 하나를 나타냅니다.

Audio and video inputs and outputs are associated. Selecting a video
source also selects an audio source. This is most evident when the video
and audio source is a tuner. Further audio connectors can combine with
more than one video input or output. Assumed two composite video inputs
and two audio inputs exist, there may be up to four valid combinations.
The relation of video and audio connectors is defined in the
``audioset`` field of the respective struct
:c:type:`v4l2_input` or struct
:c:type:`v4l2_output`, where each bit represents the index
number, starting at zero, of one audio input or output.

Audio connector 열거와 현재 선택 조회

Application은 `VIDIOC_ENUMAUDIO`와 `VIDIOC_ENUMAUDOUT` ioctl로 사용 가능한 audio input과 output의 수 및 속성을 각각 열거할 수 있습니다.

`VIDIOC_ENUMAUDIO`가 반환하는 `struct v4l2_audio`에는 현재 audio input을 조회할 때 적용되는 signal status 정보도 포함됩니다.

`VIDIOC_G_AUDIO`와 `VIDIOC_G_AUDOUT` ioctl은 현재 audio input과 output을 각각 보고합니다.

To learn about the number and attributes of the available inputs and
outputs applications can enumerate them with the
:ref:`VIDIOC_ENUMAUDIO` and
:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` ioctl, respectively.
The struct :c:type:`v4l2_audio` returned by the
:ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal
status information applicable when the current audio input is queried.

The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
:ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` ioctls report the current
audio input and output, respectively.

구조체 반환과 audio connector 선택

`VIDIOC_G_INPUT` 및 `VIDIOC_G_OUTPUT`과 달리 `VIDIOC_G_AUDIO`와 `VIDIOC_G_AUDOUT`은 index 하나가 아니라 `VIDIOC_ENUMAUDIO` 및 `VIDIOC_ENUMAUDOUT`과 같은 구조체를 반환합니다.

Audio input을 선택하고 속성을 변경하려면 `VIDIOC_S_AUDIO`를 호출합니다. 현재 변경 가능한 속성이 없는 audio output을 선택하려면 `VIDIOC_S_AUDOUT`을 호출합니다.

.. note::

   Note that, unlike :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
   :ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a
   structure as :ref:`VIDIOC_ENUMAUDIO` and
   :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` do, not just an index.

To select an audio input and change its properties applications call the
:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. To select an audio
output (which presently has no changeable properties) applications call
the :ref:`VIDIOC_S_AUDOUT <VIDIOC_G_AUDOUT>` ioctl.

Driver 구현 및 capability 요구사항

Device에 선택 가능한 audio input이 여러 개 있으면 driver는 모든 audio input ioctl을 구현해야 합니다. 선택 가능한 audio output이 여러 개 있으면 모든 audio output ioctl을 구현해야 합니다.

Device에 audio input 또는 output이 하나라도 있으면 `VIDIOC_QUERYCAP`이 반환하는 `struct v4l2_capability`에 `V4L2_CAP_AUDIO` flag를 설정해야 합니다.

Drivers must implement all audio input ioctls when the device has
multiple selectable audio inputs, all audio output ioctls when the
device has multiple selectable audio outputs. When the device has any
audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag
in the struct :c:type:`v4l2_capability` returned by
the :ref:`VIDIOC_QUERYCAP` ioctl.

현재 audio input 정보 예제

다음 C code는 `struct v4l2_audio`를 0으로 초기화하고 `VIDIOC_G_AUDIO`로 현재 input을 조회한 뒤 이름을 출력합니다.

struct v4l2_audio audio;

memset(&audio, 0, sizeof(audio));

if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) {
	perror("VIDIOC_G_AUDIO");
	exit(EXIT_FAILURE);
}

printf("Current input: %s\n", audio.name);

Example: Information about the current audio input
==================================================

.. code-block:: c

    struct v4l2_audio audio;

    memset(&audio, 0, sizeof(audio));

    if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) {
	perror("VIDIOC_G_AUDIO");
	exit(EXIT_FAILURE);
    }

    printf("Current input: %s\\n", audio.name);

첫 번째 audio input으로 전환하는 예제

다음 C code는 구조체를 초기화해 `audio.mode`와 `audio.reserved`도 지우고 `audio.index = 0`으로 설정한 뒤 `VIDIOC_S_AUDIO`를 호출합니다.

struct v4l2_audio audio;

memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */

audio.index = 0;

if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) {
	perror("VIDIOC_S_AUDIO");
	exit(EXIT_FAILURE);
}

Example: Switching to the first audio input
===========================================

.. code-block:: c

    struct v4l2_audio audio;

    memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */

    audio.index = 0;

    if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) {
	perror("VIDIOC_S_AUDIO");
	exit(EXIT_FAILURE);
    }

Radio tuner 표현에 관한 API 주석

실제로는 `struct v4l2_audio`에도 `struct v4l2_input`처럼 `tuner` field가 있어야 합니다. 그러면 API가 더 일관될 뿐 아니라 tuner가 여러 개인 radio device도 표현할 수 있습니다.

.. [#f1]
   Actually struct :c:type:`v4l2_audio` ought to have a
   ``tuner`` field like struct :c:type:`v4l2_input`, not
   only making the API more consistent but also permitting radio devices
   with multiple tuners.