DVB Audio Device

DVB audio 장치와 사용 중단 경고

DVB audio 장치는 DVB 하드웨어의 MPEG-2 audio decoder를 제어하며 `/dev/dvb/adapter?/audio?`를 통해 접근합니다. 응용 프로그램에서 `linux/dvb/audio.h`를 포함하면 data type과 ioctl 정의를 사용할 수 있습니다.

새 드라이버에서는 이 API를 사용하면 안 됩니다. 대부분의 DVB card에는 자체 MPEG decoder가 없어 audio와 video device node 자체가 생략됩니다.

이 ioctl들은 한때 V4L2의 MPEG decoder 제어에도 쓰였지만 그 용도는 폐기됐습니다. 새 V4L2 드라이버는 대체 V4L2 ioctl 또는 control을 사용해야 합니다.

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

.. c:namespace:: dtv.legacy.audio

.. _dvb_audio:

================
DVB Audio Device
================

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

The DVB audio device controls the MPEG2 audio decoder of the DVB
hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data
types and ioctl definitions can be accessed by including
``linux/dvb/audio.h`` in your application.

Please note that most DVB cards don’t have their own MPEG decoder, which
results in the omission of the audio and video device.

These ioctls were also used by V4L2 to control MPEG decoders implemented
in V4L2. The use of these ioctls for that purpose has been made obsolete
and proper V4L2 ioctls or controls have been created to replace that
functionality. Use :ref:`V4L2 ioctls<audio>` for new drivers!


Audio Data Types
================

This section describes the structures, data types and defines used when
talking to the audio device.

audio_stream_source_t 입력원

`audio_stream_source_t`는 `AUDIO_SELECT_SOURCE`가 audio stream을 내부 demux에서 받을지, 사용자 공간의 `write()` 호출에서 받을지 정합니다.

Decoder로 들어가는 데이터는 PID filter의 제어도 받습니다. demux 출력은 `dmx_output`의 `DMX_OUT_DECODER`를 선택합니다.

-----


audio_stream_source_t
---------------------

Synopsis
~~~~~~~~

.. c:enum:: audio_stream_source_t

.. code-block:: c

    typedef enum {
    AUDIO_SOURCE_DEMUX,
    AUDIO_SOURCE_MEMORY
    } audio_stream_source_t;

Constants
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``AUDIO_SOURCE_DEMUX``

       -  :cspan:`1` Selects the demultiplexer (fed either by the frontend
          or the DVR device) as the source of the video stream.

    -  ..

       -  ``AUDIO_SOURCE_MEMORY``

       -  Selects the stream from the application that comes through
          the `write()`_ system call.

Description
~~~~~~~~~~~

The audio stream source is set through the `AUDIO_SELECT_SOURCE`_ call
and can take the following values, depending on whether we are replaying
from an internal (demux) or external (user write) source.

The data fed to the decoder is also controlled by the PID-filter.
Output selection: :c:type:`dmx_output` ``DMX_OUT_DECODER``.

audio_play_state_t 재생 상태

`audio_play_state_t`는 `AUDIO_GET_STATUS`가 반환하는 현재 audio 재생 상태입니다.

원문 C 선언은 `AUDIO_PAUSED`를 정의하지만 바로 아래 상수 표는 `AUDIO_PAUSE`라고 적습니다. 번역은 선언의 실제 symbol을 기준으로 설명하되 원문 표기는 수정하지 않았습니다.

-----


audio_play_state_t
------------------

Synopsis
~~~~~~~~

.. c:enum:: audio_play_state_t

.. code-block:: c

    typedef enum {
	AUDIO_STOPPED,
	AUDIO_PLAYING,
	AUDIO_PAUSED
    } audio_play_state_t;

Constants
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``AUDIO_STOPPED``

       -  Audio is stopped.

    -  ..

       -  ``AUDIO_PLAYING``

       -  Audio is currently playing.

    -  ..

       -  ``AUDIO_PAUSE``

       -  Audio is frozen.

Description
~~~~~~~~~~~

