diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/audio.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/audio.rst | 104 |
1 files changed, 0 insertions, 104 deletions
diff --git a/Documentation/media/uapi/v4l/audio.rst b/Documentation/media/uapi/v4l/audio.rst deleted file mode 100644 index 4c7fdbc8a860..000000000000 --- a/Documentation/media/uapi/v4l/audio.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. Permission is granted to copy, distribute and/or modify this -.. document under the terms of the GNU Free Documentation License, -.. Version 1.1 or any later version published by the Free Software -.. Foundation, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _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. - -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. - -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. - -.. 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. - -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. - - -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); - - -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); - } - -.. [#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. |