doc/spec/x341.htm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Audio Inputs and Outputs</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Video for Linux Two API Specification"
HREF="book1.htm"><LINK
REL="UP"
TITLE="Common API Elements"
HREF="c174.htm"><LINK
REL="PREVIOUS"
TITLE="Video Inputs and Outputs"
HREF="x309.htm"><LINK
REL="NEXT"
TITLE="Tuners and Modulators"
HREF="x394.htm"></HEAD
><BODY
CLASS="SECTION"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Video for Linux Two API Specification: Revision 0.24</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="x309.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 1. Common API Elements</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="x394.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECTION"
><H1
CLASS="SECTION"
><A
NAME="AUDIO"
>1.5. Audio Inputs and Outputs</A
></H1
><P
>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
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>is</I
></SPAN
> an audio source, but this API associates
tuners with video inputs or outputs only, and radio devices have
none of these.<A
NAME="AEN345"
HREF="x341.htm#FTN.AEN345"
><SPAN
CLASS="footnote"
>[1]</SPAN
></A
> A connector on a TV card to loop back the received
audio signal to a sound card is not considered an audio output.</P
><P
>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 <CODE
CLASS="STRUCTFIELD"
>audioset</CODE
> field of the
respective struct&nbsp;<A
HREF="r8936.htm#V4L2-INPUT"
>v4l2_input</A
> or struct&nbsp;<A
HREF="r9149.htm#V4L2-OUTPUT"
>v4l2_output</A
>, where each bit represents
the index number, starting at zero, of one audio input or output.</P
><P
>To learn about the number and attributes of the
available inputs and outputs applications can enumerate them with the
<A
HREF="r8242.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMAUDIO</CODE
></A
> and <A
HREF="r8304.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_ENUMAUDOUT</CODE
></A
> ioctl, respectively. The
struct&nbsp;<A
HREF="r9539.htm#V4L2-AUDIO"
>v4l2_audio</A
> returned by the <CODE
CLASS="CONSTANT"
>VIDIOC_ENUMAUDIO</CODE
> ioctl
also contains signal status information applicable when the current
audio input is queried.</P
><P
>The <A
HREF="r9539.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDIO</CODE
></A
> and <A
HREF="r9688.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDOUT</CODE
></A
> ioctl report
the current audio input and output, respectively. Note that, unlike
<A
HREF="r11217.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_INPUT</CODE
></A
> and <A
HREF="r11612.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_OUTPUT</CODE
></A
> these ioctls return a structure
as <CODE
CLASS="CONSTANT"
>VIDIOC_ENUMAUDIO</CODE
> and
<CODE
CLASS="CONSTANT"
>VIDIOC_ENUMAUDOUT</CODE
> do, not just an index.</P
><P
>To select an audio input and change its properties
applications call the <A
HREF="r9539.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_AUDIO</CODE
></A
> ioctl. To select an audio
output (which presently has no changeable properties) applications
call the <A
HREF="r9688.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_AUDOUT</CODE
></A
> ioctl.</P
><P
>Drivers must implement all input ioctls when the device
has one or more inputs, all output ioctls when the device has one
or more outputs. When the device has any audio inputs or outputs the
driver must set the <CODE
CLASS="CONSTANT"
>V4L2_CAP_AUDIO</CODE
> flag in the
struct&nbsp;<A
HREF="r13105.htm#V4L2-CAPABILITY"
>v4l2_capability</A
> returned by the <A
HREF="r13105.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_QUERYCAP</CODE
></A
> ioctl.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN382"
></A
><P
><B
>Example 1-3. Information about the current audio input</B
></P
><PRE
CLASS="PROGRAMLISTING"
>struct&nbsp;<A
HREF="r9539.htm#V4L2-AUDIO"
>v4l2_audio</A
> audio;

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

if (-1 == ioctl (fd, <A
HREF="r9539.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_AUDIO</CODE
></A
>, &amp;audio)) {
        perror ("VIDIOC_G_AUDIO");
        exit (EXIT_FAILURE);
}

printf ("Current input: %s\n", audio.name);
      </PRE
></DIV
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN388"
></A
><P
><B
>Example 1-4. Switching to the first audio input</B
></P
><PRE
CLASS="PROGRAMLISTING"
>struct&nbsp;<A
HREF="r9539.htm#V4L2-AUDIO"
>v4l2_audio</A
> audio;

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

audio.index = 0;

if (-1 == ioctl (fd, <A
HREF="r9539.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_S_AUDIO</CODE
></A
>, &amp;audio)) {
        perror ("VIDIOC_S_AUDIO");
        exit (EXIT_FAILURE);
}
      </PRE
></DIV
></DIV
><H3
CLASS="FOOTNOTES"
>Notes</H3
><TABLE
BORDER="0"
CLASS="FOOTNOTES"
WIDTH="100%"
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN345"
HREF="x341.htm#AEN345"
><SPAN
CLASS="footnote"
>[1]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>Actually struct&nbsp;<A
HREF="r9539.htm#V4L2-AUDIO"
>v4l2_audio</A
> ought to have a
<CODE
CLASS="STRUCTFIELD"
>tuner</CODE
> field like struct&nbsp;<A
HREF="r8936.htm#V4L2-INPUT"
>v4l2_input</A
>, not only
making the API more consistent but also permitting radio devices with
multiple tuners.</P
></TD
></TR
></TABLE
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="x309.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.htm"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="x394.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Video Inputs and Outputs</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="c174.htm"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Tuners and Modulators</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>