This values can be returned by the `AUDIO_GET_STATUS`_ call
representing the state of audio playback.

audio_channel_select_t 출력 채널

`audio_channel_select_t`는 `AUDIO_CHANNEL_SELECT`가 선택할 audio 출력 채널 형식을 지정합니다.

-----


audio_channel_select_t
----------------------

Synopsis
~~~~~~~~

.. c:enum:: audio_channel_select_t

.. code-block:: c

    typedef enum {
	AUDIO_STEREO,
	AUDIO_MONO_LEFT,
	AUDIO_MONO_RIGHT,
	AUDIO_MONO,
	AUDIO_STEREO_SWAPPED
    } audio_channel_select_t;

Constants
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``AUDIO_STEREO``

       -  Stereo.

    -  ..

       -  ``AUDIO_MONO_LEFT``

       -  Mono, select left stereo channel as source.

    -  ..

       -  ``AUDIO_MONO_RIGHT``

       -  Mono, select right stereo channel as source.

    -  ..

       -  ``AUDIO_MONO``

       -  Mono source only.

    -  ..

       -  ``AUDIO_STEREO_SWAPPED``

       -  Stereo, swap L & R.

Description
~~~~~~~~~~~

The audio channel selected via `AUDIO_CHANNEL_SELECT`_ is determined by
this value.

audio_mixer_t 음량

`audio_mixer_t`는 `AUDIO_SET_MIXER`에 전달해 audio decoder의 왼쪽·오른쪽 음량을 설정하는 구조체입니다.

-----


audio_mixer_t
-------------

Synopsis
~~~~~~~~

.. c:struct:: audio_mixer

.. code-block:: c

    typedef struct audio_mixer {
	unsigned int volume_left;
	unsigned int volume_right;
    } audio_mixer_t;

Variables
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``unsigned int volume_left``

       -  Volume left channel.
          Valid range: 0 ... 255

    -  ..

       -  ``unsigned int volume_right``

       -  Volume right channel.
          Valid range: 0 ... 255

Description
~~~~~~~~~~~

This structure is used by the `AUDIO_SET_MIXER`_ call to set the
audio volume.

audio_status 재생 상태 묶음

`audio_status_t`는 `AUDIO_GET_STATUS`가 반환하는 재생 동작의 종합 상태입니다.

-----


audio_status
------------

Synopsis
~~~~~~~~

.. c:struct:: audio_status

.. code-block:: c

    typedef struct audio_status {
	int AV_sync_state;
	int mute_state;
	audio_play_state_t play_state;
	audio_stream_source_t stream_source;
	audio_channel_select_t channel_select;
	int bypass_mode;
	audio_mixer_t mixer_state;
    } audio_status_t;

Variables
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  :rspan:`2` ``int AV_sync_state``

       -  :cspan:`1` Shows if A/V synchronization is ON or OFF.

    -  ..

       -  TRUE  ( != 0 )

       -  AV-sync ON.

    -  ..

       -  FALSE ( == 0 )

       -  AV-sync OFF.

    -  ..

       -  :rspan:`2` ``int mute_state``

       -  :cspan:`1` Indicates if audio is muted or not.

    -  ..

       -  TRUE  ( != 0 )

       -  mute audio

    -  ..

       -  FALSE ( == 0 )

       -  unmute audio

    -  ..

       -  `audio_play_state_t`_ ``play_state``

       -  Current playback state.

    -  ..

       -  `audio_stream_source_t`_ ``stream_source``

       -  Current source of the data.

    -  ..

       -  :rspan:`2` ``int bypass_mode``

       -  :cspan:`1` Is the decoding of the current Audio stream in
          the DVB subsystem enabled or disabled.

    -  ..

       -  TRUE  ( != 0 )

       -  Bypass disabled.

    -  ..

       -  FALSE ( == 0 )

       -  Bypass enabled.

    -  ..

       -  `audio_mixer_t`_ ``mixer_state``

       -  Current volume settings.

Description
~~~~~~~~~~~

The `AUDIO_GET_STATUS`_ call returns this structure as information
about various states of the playback operation.

