diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/audio.rst')
-rw-r--r-- | Documentation/media/uapi/v4l/audio.rst | 90 |
1 files changed, 90 insertions, 0 deletions
diff --git a/Documentation/media/uapi/v4l/audio.rst b/Documentation/media/uapi/v4l/audio.rst new file mode 100644 index 000000000000..71502f0bf8bd --- /dev/null +++ b/Documentation/media/uapi/v4l/audio.rst @@ -0,0 +1,90 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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. [1]_ A connector on a TV card to loop back the received audio +signal to a sound card is not considered an audio output. + +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 +:ref:`v4l2_input <v4l2-input>` or struct +:ref:`v4l2_output <v4l2-output>`, where each bit represents the index +number, starting at zero, of one audio input or 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 :ref:`v4l2_audio <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. 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. + +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 :ref:`v4l2_capability <v4l2-capability>` returned by +the :ref:`VIDIOC_QUERYCAP` ioctl. + + +.. code-block:: c + :caption: Example 1.3. Information about the current 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); + + +.. code-block:: c + :caption: Example 1.4. Switching to the first audio input + + 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); + } + +.. [1] + Actually struct :ref:`v4l2_audio <v4l2-audio>` ought to have a + ``tuner`` field like struct :ref:`v4l2_input <v4l2-input>`, not + only making the API more consistent but also permitting radio devices + with multiple tuners. |