Documentation/DocBook/media/dvb/audio.xml

   1 <title>DVB Audio Device</title>
   2 <para>The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. It
   3 can be accessed through <constant>/dev/dvb/adapter?/audio?</constant>. Data types and and
   4 ioctl definitions can be accessed by including <constant>linux/dvb/audio.h</constant> in your
   5 application.
   6 </para>
   7 <para>Please note that some DVB cards don&#8217;t have their own MPEG decoder, which results in
   8 the omission of the audio and video device.
   9 </para>
  10 <para>
  11 These ioctls were also used by V4L2 to control MPEG decoders implemented in V4L2. The use
  12 of these ioctls for that purpose has been made obsolete and proper V4L2 ioctls or controls
  13 have been created to replace that functionality.</para>
  14
  15 <section id="audio_data_types">
  16 <title>Audio Data Types</title>
  17 <para>This section describes the structures, data types and defines used when talking to the
  18 audio device.
  19 </para>
  20
  21 <section id="audio-stream-source-t">
  22 <title>audio_stream_source_t</title>
  23 <para>The audio stream source is set through the AUDIO_SELECT_SOURCE call and can take
  24 the following values, depending on whether we are replaying from an internal (demux) or
  25 external (user write) source.
  26 </para>
  27 <programlisting>
  28 typedef enum {
  29         AUDIO_SOURCE_DEMUX,
  30         AUDIO_SOURCE_MEMORY
  31 } audio_stream_source_t;
  32 </programlisting>
  33 <para>AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the
  34 DVR device) as the source of the video stream. If AUDIO_SOURCE_MEMORY
  35 is selected the stream comes from the application through the <constant>write()</constant> system
  36 call.
  37 </para>
  38
  39 </section>
  40 <section id="audio-play-state-t">
  41 <title>audio_play_state_t</title>
  42 <para>The following values can be returned by the AUDIO_GET_STATUS call representing the
  43 state of audio playback.
  44 </para>
  45 <programlisting>
  46 typedef enum {
  47         AUDIO_STOPPED,
  48         AUDIO_PLAYING,
  49         AUDIO_PAUSED
  50 } audio_play_state_t;
  51 </programlisting>
  52
  53 </section>
  54 <section id="audio-channel-select-t">
  55 <title>audio_channel_select_t</title>
  56 <para>The audio channel selected via AUDIO_CHANNEL_SELECT is determined by the
  57 following values.
  58 </para>
  59 <programlisting>
  60 typedef enum {
  61         AUDIO_STEREO,
  62         AUDIO_MONO_LEFT,
  63         AUDIO_MONO_RIGHT,
  64         AUDIO_MONO,
  65         AUDIO_STEREO_SWAPPED
  66 } audio_channel_select_t;
  67 </programlisting>
  68
  69 </section>
  70 <section id="audio-status">
  71 <title>struct audio_status</title>
  72 <para>The AUDIO_GET_STATUS call returns the following structure informing about various
  73 states of the playback operation.
  74 </para>
  75 <programlisting>
  76 typedef struct audio_status {
  77         boolean AV_sync_state;
  78         boolean mute_state;
  79         audio_play_state_t play_state;
  80         audio_stream_source_t stream_source;
  81         audio_channel_select_t channel_select;
  82         boolean bypass_mode;
  83         audio_mixer_t mixer_state;
  84 } audio_status_t;
  85 </programlisting>
  86
  87 </section>
  88 <section id="audio-mixer">
  89 <title>struct audio_mixer</title>
  90 <para>The following structure is used by the AUDIO_SET_MIXER call to set the audio
  91 volume.
  92 </para>
  93 <programlisting>
  94 typedef struct audio_mixer {
  95         unsigned int volume_left;
  96         unsigned int volume_right;
  97 } audio_mixer_t;
  98 </programlisting>
  99
 100 </section>
 101 <section id="audio_encodings">
 102 <title>audio encodings</title>
 103 <para>A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the following
 104 bits set according to the hardwares capabilities.
 105 </para>
 106 <programlisting>
 107  #define AUDIO_CAP_DTS    1
 108  #define AUDIO_CAP_LPCM   2
 109  #define AUDIO_CAP_MP1    4
 110  #define AUDIO_CAP_MP2    8
 111  #define AUDIO_CAP_MP3   16
 112  #define AUDIO_CAP_AAC   32
 113  #define AUDIO_CAP_OGG   64
 114  #define AUDIO_CAP_SDDS 128
 115  #define AUDIO_CAP_AC3  256
 116 </programlisting>
 117
 118 </section>
 119 <section id="audio-karaoke">
 120 <title>struct audio_karaoke</title>
 121 <para>The ioctl AUDIO_SET_KARAOKE uses the following format:
 122 </para>
 123 <programlisting>
 124 typedef
 125 struct audio_karaoke {
 126         int vocal1;
 127         int vocal2;
 128         int melody;
 129 } audio_karaoke_t;
 130 </programlisting>
 131 <para>If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t at 70% each. If both,
 132 Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed into the left channel and Vocal2 into the
 133 right channel at 100% each. Ff Melody is non-zero, the melody channel gets mixed into left
 134 and right.
 135 </para>
 136
 137 </section>
 138 <section id="audio-attributes-t">
 139 <title>audio attributes</title>
 140 <para>The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES:
 141 </para>
 142 <programlisting>
 143  typedef uint16_t audio_attributes_t;
 144  /&#x22C6;   bits: descr. &#x22C6;/
 145  /&#x22C6;   15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, &#x22C6;/
 146  /&#x22C6;   12    multichannel extension &#x22C6;/
 147  /&#x22C6;   11-10 audio type (0=not spec, 1=language included) &#x22C6;/
 148  /&#x22C6;    9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) &#x22C6;/
 149  /&#x22C6;    7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit,  &#x22C6;/
 150  /&#x22C6;    5- 4 Sample frequency fs (0=48kHz, 1=96kHz) &#x22C6;/
 151  /&#x22C6;    2- 0 number of audio channels (n+1 channels) &#x22C6;/
 152 </programlisting>
 153  </section></section>
 154 <section id="audio_function_calls">
 155 <title>Audio Function Calls</title>
 156
 157
 158 <section id="audio_fopen">
 159 <title>open()</title>
 160 <para>DESCRIPTION
 161 </para>
 162 <informaltable><tgroup cols="1"><tbody><row><entry
 163  align="char">
 164 <para>This system call opens a named audio device (e.g. /dev/dvb/adapter0/audio0)
 165  for subsequent use. When an open() call has succeeded, the device will be ready
 166  for use. The significance of blocking or non-blocking mode is described in the
 167  documentation for functions where there is a difference. It does not affect the
 168  semantics of the open() call itself. A device opened in blocking mode can later
 169  be put into non-blocking mode (and vice versa) using the F_SETFL command
 170  of the fcntl system call. This is a standard system call, documented in the Linux
 171  manual page for fcntl. Only one user can open the Audio Device in O_RDWR
 172  mode. All other attempts to open the device in this mode will fail, and an error
 173  code will be returned. If the Audio Device is opened in O_RDONLY mode, the
 174  only ioctl call that can be used is AUDIO_GET_STATUS. All other call will
 175  return with an error code.</para>
 176 </entry>
 177  </row></tbody></tgroup></informaltable>
 178 <para>SYNOPSIS
 179 </para>
 180 <informaltable><tgroup cols="1"><tbody><row><entry
 181  align="char">
 182 <para>int open(const char &#x22C6;deviceName, int flags);</para>
 183 </entry>
 184  </row></tbody></tgroup></informaltable>
 185 <para>PARAMETERS
 186 </para>
 187 <informaltable><tgroup cols="2"><tbody><row><entry
 188  align="char">
 189 <para>const char
 190  *deviceName</para>
 191 </entry><entry
 192  align="char">
 193 <para>Name of specific audio device.</para>
 194 </entry>
 195  </row><row><entry
 196  align="char">
 197 <para>int flags</para>
 198 </entry><entry
 199  align="char">
 200 <para>A bit-wise OR of the following flags:</para>
 201 </entry>
 202  </row><row><entry
 203  align="char">
 204 </entry><entry
 205  align="char">
 206 <para>O_RDONLY read-only access</para>
 207 </entry>
 208  </row><row><entry
 209  align="char">
 210 </entry><entry
 211  align="char">
 212 <para>O_RDWR read/write access</para>
 213 </entry>
 214  </row><row><entry
 215  align="char">
 216 </entry><entry
 217  align="char">
 218 <para>O_NONBLOCK open in non-blocking mode</para>
 219 </entry>
 220  </row><row><entry
 221  align="char">
 222 </entry><entry
 223  align="char">
 224 <para>(blocking mode is the default)</para>
 225 </entry>
 226  </row></tbody></tgroup></informaltable>
 227 <para>RETURN VALUE</para>
 228 <informaltable><tgroup cols="2"><tbody><row><entry
 229  align="char">
 230 <para>ENODEV</para>
 231 </entry><entry
 232  align="char">
 233 <para>Device driver not loaded/available.</para>
 234 </entry>
 235  </row><row><entry
 236  align="char">
 237 <para>EBUSY</para>
 238 </entry><entry
 239  align="char">
 240 <para>Device or resource busy.</para>
 241 </entry>
 242  </row><row><entry
 243  align="char">
 244 <para>EINVAL</para>
 245 </entry><entry
 246  align="char">
 247 <para>Invalid argument.</para>
 248 </entry>
 249  </row></tbody></tgroup></informaltable>
 250
 251 </section>
 252 <section id="audio_fclose">
 253 <title>close()</title>
 254 <para>DESCRIPTION
 255 </para>
 256 <informaltable><tgroup cols="1"><tbody><row><entry
 257  align="char">
 258 <para>This system call closes a previously opened audio device.</para>
 259 </entry>
 260  </row></tbody></tgroup></informaltable>
 261 <para>SYNOPSIS
 262 </para>
 263 <informaltable><tgroup cols="1"><tbody><row><entry
 264  align="char">
 265 <para>int close(int fd);</para>
 266 </entry>
 267  </row></tbody></tgroup></informaltable>
 268 <para>PARAMETERS
 269 </para>
 270 <informaltable><tgroup cols="2"><tbody><row><entry
 271  align="char">
 272 <para>int fd</para>
 273 </entry><entry
 274  align="char">
 275 <para>File descriptor returned by a previous call to open().</para>
 276 </entry>
 277  </row></tbody></tgroup></informaltable>
 278 <para>RETURN VALUE</para>
 279 <informaltable><tgroup cols="2"><tbody><row><entry
 280  align="char">
 281 <para>EBADF</para>
 282 </entry><entry
 283  align="char">
 284 <para>fd is not a valid open file descriptor.</para>
 285 </entry>
 286  </row></tbody></tgroup></informaltable>
 287
 288 </section>
 289 <section id="audio_fwrite">
 290 <title>write()</title>
 291 <para>DESCRIPTION
 292 </para>
 293 <informaltable><tgroup cols="1"><tbody><row><entry
 294  align="char">
 295 <para>This system call can only be used if AUDIO_SOURCE_MEMORY is selected
 296  in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in
 297  PES format. If O_NONBLOCK is not specified the function will block until
 298  buffer space is available. The amount of data to be transferred is implied by
 299  count.</para>
 300 </entry>
 301  </row></tbody></tgroup></informaltable>
 302 <para>SYNOPSIS
 303 </para>
 304 <informaltable><tgroup cols="1"><tbody><row><entry
 305  align="char">
 306 <para>size_t write(int fd, const void &#x22C6;buf, size_t count);</para>
 307 </entry>
 308  </row></tbody></tgroup></informaltable>
 309 <para>PARAMETERS
 310 </para>
 311 <informaltable><tgroup cols="2"><tbody><row><entry
 312  align="char">
 313 <para>int fd</para>
 314 </entry><entry
 315  align="char">
 316 <para>File descriptor returned by a previous call to open().</para>
 317 </entry>
 318  </row><row><entry
 319  align="char">
 320 <para>void *buf</para>
 321 </entry><entry
 322  align="char">
 323 <para>Pointer to the buffer containing the PES data.</para>
 324 </entry>
 325  </row><row><entry
 326  align="char">
 327 <para>size_t count</para>
 328 </entry><entry
 329  align="char">
 330 <para>Size of buf.</para>
 331 </entry>
 332  </row></tbody></tgroup></informaltable>
 333 <para>RETURN VALUE</para>
 334 <informaltable><tgroup cols="2"><tbody><row><entry
 335  align="char">
 336 <para>EPERM</para>
 337 </entry><entry
 338  align="char">
 339 <para>Mode AUDIO_SOURCE_MEMORY not selected.</para>
 340 </entry>
 341  </row><row><entry
 342  align="char">
 343 <para>ENOMEM</para>
 344 </entry><entry
 345  align="char">
 346 <para>Attempted to write more data than the internal buffer can
 347  hold.</para>
 348 </entry>
 349  </row><row><entry
 350  align="char">
 351 <para>EBADF</para>
 352 </entry><entry
 353  align="char">
 354 <para>fd is not a valid open file descriptor.</para>
 355 </entry>
 356  </row></tbody></tgroup></informaltable>
 357
 358 </section><section id="AUDIO_STOP"
 359 role="subsection"><title>AUDIO_STOP</title>
 360 <para>DESCRIPTION
 361 </para>
 362 <informaltable><tgroup cols="1"><tbody><row><entry
 363  align="char">
 364 <para>This ioctl call asks the Audio Device to stop playing the current stream.</para>
 365 </entry>
 366  </row></tbody></tgroup></informaltable>
 367 <para>SYNOPSIS
 368 </para>
 369 <informaltable><tgroup cols="1"><tbody><row><entry
 370  align="char">
 371 <para>int ioctl(int fd, int request = AUDIO_STOP);</para>
 372 </entry>
 373  </row></tbody></tgroup></informaltable>
 374 <para>PARAMETERS
 375 </para>
 376 <informaltable><tgroup cols="2"><tbody><row><entry
 377  align="char">
 378 <para>int fd</para>
 379 </entry><entry
 380  align="char">
 381 <para>File descriptor returned by a previous call to open().</para>
 382 </entry>
 383  </row><row><entry
 384  align="char">
 385 <para>int request</para>
 386 </entry><entry
 387  align="char">
 388 <para>Equals AUDIO_STOP for this command.</para>
 389 </entry>
 390  </row></tbody></tgroup></informaltable>
 391 &return-value-dvb;
 392
 393 </section><section id="AUDIO_PLAY"
 394 role="subsection"><title>AUDIO_PLAY</title>
 395 <para>DESCRIPTION
 396 </para>
 397 <informaltable><tgroup cols="1"><tbody><row><entry
 398  align="char">
 399 <para>This ioctl call asks the Audio Device to start playing an audio stream from the
 400  selected source.</para>
 401 </entry>
 402  </row></tbody></tgroup></informaltable>
 403 <para>SYNOPSIS
 404 </para>
 405 <informaltable><tgroup cols="1"><tbody><row><entry
 406  align="char">
 407 <para>int ioctl(int fd, int request = AUDIO_PLAY);</para>
 408 </entry>
 409  </row></tbody></tgroup></informaltable>
 410 <para>PARAMETERS
 411 </para>
 412 <informaltable><tgroup cols="2"><tbody><row><entry
 413  align="char">
 414 <para>int fd</para>
 415 </entry><entry
 416  align="char">
 417 <para>File descriptor returned by a previous call to open().</para>
 418 </entry>
 419  </row><row><entry
 420  align="char">
 421 <para>int request</para>
 422 </entry><entry
 423  align="char">
 424 <para>Equals AUDIO_PLAY for this command.</para>
 425 </entry>
 426  </row></tbody></tgroup></informaltable>
 427 &return-value-dvb;
 428
 429 </section><section id="AUDIO_PAUSE"
 430 role="subsection"><title>AUDIO_PAUSE</title>
 431 <para>DESCRIPTION
 432 </para>
 433 <informaltable><tgroup cols="1"><tbody><row><entry
 434  align="char">
 435 <para>This ioctl call suspends the audio stream being played. Decoding and playing
 436  are paused. It is then possible to restart again decoding and playing process of
 437  the audio stream using AUDIO_CONTINUE command.</para>
 438 </entry>
 439  </row><row><entry
 440  align="char">
 441 <para>If AUDIO_SOURCE_MEMORY is selected in the ioctl call
 442  AUDIO_SELECT_SOURCE, the DVB-subsystem will not decode (consume)
 443  any more data until the ioctl call AUDIO_CONTINUE or AUDIO_PLAY is
 444  performed.</para>
 445 </entry>
 446  </row></tbody></tgroup></informaltable>
 447 <para>SYNOPSIS
 448 </para>
 449 <informaltable><tgroup cols="1"><tbody><row><entry
 450  align="char">
 451 <para>int ioctl(int fd, int request = AUDIO_PAUSE);</para>
 452 </entry>
 453  </row></tbody></tgroup></informaltable>
 454 <para>PARAMETERS
 455 </para>
 456 <informaltable><tgroup cols="2"><tbody><row><entry
 457  align="char">
 458 <para>int fd</para>
 459 </entry><entry
 460  align="char">
 461 <para>File descriptor returned by a previous call to open().</para>
 462 </entry>
 463  </row><row><entry
 464  align="char">
 465 <para>int request</para>
 466 </entry><entry
 467  align="char">
 468 <para>Equals AUDIO_PAUSE for this command.</para>
 469 </entry>
 470  </row></tbody></tgroup></informaltable>
 471 &return-value-dvb;
 472
 473 </section><section id="AUDIO_CONTINUE"
 474 role="subsection"><title>AUDIO_CONTINUE</title>
 475 <para>DESCRIPTION
 476 </para>
 477 <informaltable><tgroup cols="1"><tbody><row><entry
 478  align="char">
 479 <para>This ioctl restarts the decoding and playing process previously paused
 480 with AUDIO_PAUSE command.</para>
 481 </entry>
 482  </row><row><entry
 483  align="char">
 484 <para>It only works if the stream were previously stopped with AUDIO_PAUSE</para>
 485 </entry>
 486  </row></tbody></tgroup></informaltable>
 487 <para>SYNOPSIS
 488 </para>
 489 <informaltable><tgroup cols="1"><tbody><row><entry
 490  align="char">
 491 <para>int ioctl(int fd, int request = AUDIO_CONTINUE);</para>
 492 </entry>
 493  </row></tbody></tgroup></informaltable>
 494 <para>PARAMETERS
 495 </para>
 496 <informaltable><tgroup cols="2"><tbody><row><entry
 497  align="char">
 498 <para>int fd</para>
 499 </entry><entry
 500  align="char">
 501 <para>File descriptor returned by a previous call to open().</para>
 502 </entry>
 503  </row><row><entry
 504  align="char">
 505 <para>int request</para>
 506 </entry><entry
 507  align="char">
 508 <para>Equals AUDIO_CONTINUE for this command.</para>
 509 </entry>
 510  </row></tbody></tgroup></informaltable>
 511 &return-value-dvb;
 512
 513 </section><section id="AUDIO_SELECT_SOURCE"
 514 role="subsection"><title>AUDIO_SELECT_SOURCE</title>
 515 <para>DESCRIPTION
 516 </para>
 517 <informaltable><tgroup cols="1"><tbody><row><entry
 518  align="char">
 519 <para>This ioctl call informs the audio device which source shall be used
 520  for the input data. The possible sources are demux or memory. If
 521  AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device
 522  through the write command.</para>
 523 </entry>
 524  </row></tbody></tgroup></informaltable>
 525 <para>SYNOPSIS
 526 </para>
 527 <informaltable><tgroup cols="1"><tbody><row><entry
 528  align="char">
 529 <para>int ioctl(int fd, int request = AUDIO_SELECT_SOURCE,
 530  audio_stream_source_t source);</para>
 531 </entry>
 532  </row></tbody></tgroup></informaltable>
 533 <para>PARAMETERS
 534 </para>
 535 <informaltable><tgroup cols="2"><tbody><row><entry
 536  align="char">
 537 <para>int fd</para>
 538 </entry><entry
 539  align="char">
 540 <para>File descriptor returned by a previous call to open().</para>
 541 </entry>
 542  </row><row><entry
 543  align="char">
 544 <para>int request</para>
 545 </entry><entry
 546  align="char">
 547 <para>Equals AUDIO_SELECT_SOURCE for this command.</para>
 548 </entry>
 549  </row><row><entry
 550  align="char">
 551 <para>audio_stream_source_t
 552  source</para>
 553 </entry><entry
 554  align="char">
 555 <para>Indicates the source that shall be used for the Audio
 556  stream.</para>
 557 </entry>
 558  </row></tbody></tgroup></informaltable>
 559 &return-value-dvb;
 560
 561 </section><section id="AUDIO_SET_MUTE"
 562 role="subsection"><title>AUDIO_SET_MUTE</title>
 563 <para>DESCRIPTION
 564 </para>
 565 <para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2
 566 &VIDIOC-DECODER-CMD; with the <constant>V4L2_DEC_CMD_START_MUTE_AUDIO</constant> flag instead.</para>
 567 <informaltable><tgroup cols="1"><tbody><row><entry
 568  align="char">
 569 <para>This ioctl call asks the audio device to mute the stream that is currently being
 570  played.</para>
 571 </entry>
 572  </row></tbody></tgroup></informaltable>
 573 <para>SYNOPSIS
 574 </para>
 575 <informaltable><tgroup cols="1"><tbody><row><entry
 576  align="char">
 577 <para>int ioctl(int fd, int request = AUDIO_SET_MUTE,
 578  boolean state);</para>
 579 </entry>
 580  </row></tbody></tgroup></informaltable>
 581 <para>PARAMETERS
 582 </para>
 583 <informaltable><tgroup cols="2"><tbody><row><entry
 584  align="char">
 585 <para>int fd</para>
 586 </entry><entry
 587  align="char">
 588 <para>File descriptor returned by a previous call to open().</para>
 589 </entry>
 590  </row><row><entry
 591  align="char">
 592 <para>int request</para>
 593 </entry><entry
 594  align="char">
 595 <para>Equals AUDIO_SET_MUTE for this command.</para>
 596 </entry>
 597  </row><row><entry
 598  align="char">
 599 <para>boolean state</para>
 600 </entry><entry
 601  align="char">
 602 <para>Indicates if audio device shall mute or not.</para>
 603 </entry>
 604  </row><row><entry
 605  align="char">
 606 </entry><entry
 607  align="char">
 608 <para>TRUE Audio Mute</para>
 609 </entry>
 610  </row><row><entry
 611  align="char">
 612 </entry><entry
 613  align="char">
 614 <para>FALSE Audio Un-mute</para>
 615 </entry>
 616  </row></tbody></tgroup></informaltable>
 617 &return-value-dvb;
 618
 619 </section><section id="AUDIO_SET_AV_SYNC"
 620 role="subsection"><title>AUDIO_SET_AV_SYNC</title>
 621 <para>DESCRIPTION
 622 </para>
 623 <informaltable><tgroup cols="1"><tbody><row><entry
 624  align="char">
 625 <para>This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization.</para>
 626 </entry>
 627  </row></tbody></tgroup></informaltable>
 628 <para>SYNOPSIS
 629 </para>
 630 <informaltable><tgroup cols="1"><tbody><row><entry
 631  align="char">
 632 <para>int ioctl(int fd, int request = AUDIO_SET_AV_SYNC,
 633  boolean state);</para>
 634 </entry>
 635  </row></tbody></tgroup></informaltable>
 636 <para>PARAMETERS
 637 </para>
 638 <informaltable><tgroup cols="2"><tbody><row><entry
 639  align="char">
 640 <para>int fd</para>
 641 </entry><entry
 642  align="char">
 643 <para>File descriptor returned by a previous call to open().</para>
 644 </entry>
 645  </row><row><entry
 646  align="char">
 647 <para>int request</para>
 648 </entry><entry
 649  align="char">
 650 <para>Equals AUDIO_AV_SYNC for this command.</para>
 651 </entry>
 652  </row><row><entry
 653  align="char">
 654 <para>boolean state</para>
 655 </entry><entry
 656  align="char">
 657 <para>Tells the DVB subsystem if A/V synchronization shall be
 658  ON or OFF.</para>
 659 </entry>
 660  </row><row><entry
 661  align="char">
 662 </entry><entry
 663  align="char">
 664 <para>TRUE AV-sync ON</para>
 665 </entry>
 666  </row><row><entry
 667  align="char">
 668 </entry><entry
 669  align="char">
 670 <para>FALSE AV-sync OFF</para>
 671 </entry>
 672  </row></tbody></tgroup></informaltable>
 673 &return-value-dvb;
 674
 675 </section><section id="AUDIO_SET_BYPASS_MODE"
 676 role="subsection"><title>AUDIO_SET_BYPASS_MODE</title>
 677 <para>DESCRIPTION
 678 </para>
 679 <informaltable><tgroup cols="1"><tbody><row><entry
 680  align="char">
 681 <para>This ioctl call asks the Audio Device to bypass the Audio decoder and forward
 682  the stream without decoding. This mode shall be used if streams that can&#8217;t be
 683  handled by the DVB system shall be decoded. Dolby DigitalTM streams are
 684  automatically forwarded by the DVB subsystem if the hardware can handle it.</para>
 685 </entry>
 686  </row></tbody></tgroup></informaltable>
 687 <para>SYNOPSIS
 688 </para>
 689 <informaltable><tgroup cols="1"><tbody><row><entry
 690  align="char">
 691 <para>int ioctl(int fd, int request =
 692  AUDIO_SET_BYPASS_MODE, boolean mode);</para>
 693 </entry>
 694  </row></tbody></tgroup></informaltable>
 695 <para>PARAMETERS
 696 </para>
 697 <informaltable><tgroup cols="2"><tbody><row><entry
 698  align="char">
 699 <para>int fd</para>
 700 </entry><entry
 701  align="char">
 702 <para>File descriptor returned by a previous call to open().</para>
 703 </entry>
 704  </row><row><entry
 705  align="char">
 706 <para>int request</para>
 707 </entry><entry
 708  align="char">
 709 <para>Equals AUDIO_SET_BYPASS_MODE for this
 710  command.</para>
 711 </entry>
 712  </row><row><entry
 713  align="char">
 714 <para>boolean mode</para>
 715 </entry><entry
 716  align="char">
 717 <para>Enables or disables the decoding of the current Audio
 718  stream in the DVB subsystem.</para>
 719 </entry>
 720  </row><row><entry
 721  align="char">
 722 </entry><entry
 723  align="char">
 724 <para>TRUE Bypass is disabled</para>
 725 </entry>
 726  </row><row><entry
 727  align="char">
 728 </entry><entry
 729  align="char">
 730 <para>FALSE Bypass is enabled</para>
 731 </entry>
 732  </row></tbody></tgroup></informaltable>
 733 &return-value-dvb;
 734
 735 </section><section id="AUDIO_CHANNEL_SELECT"
 736 role="subsection"><title>AUDIO_CHANNEL_SELECT</title>
 737 <para>DESCRIPTION
 738 </para>
 739 <para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2
 740 <constant>V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK</constant> control instead.</para>
 741 <informaltable><tgroup cols="1"><tbody><row><entry
 742  align="char">
 743 <para>This ioctl call asks the Audio Device to select the requested channel if possible.</para>
 744 </entry>
 745  </row></tbody></tgroup></informaltable>
 746 <para>SYNOPSIS
 747 </para>
 748 <informaltable><tgroup cols="1"><tbody><row><entry
 749  align="char">
 750 <para>int ioctl(int fd, int request =
 751  AUDIO_CHANNEL_SELECT, audio_channel_select_t);</para>
 752 </entry>
 753  </row></tbody></tgroup></informaltable>
 754 <para>PARAMETERS
 755 </para>
 756 <informaltable><tgroup cols="2"><tbody><row><entry
 757  align="char">
 758 <para>int fd</para>
 759 </entry><entry
 760  align="char">
 761 <para>File descriptor returned by a previous call to open().</para>
 762 </entry>
 763  </row><row><entry
 764  align="char">
 765 <para>int request</para>
 766 </entry><entry
 767  align="char">
 768 <para>Equals AUDIO_CHANNEL_SELECT for this
 769  command.</para>
 770 </entry>
 771  </row><row><entry
 772  align="char">
 773 <para>audio_channel_select_t
 774  ch</para>
 775 </entry><entry
 776  align="char">
 777 <para>Select the output format of the audio (mono left/right,
 778  stereo).</para>
 779 </entry>
 780  </row></tbody></tgroup></informaltable>
 781 &return-value-dvb;
 782
 783 </section><section id="AUDIO_BILINGUAL_CHANNEL_SELECT"
 784 role="subsection"><title>AUDIO_BILINGUAL_CHANNEL_SELECT</title>
 785 <para>DESCRIPTION
 786 </para>
 787 <para>This ioctl is obsolete. Do not use in new drivers. It has been replaced by
 788 the V4L2 <constant>V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK</constant> control
 789 for MPEG decoders controlled through V4L2.</para>
 790 <informaltable><tgroup cols="1"><tbody><row><entry
 791  align="char">
 792 <para>This ioctl call asks the Audio Device to select the requested channel for bilingual streams if possible.</para>
 793 </entry>
 794  </row></tbody></tgroup></informaltable>
 795 <para>SYNOPSIS
 796 </para>
 797 <informaltable><tgroup cols="1"><tbody><row><entry
 798  align="char">
 799 <para>int ioctl(int fd, int request =
 800  AUDIO_BILINGUAL_CHANNEL_SELECT, audio_channel_select_t);</para>
 801 </entry>
 802  </row></tbody></tgroup></informaltable>
 803 <para>PARAMETERS
 804 </para>
 805 <informaltable><tgroup cols="2"><tbody><row><entry
 806  align="char">
 807 <para>int fd</para>
 808 </entry><entry
 809  align="char">
 810 <para>File descriptor returned by a previous call to open().</para>
 811 </entry>
 812  </row><row><entry
 813  align="char">
 814 <para>int request</para>
 815 </entry><entry
 816  align="char">
 817 <para>Equals AUDIO_BILINGUAL_CHANNEL_SELECT for this
 818  command.</para>
 819 </entry>
 820  </row><row><entry
 821  align="char">
 822 <para>audio_channel_select_t
 823 ch</para>
 824 </entry><entry
 825  align="char">
 826 <para>Select the output format of the audio (mono left/right,
 827  stereo).</para>
 828 </entry>
 829  </row>
 830 </tbody></tgroup></informaltable>
 831 &return-value-dvb;
 832
 833 </section><section id="AUDIO_GET_PTS"
 834 role="subsection"><title>AUDIO_GET_PTS</title>
 835 <para>DESCRIPTION
 836 </para>
 837 <para>This ioctl is obsolete. Do not use in new drivers. If you need this functionality,
 838 then please contact the linux-media mailing list (&v4l-ml;).</para>
 839 <informaltable><tgroup cols="1"><tbody><row><entry
 840  align="char">
 841 <para>This ioctl call asks the Audio Device to return the current PTS timestamp.</para>
 842 </entry>
 843  </row></tbody></tgroup></informaltable>
 844 <para>SYNOPSIS
 845 </para>
 846 <informaltable><tgroup cols="1"><tbody><row><entry
 847  align="char">
 848 <para>int ioctl(int fd, int request =
 849  AUDIO_GET_PTS, __u64 *pts);</para>
 850 </entry>
 851  </row></tbody></tgroup></informaltable>
 852 <para>PARAMETERS
 853 </para>
 854 <informaltable><tgroup cols="2"><tbody><row><entry
 855  align="char">
 856 <para>int fd</para>
 857 </entry><entry
 858  align="char">
 859 <para>File descriptor returned by a previous call to open().</para>
 860 </entry>
 861  </row><row><entry
 862  align="char">
 863 <para>int request</para>
 864 </entry><entry
 865  align="char">
 866 <para>Equals AUDIO_GET_PTS for this
 867  command.</para>
 868 </entry>
 869  </row><row><entry
 870  align="char">
 871 <para>__u64 *pts
 872 </para>
 873 </entry><entry
 874  align="char">
 875 <para>Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / ISO/IEC 13818-1.
 876 </para>
 877 <para>
 878 The PTS should belong to the currently played
 879 frame if possible, but may also be a value close to it
 880 like the PTS of the last decoded frame or the last PTS
 881 extracted by the PES parser.</para>
 882 </entry>
 883  </row></tbody></tgroup></informaltable>
 884 &return-value-dvb;
 885
 886 </section><section id="AUDIO_GET_STATUS"
 887 role="subsection"><title>AUDIO_GET_STATUS</title>
 888 <para>DESCRIPTION
 889 </para>
 890 <informaltable><tgroup cols="1"><tbody><row><entry
 891  align="char">
 892 <para>This ioctl call asks the Audio Device to return the current state of the Audio
 893  Device.</para>
 894 </entry>
 895  </row></tbody></tgroup></informaltable>
 896 <para>SYNOPSIS
 897 </para>
 898 <informaltable><tgroup cols="1"><tbody><row><entry
 899  align="char">
 900 <para>int ioctl(int fd, int request = AUDIO_GET_STATUS,
 901  struct audio_status &#x22C6;status);</para>
 902 </entry>
 903  </row></tbody></tgroup></informaltable>
 904 <para>PARAMETERS
 905 </para>
 906 <informaltable><tgroup cols="2"><tbody><row><entry
 907  align="char">
 908 <para>int fd</para>
 909 </entry><entry
 910  align="char">
 911 <para>File descriptor returned by a previous call to open().</para>
 912 </entry>
 913  </row><row><entry
 914  align="char">
 915 <para>int request</para>
 916 </entry><entry
 917  align="char">
 918 <para>Equals AUDIO_GET_STATUS for this command.</para>
 919 </entry>
 920  </row><row><entry
 921  align="char">
 922 <para>struct audio_status
 923  *status</para>
 924 </entry><entry
 925  align="char">
 926 <para>Returns the current state of Audio Device.</para>
 927 </entry>
 928  </row></tbody></tgroup></informaltable>
 929 &return-value-dvb;
 930
 931 </section><section id="AUDIO_GET_CAPABILITIES"
 932 role="subsection"><title>AUDIO_GET_CAPABILITIES</title>
 933 <para>DESCRIPTION
 934 </para>
 935 <informaltable><tgroup cols="1"><tbody><row><entry
 936  align="char">
 937 <para>This ioctl call asks the Audio Device to tell us about the decoding capabilities
 938  of the audio hardware.</para>
 939 </entry>
 940  </row></tbody></tgroup></informaltable>
 941 <para>SYNOPSIS
 942 </para>
 943 <informaltable><tgroup cols="1"><tbody><row><entry
 944  align="char">
 945 <para>int ioctl(int fd, int request =
 946  AUDIO_GET_CAPABILITIES, unsigned int &#x22C6;cap);</para>
 947 </entry>
 948  </row></tbody></tgroup></informaltable>
 949 <para>PARAMETERS
 950 </para>
 951 <informaltable><tgroup cols="2"><tbody><row><entry
 952  align="char">
 953 <para>int fd</para>
 954 </entry><entry
 955  align="char">
 956 <para>File descriptor returned by a previous call to open().</para>
 957 </entry>
 958  </row><row><entry
 959  align="char">
 960 <para>int request</para>
 961 </entry><entry
 962  align="char">
 963 <para>Equals AUDIO_GET_CAPABILITIES for this
 964  command.</para>
 965 </entry>
 966  </row><row><entry
 967  align="char">
 968 <para>unsigned int *cap</para>
 969 </entry><entry
 970  align="char">
 971 <para>Returns a bit array of supported sound formats.</para>
 972 </entry>
 973  </row></tbody></tgroup></informaltable>
 974 &return-value-dvb;
 975
 976 </section><section id="AUDIO_CLEAR_BUFFER"
 977 role="subsection"><title>AUDIO_CLEAR_BUFFER</title>
 978 <para>DESCRIPTION
 979 </para>
 980 <informaltable><tgroup cols="1"><tbody><row><entry
 981  align="char">
 982 <para>This ioctl call asks the Audio Device to clear all software and hardware buffers
 983  of the audio decoder device.</para>
 984 </entry>
 985  </row></tbody></tgroup></informaltable>
 986 <para>SYNOPSIS
 987 </para>
 988 <informaltable><tgroup cols="1"><tbody><row><entry
 989  align="char">
 990 <para>int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER);</para>
 991 </entry>
 992  </row></tbody></tgroup></informaltable>
 993 <para>PARAMETERS
 994 </para>
 995 <informaltable><tgroup cols="2"><tbody><row><entry
 996  align="char">
 997 <para>int fd</para>
 998 </entry><entry
 999  align="char">
1000 <para>File descriptor returned by a previous call to open().</para>
1001 </entry>
1002  </row><row><entry
1003  align="char">
1004 <para>int request</para>
1005 </entry><entry
1006  align="char">
1007 <para>Equals AUDIO_CLEAR_BUFFER for this command.</para>
1008 </entry>
1009  </row></tbody></tgroup></informaltable>
1010 &return-value-dvb;
1011
1012 </section><section id="AUDIO_SET_ID"
1013 role="subsection"><title>AUDIO_SET_ID</title>
1014 <para>DESCRIPTION
1015 </para>
1016 <informaltable><tgroup cols="1"><tbody><row><entry
1017  align="char">
1018 <para>This ioctl selects which sub-stream is to be decoded if a program or system
1019  stream is sent to the video device. If no audio stream type is set the id has to be
1020  in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7]
1021  for LPCM. More specifications may follow for other stream types. If the stream
1022  type is set the id just specifies the substream id of the audio stream and only
1023  the first 5 bits are recognized.</para>
1024 </entry>
1025  </row></tbody></tgroup></informaltable>
1026 <para>SYNOPSIS
1027 </para>
1028 <informaltable><tgroup cols="1"><tbody><row><entry
1029  align="char">
1030 <para>int ioctl(int fd, int request = AUDIO_SET_ID, int
1031  id);</para>
1032 </entry>
1033  </row></tbody></tgroup></informaltable>
1034 <para>PARAMETERS
1035 </para>
1036 <informaltable><tgroup cols="2"><tbody><row><entry
1037  align="char">
1038 <para>int fd</para>
1039 </entry><entry
1040  align="char">
1041 <para>File descriptor returned by a previous call to open().</para>
1042 </entry>
1043  </row><row><entry
1044  align="char">
1045 <para>int request</para>
1046 </entry><entry
1047  align="char">
1048 <para>Equals AUDIO_SET_ID for this command.</para>
1049 </entry>
1050  </row><row><entry
1051  align="char">
1052 <para>int id</para>
1053 </entry><entry
1054  align="char">
1055 <para>audio sub-stream id</para>
1056 </entry>
1057  </row></tbody></tgroup></informaltable>
1058 &return-value-dvb;
1059
1060 </section><section id="AUDIO_SET_MIXER"
1061 role="subsection"><title>AUDIO_SET_MIXER</title>
1062 <para>DESCRIPTION
1063 </para>
1064 <informaltable><tgroup cols="1"><tbody><row><entry
1065  align="char">
1066 <para>This ioctl lets you adjust the mixer settings of the audio decoder.</para>
1067 </entry>
1068  </row></tbody></tgroup></informaltable>
1069 <para>SYNOPSIS
1070 </para>
1071 <informaltable><tgroup cols="1"><tbody><row><entry
1072  align="char">
1073 <para>int ioctl(int fd, int request = AUDIO_SET_MIXER,
1074  audio_mixer_t &#x22C6;mix);</para>
1075 </entry>
1076  </row></tbody></tgroup></informaltable>
1077 <para>PARAMETERS
1078 </para>
1079 <informaltable><tgroup cols="2"><tbody><row><entry
1080  align="char">
1081 <para>int fd</para>
1082 </entry><entry
1083  align="char">
1084 <para>File descriptor returned by a previous call to open().</para>
1085 </entry>
1086  </row><row><entry
1087  align="char">
1088 <para>int request</para>
1089 </entry><entry
1090  align="char">
1091 <para>Equals AUDIO_SET_ID for this command.</para>
1092 </entry>
1093  </row><row><entry
1094  align="char">
1095 <para>audio_mixer_t *mix</para>
1096 </entry><entry
1097  align="char">
1098 <para>mixer settings.</para>
1099 </entry>
1100  </row></tbody></tgroup></informaltable>
1101 &return-value-dvb;
1102
1103 </section><section id="AUDIO_SET_STREAMTYPE"
1104 role="subsection"><title>AUDIO_SET_STREAMTYPE</title>
1105 <para>DESCRIPTION
1106 </para>
1107 <informaltable><tgroup cols="1"><tbody><row><entry
1108  align="char">
1109 <para>This ioctl tells the driver which kind of audio stream to expect. This is useful
1110  if the stream offers several audio sub-streams like LPCM and AC3.</para>
1111 </entry>
1112  </row></tbody></tgroup></informaltable>
1113 <para>SYNOPSIS
1114 </para>
1115 <informaltable><tgroup cols="1"><tbody><row><entry
1116  align="char">
1117 <para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE,
1118  int type);</para>
1119 </entry>
1120  </row></tbody></tgroup></informaltable>
1121 <para>PARAMETERS
1122 </para>
1123 <informaltable><tgroup cols="2"><tbody><row><entry
1124  align="char">
1125 <para>int fd</para>
1126 </entry><entry
1127  align="char">
1128 <para>File descriptor returned by a previous call to open().</para>
1129 </entry>
1130  </row><row><entry
1131  align="char">
1132 <para>int request</para>
1133 </entry><entry
1134  align="char">
1135 <para>Equals AUDIO_SET_STREAMTYPE for this
1136  command.</para>
1137 </entry>
1138  </row><row><entry
1139  align="char">
1140 <para>int type</para>
1141 </entry><entry
1142  align="char">
1143 <para>stream type</para>
1144 </entry>
1145  </row></tbody></tgroup></informaltable>
1146 &return-value-dvb;
1147 <informaltable><tgroup cols="2"><tbody><row><entry
1148  align="char">
1149 <para>EINVAL</para>
1150 </entry><entry
1151  align="char">
1152 <para>type is not a valid or supported stream type.</para>
1153 </entry>
1154  </row></tbody></tgroup></informaltable>
1155
1156 </section><section id="AUDIO_SET_EXT_ID"
1157 role="subsection"><title>AUDIO_SET_EXT_ID</title>
1158 <para>DESCRIPTION
1159 </para>
1160 <informaltable><tgroup cols="1"><tbody><row><entry
1161  align="char">
1162 <para>This ioctl can be used to set the extension id for MPEG streams in DVD
1163  playback. Only the first 3 bits are recognized.</para>
1164 </entry>
1165  </row></tbody></tgroup></informaltable>
1166 <para>SYNOPSIS
1167 </para>
1168 <informaltable><tgroup cols="1"><tbody><row><entry
1169  align="char">
1170 <para>int ioctl(fd, int request = AUDIO_SET_EXT_ID, int
1171  id);</para>
1172 </entry>
1173  </row></tbody></tgroup></informaltable>
1174 <para>PARAMETERS
1175 </para>
1176 <informaltable><tgroup cols="2"><tbody><row><entry
1177  align="char">
1178 <para>int fd</para>
1179 </entry><entry
1180  align="char">
1181 <para>File descriptor returned by a previous call to open().</para>
1182 </entry>
1183  </row><row><entry
1184  align="char">
1185 <para>int request</para>
1186 </entry><entry
1187  align="char">
1188 <para>Equals AUDIO_SET_EXT_ID for this command.</para>
1189 </entry>
1190  </row><row><entry
1191  align="char">
1192 <para>int id</para>
1193 </entry><entry
1194  align="char">
1195 <para>audio sub_stream_id</para>
1196 </entry>
1197  </row></tbody></tgroup></informaltable>
1198 &return-value-dvb;
1199 <informaltable><tgroup cols="2"><tbody><row><entry
1200  align="char">
1201 <para>EINVAL</para>
1202 </entry><entry
1203  align="char">
1204 <para>id is not a valid id.</para>
1205 </entry>
1206  </row></tbody></tgroup></informaltable>
1207
1208 </section><section id="AUDIO_SET_ATTRIBUTES"
1209 role="subsection"><title>AUDIO_SET_ATTRIBUTES</title>
1210 <para>DESCRIPTION
1211 </para>
1212 <informaltable><tgroup cols="1"><tbody><row><entry
1213  align="char">
1214 <para>This ioctl is intended for DVD playback and allows you to set certain
1215  information about the audio stream.</para>
1216 </entry>
1217  </row></tbody></tgroup></informaltable>
1218 <para>SYNOPSIS
1219 </para>
1220 <informaltable><tgroup cols="1"><tbody><row><entry
1221  align="char">
1222 <para>int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES,
1223  audio_attributes_t attr );</para>
1224 </entry>
1225  </row></tbody></tgroup></informaltable>
1226 <para>PARAMETERS
1227 </para>
1228 <informaltable><tgroup cols="2"><tbody><row><entry
1229  align="char">
1230 <para>int fd</para>
1231 </entry><entry
1232  align="char">
1233 <para>File descriptor returned by a previous call to open().</para>
1234 </entry>
1235  </row><row><entry
1236  align="char">
1237 <para>int request</para>
1238 </entry><entry
1239  align="char">
1240 <para>Equals AUDIO_SET_ATTRIBUTES for this command.</para>
1241 </entry>
1242  </row><row><entry
1243  align="char">
1244 <para>audio_attributes_t
1245  attr</para>
1246 </entry><entry
1247  align="char">
1248 <para>audio attributes according to section ??</para>
1249 </entry>
1250  </row></tbody></tgroup></informaltable>
1251 &return-value-dvb;
1252 <informaltable><tgroup cols="2"><tbody><row><entry
1253  align="char">
1254 <para>EINVAL</para>
1255 </entry><entry
1256  align="char">
1257 <para>attr is not a valid or supported attribute setting.</para>
1258 </entry>
1259  </row></tbody></tgroup></informaltable>
1260
1261 </section><section id="AUDIO_SET_KARAOKE"
1262 role="subsection"><title>AUDIO_SET_KARAOKE</title>
1263 <para>DESCRIPTION
1264 </para>
1265 <informaltable><tgroup cols="1"><tbody><row><entry
1266  align="char">
1267 <para>This ioctl allows one to set the mixer settings for a karaoke DVD.</para>
1268 </entry>
1269  </row></tbody></tgroup></informaltable>
1270 <para>SYNOPSIS
1271 </para>
1272 <informaltable><tgroup cols="1"><tbody><row><entry
1273  align="char">
1274 <para>int ioctl(fd, int request = AUDIO_SET_KARAOKE,
1275  audio_karaoke_t &#x22C6;karaoke);</para>
1276 </entry>
1277  </row></tbody></tgroup></informaltable>
1278 <para>PARAMETERS
1279 </para>
1280 <informaltable><tgroup cols="2"><tbody><row><entry
1281  align="char">
1282 <para>int fd</para>
1283 </entry><entry
1284  align="char">
1285 <para>File descriptor returned by a previous call to open().</para>
1286 </entry>
1287  </row><row><entry
1288  align="char">
1289 <para>int request</para>
1290 </entry><entry
1291  align="char">
1292 <para>Equals AUDIO_SET_KARAOKE for this
1293  command.</para>
1294 </entry>
1295  </row><row><entry
1296  align="char">
1297 <para>audio_karaoke_t
1298  *karaoke</para>
1299 </entry><entry
1300  align="char">
1301 <para>karaoke settings according to section ??.</para>
1302 </entry>
1303  </row></tbody></tgroup></informaltable>
1304 &return-value-dvb;
1305 <informaltable><tgroup cols="2"><tbody><row><entry
1306  align="char">
1307 <para>EINVAL</para>
1308 </entry><entry
1309  align="char">
1310 <para>karaoke is not a valid or supported karaoke setting.</para>
1311 </entry>
1312  </row></tbody></tgroup></informaltable>
1313  </section>
1314 </section>