Audio encoding capability bit

`AUDIO_GET_CAPABILITIES`는 하드웨어가 받아들일 수 있는 audio format을 unsigned integer bit mask로 반환합니다.

여러 format을 지원하면 대응하는 bit들이 함께 설정됩니다.

-----


audio encodings
---------------

Synopsis
~~~~~~~~

.. code-block:: c

     #define AUDIO_CAP_DTS    1
     #define AUDIO_CAP_LPCM   2
     #define AUDIO_CAP_MP1    4
     #define AUDIO_CAP_MP2    8
     #define AUDIO_CAP_MP3   16
     #define AUDIO_CAP_AAC   32
     #define AUDIO_CAP_OGG   64
     #define AUDIO_CAP_SDDS 128
     #define AUDIO_CAP_AC3  256

Constants
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``AUDIO_CAP_DTS``

       -  :cspan:`1` The hardware accepts DTS audio tracks.

    -  ..

       -  ``AUDIO_CAP_LPCM``

       -   The hardware accepts uncompressed audio with
           Linear Pulse-Code Modulation (LPCM)

    -  ..

       -  ``AUDIO_CAP_MP1``

       -  The hardware accepts MPEG-1 Audio Layer 1.

    -  ..

       -  ``AUDIO_CAP_MP2``

       -  The hardware accepts MPEG-1 Audio Layer 2.
          Also known as MUSICAM.

    -  ..

       -  ``AUDIO_CAP_MP3``

       -  The hardware accepts MPEG-1 Audio Layer III.
          Commonly known as .mp3.

    -  ..

       -  ``AUDIO_CAP_AAC``

       -  The hardware accepts AAC (Advanced Audio Coding).

    -  ..

       -  ``AUDIO_CAP_OGG``

       -  The hardware accepts Vorbis audio tracks.

    -  ..

       -  ``AUDIO_CAP_SDDS``

       -  The hardware accepts Sony Dynamic Digital Sound (SDDS).

    -  ..

       -  ``AUDIO_CAP_AC3``

       -  The hardware accepts Dolby Digital ATSC A/52 audio.
          Also known as AC-3.

Description
~~~~~~~~~~~

A call to `AUDIO_GET_CAPABILITIES`_ returns an unsigned integer with the
following bits set according to the hardwares capabilities.

AUDIO_STOP

`ioctl(fd, AUDIO_STOP)`은 현재 stream 재생을 멈추도록 Audio Device에 요청합니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

-----


Audio Function Calls
====================


AUDIO_STOP
----------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_STOP

.. code-block:: c

	 int ioctl(int fd, int request = AUDIO_STOP)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  File descriptor returned by a previous call to `open()`_.

    -  ..

       -  ``int request``

       -  :cspan:`1` Equals ``AUDIO_STOP`` for this command.

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl call asks the Audio Device to stop playing the current
stream.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

AUDIO_PLAY

`ioctl(fd, AUDIO_PLAY)`는 선택한 source에서 audio stream 재생을 시작하도록 요청합니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_PLAY
----------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_PLAY

.. code-block:: c

	 int  ioctl(int fd, int request = AUDIO_PLAY)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  File descriptor returned by a previous call to `open()`_.

    -  ..

       -  ``int request``

       -  :cspan:`1` Equals ``AUDIO_PLAY`` for this command.

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl call asks the Audio Device to start playing an audio stream
from the selected source.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

AUDIO_PAUSE

`ioctl(fd, AUDIO_PAUSE)`는 재생 중인 audio stream의 decoding과 재생을 함께 일시 정지합니다. 이후 `AUDIO_CONTINUE`로 같은 과정을 다시 시작할 수 있습니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_PAUSE
-----------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_PAUSE

.. code-block:: c

	 int  ioctl(int fd, int request = AUDIO_PAUSE)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``int request``

       -  Equals ``AUDIO_PAUSE`` for this command.

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl call suspends the audio stream being played. Decoding and
playing are paused. It is then possible to restart again decoding and
playing process of the audio stream using `AUDIO_CONTINUE`_ command.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

AUDIO_CONTINUE

`ioctl(fd, AUDIO_CONTINUE)`는 앞서 `AUDIO_PAUSE`로 멈춘 decoding과 재생을 재개합니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_CONTINUE
--------------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_CONTINUE

.. code-block:: c

	 int  ioctl(int fd, int request = AUDIO_CONTINUE)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``int request``

       -  Equals ``AUDIO_CONTINUE`` for this command.

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl restarts the decoding and playing process previously paused
with `AUDIO_PAUSE`_ command.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

AUDIO_SELECT_SOURCE

`AUDIO_SELECT_SOURCE`는 Audio Device의 입력 데이터를 demux 또는 응용 프로그램 memory 중 어디서 받을지 지정합니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_SELECT_SOURCE
-------------------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_SELECT_SOURCE

.. code-block:: c

	 int ioctl(int fd, int request = AUDIO_SELECT_SOURCE,
	 audio_stream_source_t source)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``int request``

       -  Equals ``AUDIO_SELECT_SOURCE`` for this command.

    -  ..

       -  `audio_stream_source_t`_ ``source``

       -  Indicates the source that shall be used for the Audio stream.

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl call informs the audio device which source shall be used for
the input data. The possible sources are demux or memory. If
``AUDIO_SOURCE_MEMORY`` is selected, the data is fed to the Audio Device
through the write command. If ``AUDIO_SOURCE_DEMUX`` is selected, the data
is directly transferred from the onboard demux-device to the decoder.
Note: This only supports DVB-devices with one demux and one decoder so far.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

AUDIO_SET_MUTE

`AUDIO_SET_MUTE`는 현재 재생 중인 stream의 audio를 mute하거나 다시 들리게 합니다. 이 ioctl은 DVB 장치 전용입니다.

V4L2 decoder는 대신 `VIDIOC_DECODER_CMD`와 `V4L2_DEC_CMD_START_MUTE_AUDIO` flag를 사용합니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_SET_MUTE
--------------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_SET_MUTE

.. code-block:: c

	 int  ioctl(int fd, int request = AUDIO_SET_MUTE, int state)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``int request``

       -  :cspan:`1` Equals ``AUDIO_SET_MUTE`` for this command.

    -  ..

       -  :rspan:`2` ``int state``

       -  :cspan:`1` Indicates if audio device shall mute or not.

    -  ..

       -  TRUE  ( != 0 )

       -  mute audio

    -  ..

       -  FALSE ( == 0 )

       -  unmute audio

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl is for DVB devices only. To control a V4L2 decoder use the
V4L2 :ref:`VIDIOC_DECODER_CMD` with the
``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead.

This ioctl call asks the audio device to mute the stream that is
currently being played.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

AUDIO_SET_AV_SYNC

`AUDIO_SET_AV_SYNC`는 Audio Device의 A/V synchronization을 켜거나 끕니다.

원문 인자 표는 request가 `AUDIO_AV_SYNC`와 같다고 적지만 synopsis의 실제 명령은 `AUDIO_SET_AV_SYNC`입니다. 원문 불일치는 보존했습니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_SET_AV_SYNC
-----------------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_SET_AV_SYNC

.. code-block:: c

	 int  ioctl(int fd, int request = AUDIO_SET_AV_SYNC, int state)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``int request``

       -  :cspan:`1` Equals ``AUDIO_AV_SYNC`` for this command.

    -  ..

       -  :rspan:`2` ``int state``

       -  :cspan:`1` Tells the DVB subsystem if A/V synchronization
          shall be ON or OFF.

    -  ..

       -  TRUE  ( != 0 )

       -  AV-sync ON.

    -  ..

       -  FALSE ( == 0 )

       -  AV-sync OFF.

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl call asks the Audio Device to turn ON or OFF A/V
synchronization.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

AUDIO_SET_BYPASS_MODE

`AUDIO_SET_BYPASS_MODE`는 DVB audio decoder를 우회해 stream을 decoding하지 않고 전달할지 정합니다. DVB subsystem이 처리할 수 없는 stream을 외부 decoder로 보낼 때 사용합니다.

하드웨어가 Dolby Digital stream을 처리할 수 있으면 DVB subsystem이 자동으로 전달합니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_SET_BYPASS_MODE
---------------------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_SET_BYPASS_MODE

.. code-block:: c

	 int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, int mode)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``int request``

       -  :cspan:`1` Equals ``AUDIO_SET_BYPASS_MODE`` for this command.

    -  ..

       -  :rspan:`2` ``int mode``

       -  :cspan:`1` Enables or disables the decoding of the current
          Audio stream in the DVB subsystem.
    -  ..

       -  TRUE  ( != 0 )

       -  Disable bypass

    -  ..

       -  FALSE ( == 0 )

       -  Enable bypass

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl call asks the Audio Device to bypass the Audio decoder and
forward the stream without decoding. This mode shall be used if streams
that can’t be handled by the DVB system shall be decoded. Dolby
DigitalTM streams are automatically forwarded by the DVB subsystem if
the hardware can handle it.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

AUDIO_CHANNEL_SELECT

`AUDIO_CHANNEL_SELECT`는 가능한 경우 mono left, mono right, stereo 등 요청한 audio 출력 채널을 선택합니다. DVB 장치 전용 ioctl입니다.

V4L2 decoder는 대신 `V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK` control을 사용합니다. 원문 synopsis에는 세 번째 인자의 변수명이 없지만 인자 표에서는 `ch`라고 부릅니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_CHANNEL_SELECT
--------------------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_CHANNEL_SELECT

.. code-block:: c

	 int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT,
	 audio_channel_select_t)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``int request``

       -  Equals ``AUDIO_CHANNEL_SELECT`` for this command.

    -  ..

       -  `audio_channel_select_t`_ ``ch``

       -  Select the output format of the audio (mono left/right, stereo).

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl is for DVB devices only. To control a V4L2 decoder use the
V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead.

This ioctl call asks the Audio Device to select the requested channel if
possible.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

AUDIO_GET_STATUS

`AUDIO_GET_STATUS`는 Audio Device의 현재 상태를 `struct audio_status`에 채워 반환합니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_GET_STATUS
----------------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_GET_STATUS

.. code-block:: c

	 int ioctl(int fd, int request = AUDIO_GET_STATUS,
	 struct audio_status *status)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``int request``

       -  Equals AUDIO_GET_STATUS for this command.

    -  ..

       -  ``struct`` `audio_status`_ ``*status``

       -  Returns the current state of Audio Device.

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl call asks the Audio Device to return the current state of the
Audio Device.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

AUDIO_GET_CAPABILITIES

`AUDIO_GET_CAPABILITIES`는 audio 하드웨어가 decoding할 수 있는 sound format을 bit array로 조회합니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_GET_CAPABILITIES
----------------------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_GET_CAPABILITIES

.. code-block:: c

	 int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES,
	 unsigned int *cap)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``int request``

       -  Equals ``AUDIO_GET_CAPABILITIES`` for this command.

    -  ..

       -  ``unsigned int *cap``

       -  Returns a bit array of supported sound formats.
          Bits are defined in `audio encodings`_.

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl call asks the Audio Device to tell us about the decoding
capabilities of the audio hardware.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

AUDIO_CLEAR_BUFFER

`AUDIO_CLEAR_BUFFER`는 audio decoder 장치의 software buffer와 hardware buffer를 모두 비우도록 요청합니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_CLEAR_BUFFER
------------------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_CLEAR_BUFFER

.. code-block:: c

	 int  ioctl(int fd, int request = AUDIO_CLEAR_BUFFER)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``int request``

       -  Equals ``AUDIO_CLEAR_BUFFER`` for this command.

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl call asks the Audio Device to clear all software and hardware
buffers of the audio decoder device.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

AUDIO_SET_ID

`AUDIO_SET_ID`는 program 또는 system stream에 여러 audio sub-stream이 있을 때 decoding할 sub-stream id를 선택합니다.

범위 정의는 ITU-T H.222.0 | ISO/IEC 13818-1을 따릅니다. 원문은 stream이 `video device`로 전송된다고 표현하며, 이 문구도 원문 블록에 그대로 보존했습니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_SET_ID
------------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_SET_ID

.. code-block:: c

	 int  ioctl(int fd, int request = AUDIO_SET_ID, int id)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``int request``

       -  Equals ``AUDIO_SET_ID`` for this command.

    -  ..

       -  ``int id``

       -  Audio sub-stream id.

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl selects which sub-stream is to be decoded if a program or
system stream is sent to the video device.

If no audio stream type is set the id has to be in range [0xC0,0xDF]
for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7] for LPCM.
See ITU-T H.222.0 | ISO/IEC 13818-1 for further description.

If the stream type is set with `AUDIO_SET_STREAMTYPE`_, specifies the
id just the sub-stream id of the audio stream and only the first 5 bits
(& 0x1F) are recognized.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

AUDIO_SET_MIXER

`AUDIO_SET_MIXER`는 `audio_mixer_t` 구조체로 audio decoder의 왼쪽·오른쪽 mixer 음량을 조정합니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_SET_MIXER
---------------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_SET_MIXER

.. code-block:: c

	 int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``int request``

       -  Equals ``AUDIO_SET_MIXER`` for this command.

    -  ..

       -  ``audio_mixer_t *mix``

       -  Mixer settings.

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl lets you adjust the mixer settings of the audio decoder.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

AUDIO_SET_STREAMTYPE

`AUDIO_SET_STREAMTYPE`은 driver가 어떤 종류의 audio stream을 받게 될지 알려 줍니다. LPCM과 AC-3처럼 여러 audio sub-stream을 제공하는 stream에서 유용합니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_SET_STREAMTYPE
--------------------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_SET_STREAMTYPE

.. code-block:: c

	 int  ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``int request``

       -  Equals ``AUDIO_SET_STREAMTYPE`` for this command.

    -  ..

       -  ``int type``

       -  Stream type.

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl tells the driver which kind of audio stream to expect. This
is useful if the stream offers several audio sub-streams like LPCM and
AC3.

Stream types defined in ITU-T H.222.0 | ISO/IEC 13818-1 are used.


Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``EINVAL``

       -  Type is not a valid or supported stream type.


-----

AUDIO_BILINGUAL_CHANNEL_SELECT

`AUDIO_BILINGUAL_CHANNEL_SELECT`는 bilingual stream에서 가능한 경우 요청한 mono left, mono right 또는 stereo 채널을 선택합니다.

V4L2로 제어하는 MPEG decoder에서는 이 ioctl이 `V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK` control로 대체됐습니다.

주의: 이 legacy ioctl은 새 드라이버에서 사용하면 안 됩니다. 새 구현은 해당 기능의 V4L2 ioctl 또는 control을 사용해야 합니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정하며, 공통 오류 의미는 Generic Error Codes 절을 따릅니다.

AUDIO_BILINGUAL_CHANNEL_SELECT
------------------------------

Synopsis
~~~~~~~~

.. c:macro:: AUDIO_BILINGUAL_CHANNEL_SELECT

.. code-block:: c

	 int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT,
	 audio_channel_select_t)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``int request``

       -  Equals ``AUDIO_BILINGUAL_CHANNEL_SELECT`` for this command.

    -  ..

       -  ``audio_channel_select_t ch``

       -  Select the output format of the audio (mono left/right, stereo).

Description
~~~~~~~~~~~

.. attention:: Do **not** use in new drivers!
             See: :ref:`legacy_dvb_decoder_notes`

This ioctl has been replaced by the V4L2
``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control
for MPEG decoders controlled through V4L2.

This ioctl call asks the Audio Device to select the requested channel
for bilingual streams if possible.

Return Value
~~~~~~~~~~~~

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


-----

open() 장치 열기

`open()`은 `/dev/dvb/adapter0/audio0` 같은 audio device를 열어 이후 호출에 사용할 file descriptor를 얻습니다. blocking 여부는 `open()` 자체의 의미를 바꾸지 않으며, 나중에 `fcntl(F_SETFL)`로 전환할 수 있습니다.

`O_RDWR`로는 한 사용자만 Audio Device를 열 수 있습니다. 다른 `O_RDWR` open은 실패합니다. `O_RDONLY`로 열면 `AUDIO_GET_STATUS`만 호출할 수 있고 다른 ioctl은 오류를 반환합니다.

open()
------

Synopsis
~~~~~~~~

.. code-block:: c

    #include <fcntl.h>

.. c:function:: int  open(const char *deviceName, int flags)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``const char *deviceName``

       -  Name of specific audio device.

    -  ..

       -  :rspan:`3` ``int flags``

       -  :cspan:`1` A bit-wise OR of the following flags:

    -  ..

       -  ``O_RDONLY``

       -  read-only access

    -  ..

       -  ``O_RDWR``

       -  read/write access

    -  ..

       -  ``O_NONBLOCK``
       -  | Open in non-blocking mode
          | (blocking mode is the default)

Description
~~~~~~~~~~~

This system call opens a named audio device (e.g.
``/dev/dvb/adapter0/audio0``) for subsequent use. When an open() call has
succeeded, the device will be ready for use. The significance of
blocking or non-blocking mode is described in the documentation for
functions where there is a difference. It does not affect the semantics
of the open() call itself. A device opened in blocking mode can later be
put into non-blocking mode (and vice versa) using the F_SETFL command
of the fcntl system call. This is a standard system call, documented in
the Linux manual page for fcntl. Only one user can open the Audio Device
in O_RDWR mode. All other attempts to open the device in this mode will
fail, and an error code will be returned. If the Audio Device is opened
in O_RDONLY mode, the only ioctl call that can be used is
`AUDIO_GET_STATUS`_. All other call will return with an error code.

Return Value
~~~~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``ENODEV``

       -  Device driver not loaded/available.

    -  ..

       -  ``EBUSY``

       -  Device or resource busy.

    -  ..

       -  ``EINVAL``

       -  Invalid argument.


-----

close() 장치 닫기

`close(fd)`는 이전에 연 audio device를 닫습니다.

close()
-------

Synopsis
~~~~~~~~

.. c:function:: 	int close(int fd)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

Description
~~~~~~~~~~~

This system call closes a previously opened audio device.

Return Value
~~~~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``EBADF``

       -  Fd is not a valid open file descriptor.

-----

write() PES 데이터 공급

`write(fd, buf, count)`는 `AUDIO_SELECT_SOURCE`에서 `AUDIO_SOURCE_MEMORY`를 선택했을 때만 사용할 수 있습니다. `buf`의 데이터는 PES format이어야 합니다.

`O_NONBLOCK`을 지정하지 않으면 buffer 공간이 생길 때까지 호출이 block됩니다. 전송량은 `count`가 정합니다.

write()
-------

Synopsis
~~~~~~~~

.. code-block:: c

	 size_t write(int fd, const void *buf, size_t count)

Arguments
~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``int fd``

       -  :cspan:`1` File descriptor returned by a previous call
          to `open()`_.

    -  ..

       -  ``void *buf``

       -  Pointer to the buffer containing the PES data.

    -  ..

       -  ``size_t count``

       -  Size of buf.

Description
~~~~~~~~~~~

This system call can only be used if ``AUDIO_SOURCE_MEMORY`` is selected
in the ioctl call `AUDIO_SELECT_SOURCE`_. The data provided shall be in
PES format. If ``O_NONBLOCK`` is not specified the function will block
until buffer space is available. The amount of data to be transferred is
implied by count.

Return Value
~~~~~~~~~~~~

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    -  ..

       -  ``EPERM``

       -  :cspan:`1` Mode ``AUDIO_SOURCE_MEMORY`` not selected.

    -  ..

       -  ``ENOMEM``

       -  Attempted to write more data than the internal buffer can hold.

    -  ..

       -  ``EBADF``

       -  Fd is not a valid open file descriptor.