1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0
2
3 .. c:namespace:: dtv.legacy.audio
4
5 .. _dvb_audio:
6
7 ================
8 DVB Audio Device
9 ================
10
11 .. attention:: Do **not** use in new drivers!
12 See: :ref:`legacy_dvb_decoder_notes`
13
14 The DVB audio device controls the MPEG2 audio decoder of the DVB
15 hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data
16 types and ioctl definitions can be accessed by including
17 ``linux/dvb/audio.h`` in your application.
18
19 Please note that most DVB cards don’t have their own MPEG decoder, which
20 results in the omission of the audio and video device.
21
22 These ioctls were also used by V4L2 to control MPEG decoders implemented
23 in V4L2. The use of these ioctls for that purpose has been made obsolete
24 and proper V4L2 ioctls or controls have been created to replace that
25 functionality. Use :ref:`V4L2 ioctls<audio>` for new drivers!
26
27
28 Audio Data Types
29 ================
30
31 This section describes the structures, data types and defines used when
32 talking to the audio device.
33
34
35 -----
36
37
38 audio_stream_source_t
39 ---------------------
40
41 Synopsis
42 ~~~~~~~~
43
44 .. c:enum:: audio_stream_source_t
45
46 .. code-block:: c
47
48 typedef enum {
49 AUDIO_SOURCE_DEMUX,
50 AUDIO_SOURCE_MEMORY
51 } audio_stream_source_t;
52
53 Constants
54 ~~~~~~~~~
55
56 .. flat-table::
57 :header-rows: 0
58 :stub-columns: 0
59
60 - ..
61
62 - ``AUDIO_SOURCE_DEMUX``
63
64 - :cspan:`1` Selects the demultiplexer (fed either by the frontend
65 or the DVR device) as the source of the video stream.
66
67 - ..
68
69 - ``AUDIO_SOURCE_MEMORY``
70
71 - Selects the stream from the application that comes through
72 the `write()`_ system call.
73
74 Description
75 ~~~~~~~~~~~
76
77 The audio stream source is set through the `AUDIO_SELECT_SOURCE`_ call
78 and can take the following values, depending on whether we are replaying
79 from an internal (demux) or external (user write) source.
80
81 The data fed to the decoder is also controlled by the PID-filter.
82 Output selection: :c:type:`dmx_output` ``DMX_OUT_DECODER``.
83
84
85 -----
86
87
88 audio_play_state_t
89 ------------------
90
91 Synopsis
92 ~~~~~~~~
93
94 .. c:enum:: audio_play_state_t
95
96 .. code-block:: c
97
98 typedef enum {
99 AUDIO_STOPPED,
100 AUDIO_PLAYING,
101 AUDIO_PAUSED
102 } audio_play_state_t;
103
104 Constants
105 ~~~~~~~~~
106
107 .. flat-table::
108 :header-rows: 0
109 :stub-columns: 0
110
111 - ..
112
113 - ``AUDIO_STOPPED``
114
115 - Audio is stopped.
116
117 - ..
118
119 - ``AUDIO_PLAYING``
120
121 - Audio is currently playing.
122
123 - ..
124
125 - ``AUDIO_PAUSE``
126
127 - Audio is frozen.
128
129 Description
130 ~~~~~~~~~~~
131
132 This values can be returned by the `AUDIO_GET_STATUS`_ call
133 representing the state of audio playback.
134
135
136 -----
137
138
139 audio_channel_select_t
140 ----------------------
141
142 Synopsis
143 ~~~~~~~~
144
145 .. c:enum:: audio_channel_select_t
146
147 .. code-block:: c
148
149 typedef enum {
150 AUDIO_STEREO,
151 AUDIO_MONO_LEFT,
152 AUDIO_MONO_RIGHT,
153 AUDIO_MONO,
154 AUDIO_STEREO_SWAPPED
155 } audio_channel_select_t;
156
157 Constants
158 ~~~~~~~~~
159
160 .. flat-table::
161 :header-rows: 0
162 :stub-columns: 0
163
164 - ..
165
166 - ``AUDIO_STEREO``
167
168 - Stereo.
169
170 - ..
171
172 - ``AUDIO_MONO_LEFT``
173
174 - Mono, select left stereo channel as source.
175
176 - ..
177
178 - ``AUDIO_MONO_RIGHT``
179
180 - Mono, select right stereo channel as source.
181
182 - ..
183
184 - ``AUDIO_MONO``
185
186 - Mono source only.
187
188 - ..
189
190 - ``AUDIO_STEREO_SWAPPED``
191
192 - Stereo, swap L & R.
193
194 Description
195 ~~~~~~~~~~~
196
197 The audio channel selected via `AUDIO_CHANNEL_SELECT`_ is determined by
198 this values.
199
200
201 -----
202
203
204 audio_mixer_t
205 -------------
206
207 Synopsis
208 ~~~~~~~~
209
210 .. c:struct:: audio_mixer
211
212 .. code-block:: c
213
214 typedef struct audio_mixer {
215 unsigned int volume_left;
216 unsigned int volume_right;
217 } audio_mixer_t;
218
219 Variables
220 ~~~~~~~~~
221
222 .. flat-table::
223 :header-rows: 0
224 :stub-columns: 0
225
226 - ..
227
228 - ``unsigned int volume_left``
229
230 - Volume left channel.
231 Valid range: 0 ... 255
232
233 - ..
234
235 - ``unsigned int volume_right``
236
237 - Volume right channel.
238 Valid range: 0 ... 255
239
240 Description
241 ~~~~~~~~~~~
242
243 This structure is used by the `AUDIO_SET_MIXER`_ call to set the
244 audio volume.
245
246
247 -----
248
249
250 audio_status
251 ------------
252
253 Synopsis
254 ~~~~~~~~
255
256 .. c:struct:: audio_status
257
258 .. code-block:: c
259
260 typedef struct audio_status {
261 int AV_sync_state;
262 int mute_state;
263 audio_play_state_t play_state;
264 audio_stream_source_t stream_source;
265 audio_channel_select_t channel_select;
266 int bypass_mode;
267 audio_mixer_t mixer_state;
268 } audio_status_t;
269
270 Variables
271 ~~~~~~~~~
272
273 .. flat-table::
274 :header-rows: 0
275 :stub-columns: 0
276
277 - ..
278
279 - :rspan:`2` ``int AV_sync_state``
280
281 - :cspan:`1` Shows if A/V synchronization is ON or OFF.
282
283 - ..
284
285 - TRUE ( != 0 )
286
287 - AV-sync ON.
288
289 - ..
290
291 - FALSE ( == 0 )
292
293 - AV-sync OFF.
294
295 - ..
296
297 - :rspan:`2` ``int mute_state``
298
299 - :cspan:`1` Indicates if audio is muted or not.
300
301 - ..
302
303 - TRUE ( != 0 )
304
305 - mute audio
306
307 - ..
308
309 - FALSE ( == 0 )
310
311 - unmute audio
312
313 - ..
314
315 - `audio_play_state_t`_ ``play_state``
316
317 - Current playback state.
318
319 - ..
320
321 - `audio_stream_source_t`_ ``stream_source``
322
323 - Current source of the data.
324
325 - ..
326
327 - :rspan:`2` ``int bypass_mode``
328
329 - :cspan:`1` Is the decoding of the current Audio stream in
330 the DVB subsystem enabled or disabled.
331
332 - ..
333
334 - TRUE ( != 0 )
335
336 - Bypass disabled.
337
338 - ..
339
340 - FALSE ( == 0 )
341
342 - Bypass enabled.
343
344 - ..
345
346 - `audio_mixer_t`_ ``mixer_state``
347
348 - Current volume settings.
349
350 Description
351 ~~~~~~~~~~~
352
353 The `AUDIO_GET_STATUS`_ call returns this structure as information
354 about various states of the playback operation.
355
356
357 -----
358
359
360 audio encodings
361 ---------------
362
363 Synopsis
364 ~~~~~~~~
365
366 .. code-block:: c
367
368 #define AUDIO_CAP_DTS 1
369 #define AUDIO_CAP_LPCM 2
370 #define AUDIO_CAP_MP1 4
371 #define AUDIO_CAP_MP2 8
372 #define AUDIO_CAP_MP3 16
373 #define AUDIO_CAP_AAC 32
374 #define AUDIO_CAP_OGG 64
375 #define AUDIO_CAP_SDDS 128
376 #define AUDIO_CAP_AC3 256
377
378 Constants
379 ~~~~~~~~~
380
381 .. flat-table::
382 :header-rows: 0
383 :stub-columns: 0
384
385 - ..
386
387 - ``AUDIO_CAP_DTS``
388
389 - :cspan:`1` The hardware accepts DTS audio tracks.
390
391 - ..
392
393 - ``AUDIO_CAP_LPCM``
394
395 - The hardware accepts uncompressed audio with
396 Linear Pulse-Code Modulation (LPCM)
397
398 - ..
399
400 - ``AUDIO_CAP_MP1``
401
402 - The hardware accepts MPEG-1 Audio Layer 1.
403
404 - ..
405
406 - ``AUDIO_CAP_MP2``
407
408 - The hardware accepts MPEG-1 Audio Layer 2.
409 Also known as MUSICAM.
410
411 - ..
412
413 - ``AUDIO_CAP_MP3``
414
415 - The hardware accepts MPEG-1 Audio Layer III.
416 Commomly known as .mp3.
417
418 - ..
419
420 - ``AUDIO_CAP_AAC``
421
422 - The hardware accepts AAC (Advanced Audio Coding).
423
424 - ..
425
426 - ``AUDIO_CAP_OGG``
427
428 - The hardware accepts Vorbis audio tracks.
429
430 - ..
431
432 - ``AUDIO_CAP_SDDS``
433
434 - The hardware accepts Sony Dynamic Digital Sound (SDDS).
435
436 - ..
437
438 - ``AUDIO_CAP_AC3``
439
440 - The hardware accepts Dolby Digital ATSC A/52 audio.
441 Also known as AC-3.
442
443 Description
444 ~~~~~~~~~~~
445
446 A call to `AUDIO_GET_CAPABILITIES`_ returns an unsigned integer with the
447 following bits set according to the hardwares capabilities.
448
449
450 -----
451
452
453 Audio Function Calls
454 ====================
455
456
457 AUDIO_STOP
458 ----------
459
460 Synopsis
461 ~~~~~~~~
462
463 .. c:macro:: AUDIO_STOP
464
465 .. code-block:: c
466
467 int ioctl(int fd, int request = AUDIO_STOP)
468
469 Arguments
470 ~~~~~~~~~
471
472 .. flat-table::
473 :header-rows: 0
474 :stub-columns: 0
475
476 - ..
477
478 - ``int fd``
479
480 - File descriptor returned by a previous call to `open()`_.
481
482 - ..
483
484 - ``int request``
485
486 - :cspan:`1` Equals ``AUDIO_STOP`` for this command.
487
488 Description
489 ~~~~~~~~~~~
490
491 .. attention:: Do **not** use in new drivers!
492 See: :ref:`legacy_dvb_decoder_notes`
493
494 This ioctl call asks the Audio Device to stop playing the current
495 stream.
496
497 Return Value
498 ~~~~~~~~~~~~
499
500 On success 0 is returned, on error -1 and the ``errno`` variable is set
501 appropriately. The generic error codes are described at the
502 :ref:`Generic Error Codes <gen-errors>` chapter.
503
504
505 -----
506
507
508 AUDIO_PLAY
509 ----------
510
511 Synopsis
512 ~~~~~~~~
513
514 .. c:macro:: AUDIO_PLAY
515
516 .. code-block:: c
517
518 int ioctl(int fd, int request = AUDIO_PLAY)
519
520 Arguments
521 ~~~~~~~~~
522
523 .. flat-table::
524 :header-rows: 0
525 :stub-columns: 0
526
527 - ..
528
529 - ``int fd``
530
531 - File descriptor returned by a previous call to `open()`_.
532
533 - ..
534
535 - ``int request``
536
537 - :cspan:`1` Equals ``AUDIO_PLAY`` for this command.
538
539 Description
540 ~~~~~~~~~~~
541
542 .. attention:: Do **not** use in new drivers!
543 See: :ref:`legacy_dvb_decoder_notes`
544
545 This ioctl call asks the Audio Device to start playing an audio stream
546 from the selected source.
547
548 Return Value
549 ~~~~~~~~~~~~
550
551 On success 0 is returned, on error -1 and the ``errno`` variable is set
552 appropriately. The generic error codes are described at the
553 :ref:`Generic Error Codes <gen-errors>` chapter.
554
555
556 -----
557
558
559 AUDIO_PAUSE
560 -----------
561
562 Synopsis
563 ~~~~~~~~
564
565 .. c:macro:: AUDIO_PAUSE
566
567 .. code-block:: c
568
569 int ioctl(int fd, int request = AUDIO_PAUSE)
570
571 Arguments
572 ~~~~~~~~~
573
574 .. flat-table::
575 :header-rows: 0
576 :stub-columns: 0
577
578 - ..
579
580 - ``int fd``
581
582 - :cspan:`1` File descriptor returned by a previous call
583 to `open()`_.
584
585 - ..
586
587 - ``int request``
588
589 - Equals ``AUDIO_PAUSE`` for this command.
590
591 Description
592 ~~~~~~~~~~~
593
594 .. attention:: Do **not** use in new drivers!
595 See: :ref:`legacy_dvb_decoder_notes`
596
597 This ioctl call suspends the audio stream being played. Decoding and
598 playing are paused. It is then possible to restart again decoding and
599 playing process of the audio stream using `AUDIO_CONTINUE`_ command.
600
601 Return Value
602 ~~~~~~~~~~~~
603
604 On success 0 is returned, on error -1 and the ``errno`` variable is set
605 appropriately. The generic error codes are described at the
606 :ref:`Generic Error Codes <gen-errors>` chapter.
607
608
609 -----
610
611
612 AUDIO_CONTINUE
613 --------------
614
615 Synopsis
616 ~~~~~~~~
617
618 .. c:macro:: AUDIO_CONTINUE
619
620 .. code-block:: c
621
622 int ioctl(int fd, int request = AUDIO_CONTINUE)
623
624 Arguments
625 ~~~~~~~~~
626
627 .. flat-table::
628 :header-rows: 0
629 :stub-columns: 0
630
631 - ..
632
633 - ``int fd``
634
635 - :cspan:`1` File descriptor returned by a previous call
636 to `open()`_.
637
638 - ..
639
640 - ``int request``
641
642 - Equals ``AUDIO_CONTINUE`` for this command.
643
644 Description
645 ~~~~~~~~~~~
646
647 .. attention:: Do **not** use in new drivers!
648 See: :ref:`legacy_dvb_decoder_notes`
649
650 This ioctl restarts the decoding and playing process previously paused
651 with `AUDIO_PAUSE`_ command.
652
653 Return Value
654 ~~~~~~~~~~~~
655
656 On success 0 is returned, on error -1 and the ``errno`` variable is set
657 appropriately. The generic error codes are described at the
658 :ref:`Generic Error Codes <gen-errors>` chapter.
659
660
661 -----
662
663
664 AUDIO_SELECT_SOURCE
665 -------------------
666
667 Synopsis
668 ~~~~~~~~
669
670 .. c:macro:: AUDIO_SELECT_SOURCE
671
672 .. code-block:: c
673
674 int ioctl(int fd, int request = AUDIO_SELECT_SOURCE,
675 audio_stream_source_t source)
676
677 Arguments
678 ~~~~~~~~~
679
680 .. flat-table::
681 :header-rows: 0
682 :stub-columns: 0
683
684 - ..
685
686 - ``int fd``
687
688 - :cspan:`1` File descriptor returned by a previous call
689 to `open()`_.
690
691 - ..
692
693 - ``int request``
694
695 - Equals ``AUDIO_SELECT_SOURCE`` for this command.
696
697 - ..
698
699 - `audio_stream_source_t`_ ``source``
700
701 - Indicates the source that shall be used for the Audio stream.
702
703 Description
704 ~~~~~~~~~~~
705
706 .. attention:: Do **not** use in new drivers!
707 See: :ref:`legacy_dvb_decoder_notes`
708
709 This ioctl call informs the audio device which source shall be used for
710 the input data. The possible sources are demux or memory. If
711 ``AUDIO_SOURCE_MEMORY`` is selected, the data is fed to the Audio Device
712 through the write command. If ``AUDIO_SOURCE_DEMUX`` is selected, the data
713 is directly transferred from the onboard demux-device to the decoder.
714 Note: This only supports DVB-devices with one demux and one decoder so far.
715
716 Return Value
717 ~~~~~~~~~~~~
718
719 On success 0 is returned, on error -1 and the ``errno`` variable is set
720 appropriately. The generic error codes are described at the
721 :ref:`Generic Error Codes <gen-errors>` chapter.
722
723
724 -----
725
726
727 AUDIO_SET_MUTE
728 --------------
729
730 Synopsis
731 ~~~~~~~~
732
733 .. c:macro:: AUDIO_SET_MUTE
734
735 .. code-block:: c
736
737 int ioctl(int fd, int request = AUDIO_SET_MUTE, int state)
738
739 Arguments
740 ~~~~~~~~~
741
742 .. flat-table::
743 :header-rows: 0
744 :stub-columns: 0
745
746 - ..
747
748 - ``int fd``
749
750 - :cspan:`1` File descriptor returned by a previous call
751 to `open()`_.
752
753 - ..
754
755 - ``int request``
756
757 - :cspan:`1` Equals ``AUDIO_SET_MUTE`` for this command.
758
759 - ..
760
761 - :rspan:`2` ``int state``
762
763 - :cspan:`1` Indicates if audio device shall mute or not.
764
765 - ..
766
767 - TRUE ( != 0 )
768
769 - mute audio
770
771 - ..
772
773 - FALSE ( == 0 )
774
775 - unmute audio
776
777 Description
778 ~~~~~~~~~~~
779
780 .. attention:: Do **not** use in new drivers!
781 See: :ref:`legacy_dvb_decoder_notes`
782
783 This ioctl is for DVB devices only. To control a V4L2 decoder use the
784 V4L2 :ref:`VIDIOC_DECODER_CMD` with the
785 ``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead.
786
787 This ioctl call asks the audio device to mute the stream that is
788 currently being played.
789
790 Return Value
791 ~~~~~~~~~~~~
792
793 On success 0 is returned, on error -1 and the ``errno`` variable is set
794 appropriately. The generic error codes are described at the
795 :ref:`Generic Error Codes <gen-errors>` chapter.
796
797
798 -----
799
800
801 AUDIO_SET_AV_SYNC
802 -----------------
803
804 Synopsis
805 ~~~~~~~~
806
807 .. c:macro:: AUDIO_SET_AV_SYNC
808
809 .. code-block:: c
810
811 int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, int state)
812
813 Arguments
814 ~~~~~~~~~
815
816 .. flat-table::
817 :header-rows: 0
818 :stub-columns: 0
819
820 - ..
821
822 - ``int fd``
823
824 - :cspan:`1` File descriptor returned by a previous call
825 to `open()`_.
826
827 - ..
828
829 - ``int request``
830
831 - :cspan:`1` Equals ``AUDIO_AV_SYNC`` for this command.
832
833 - ..
834
835 - :rspan:`2` ``int state``
836
837 - :cspan:`1` Tells the DVB subsystem if A/V synchronization
838 shall be ON or OFF.
839
840 - ..
841
842 - TRUE ( != 0 )
843
844 - AV-sync ON.
845
846 - ..
847
848 - FALSE ( == 0 )
849
850 - AV-sync OFF.
851
852 Description
853 ~~~~~~~~~~~
854
855 .. attention:: Do **not** use in new drivers!
856 See: :ref:`legacy_dvb_decoder_notes`
857
858 This ioctl call asks the Audio Device to turn ON or OFF A/V
859 synchronization.
860
861 Return Value
862 ~~~~~~~~~~~~
863
864 On success 0 is returned, on error -1 and the ``errno`` variable is set
865 appropriately. The generic error codes are described at the
866 :ref:`Generic Error Codes <gen-errors>` chapter.
867
868
869 -----
870
871
872 AUDIO_SET_BYPASS_MODE
873 ---------------------
874
875 Synopsis
876 ~~~~~~~~
877
878 .. c:macro:: AUDIO_SET_BYPASS_MODE
879
880 .. code-block:: c
881
882 int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, int mode)
883
884 Arguments
885 ~~~~~~~~~
886
887 .. flat-table::
888 :header-rows: 0
889 :stub-columns: 0
890
891 - ..
892
893 - ``int fd``
894
895 - :cspan:`1` File descriptor returned by a previous call
896 to `open()`_.
897
898 - ..
899
900 - ``int request``
901
902 - :cspan:`1` Equals ``AUDIO_SET_BYPASS_MODE`` for this command.
903
904 - ..
905
906 - :rspan:`2` ``int mode``
907
908 - :cspan:`1` Enables or disables the decoding of the current
909 Audio stream in the DVB subsystem.
910 - ..
911
912 - TRUE ( != 0 )
913
914 - Disable bypass
915
916 - ..
917
918 - FALSE ( == 0 )
919
920 - Enable bypass
921
922 Description
923 ~~~~~~~~~~~
924
925 .. attention:: Do **not** use in new drivers!
926 See: :ref:`legacy_dvb_decoder_notes`
927
928 This ioctl call asks the Audio Device to bypass the Audio decoder and
929 forward the stream without decoding. This mode shall be used if streams
930 that can’t be handled by the DVB system shall be decoded. Dolby
931 DigitalTM streams are automatically forwarded by the DVB subsystem if
932 the hardware can handle it.
933
934 Return Value
935 ~~~~~~~~~~~~
936
937 On success 0 is returned, on error -1 and the ``errno`` variable is set
938 appropriately. The generic error codes are described at the
939 :ref:`Generic Error Codes <gen-errors>` chapter.
940
941
942 -----
943
944
945 AUDIO_CHANNEL_SELECT
946 --------------------
947
948 Synopsis
949 ~~~~~~~~
950
951 .. c:macro:: AUDIO_CHANNEL_SELECT
952
953 .. code-block:: c
954
955 int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT,
956 audio_channel_select_t)
957
958 Arguments
959 ~~~~~~~~~
960
961 .. flat-table::
962 :header-rows: 0
963 :stub-columns: 0
964
965 - ..
966
967 - ``int fd``
968
969 - :cspan:`1` File descriptor returned by a previous call
970 to `open()`_.
971
972 - ..
973
974 - ``int request``
975
976 - Equals ``AUDIO_CHANNEL_SELECT`` for this command.
977
978 - ..
979
980 - `audio_channel_select_t`_ ``ch``
981
982 - Select the output format of the audio (mono left/right, stereo).
983
984 Description
985 ~~~~~~~~~~~
986
987 .. attention:: Do **not** use in new drivers!
988 See: :ref:`legacy_dvb_decoder_notes`
989
990 This ioctl is for DVB devices only. To control a V4L2 decoder use the
991 V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead.
992
993 This ioctl call asks the Audio Device to select the requested channel if
994 possible.
995
996 Return Value
997 ~~~~~~~~~~~~
998
999 On success 0 is returned, on error -1 and the ``errno`` variable is set
1000 appropriately. The generic error codes are described at the
1001 :ref:`Generic Error Codes <gen-errors>` chapter.
1002
1003
1004 -----
1005
1006
1007 AUDIO_GET_STATUS
1008 ----------------
1009
1010 Synopsis
1011 ~~~~~~~~
1012
1013 .. c:macro:: AUDIO_GET_STATUS
1014
1015 .. code-block:: c
1016
1017 int ioctl(int fd, int request = AUDIO_GET_STATUS,
1018 struct audio_status *status)
1019
1020 Arguments
1021 ~~~~~~~~~
1022
1023 .. flat-table::
1024 :header-rows: 0
1025 :stub-columns: 0
1026
1027 - ..
1028
1029 - ``int fd``
1030
1031 - :cspan:`1` File descriptor returned by a previous call
1032 to `open()`_.
1033
1034 - ..
1035
1036 - ``int request``
1037
1038 - Equals AUDIO_GET_STATUS for this command.
1039
1040 - ..
1041
1042 - ``struct`` `audio_status`_ ``*status``
1043
1044 - Returns the current state of Audio Device.
1045
1046 Description
1047 ~~~~~~~~~~~
1048
1049 .. attention:: Do **not** use in new drivers!
1050 See: :ref:`legacy_dvb_decoder_notes`
1051
1052 This ioctl call asks the Audio Device to return the current state of the
1053 Audio Device.
1054
1055 Return Value
1056 ~~~~~~~~~~~~
1057
1058 On success 0 is returned, on error -1 and the ``errno`` variable is set
1059 appropriately. The generic error codes are described at the
1060 :ref:`Generic Error Codes <gen-errors>` chapter.
1061
1062
1063 -----
1064
1065
1066 AUDIO_GET_CAPABILITIES
1067 ----------------------
1068
1069 Synopsis
1070 ~~~~~~~~
1071
1072 .. c:macro:: AUDIO_GET_CAPABILITIES
1073
1074 .. code-block:: c
1075
1076 int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES,
1077 unsigned int *cap)
1078
1079 Arguments
1080 ~~~~~~~~~
1081
1082 .. flat-table::
1083 :header-rows: 0
1084 :stub-columns: 0
1085
1086 - ..
1087
1088 - ``int fd``
1089
1090 - :cspan:`1` File descriptor returned by a previous call
1091 to `open()`_.
1092
1093 - ..
1094
1095 - ``int request``
1096
1097 - Equals ``AUDIO_GET_CAPABILITIES`` for this command.
1098
1099 - ..
1100
1101 - ``unsigned int *cap``
1102
1103 - Returns a bit array of supported sound formats.
1104 Bits are defined in `audio encodings`_.
1105
1106 Description
1107 ~~~~~~~~~~~
1108
1109 .. attention:: Do **not** use in new drivers!
1110 See: :ref:`legacy_dvb_decoder_notes`
1111
1112 This ioctl call asks the Audio Device to tell us about the decoding
1113 capabilities of the audio hardware.
1114
1115 Return Value
1116 ~~~~~~~~~~~~
1117
1118 On success 0 is returned, on error -1 and the ``errno`` variable is set
1119 appropriately. The generic error codes are described at the
1120 :ref:`Generic Error Codes <gen-errors>` chapter.
1121
1122
1123 -----
1124
1125
1126 AUDIO_CLEAR_BUFFER
1127 ------------------
1128
1129 Synopsis
1130 ~~~~~~~~
1131
1132 .. c:macro:: AUDIO_CLEAR_BUFFER
1133
1134 .. code-block:: c
1135
1136 int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER)
1137
1138 Arguments
1139 ~~~~~~~~~
1140
1141 .. flat-table::
1142 :header-rows: 0
1143 :stub-columns: 0
1144
1145 - ..
1146
1147 - ``int fd``
1148
1149 - :cspan:`1` File descriptor returned by a previous call
1150 to `open()`_.
1151
1152 - ..
1153
1154 - ``int request``
1155
1156 - Equals ``AUDIO_CLEAR_BUFFER`` for this command.
1157
1158 Description
1159 ~~~~~~~~~~~
1160
1161 .. attention:: Do **not** use in new drivers!
1162 See: :ref:`legacy_dvb_decoder_notes`
1163
1164 This ioctl call asks the Audio Device to clear all software and hardware
1165 buffers of the audio decoder device.
1166
1167 Return Value
1168 ~~~~~~~~~~~~
1169
1170 On success 0 is returned, on error -1 and the ``errno`` variable is set
1171 appropriately. The generic error codes are described at the
1172 :ref:`Generic Error Codes <gen-errors>` chapter.
1173
1174
1175 -----
1176
1177
1178 AUDIO_SET_ID
1179 ------------
1180
1181 Synopsis
1182 ~~~~~~~~
1183
1184 .. c:macro:: AUDIO_SET_ID
1185
1186 .. code-block:: c
1187
1188 int ioctl(int fd, int request = AUDIO_SET_ID, int id)
1189
1190 Arguments
1191 ~~~~~~~~~
1192
1193 .. flat-table::
1194 :header-rows: 0
1195 :stub-columns: 0
1196
1197 - ..
1198
1199 - ``int fd``
1200
1201 - :cspan:`1` File descriptor returned by a previous call
1202 to `open()`_.
1203
1204 - ..
1205
1206 - ``int request``
1207
1208 - Equals ``AUDIO_SET_ID`` for this command.
1209
1210 - ..
1211
1212 - ``int id``
1213
1214 - Audio sub-stream id.
1215
1216 Description
1217 ~~~~~~~~~~~
1218
1219 .. attention:: Do **not** use in new drivers!
1220 See: :ref:`legacy_dvb_decoder_notes`
1221
1222 This ioctl selects which sub-stream is to be decoded if a program or
1223 system stream is sent to the video device.
1224
1225 If no audio stream type is set the id has to be in range [0xC0,0xDF]
1226 for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7] for LPCM.
1227 See ITU-T H.222.0 | ISO/IEC 13818-1 for further description.
1228
1229 If the stream type is set with `AUDIO_SET_STREAMTYPE`_, specifies the
1230 id just the sub-stream id of the audio stream and only the first 5 bits
1231 (& 0x1F) are recognized.
1232
1233 Return Value
1234 ~~~~~~~~~~~~
1235
1236 On success 0 is returned, on error -1 and the ``errno`` variable is set
1237 appropriately. The generic error codes are described at the
1238 :ref:`Generic Error Codes <gen-errors>` chapter.
1239
1240
1241 -----
1242
1243
1244 AUDIO_SET_MIXER
1245 ---------------
1246
1247 Synopsis
1248 ~~~~~~~~
1249
1250 .. c:macro:: AUDIO_SET_MIXER
1251
1252 .. code-block:: c
1253
1254 int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix)
1255
1256 Arguments
1257 ~~~~~~~~~
1258
1259 .. flat-table::
1260 :header-rows: 0
1261 :stub-columns: 0
1262
1263 - ..
1264
1265 - ``int fd``
1266
1267 - :cspan:`1` File descriptor returned by a previous call
1268 to `open()`_.
1269
1270 - ..
1271
1272 - ``int request``
1273
1274 - Equals ``AUDIO_SET_MIXER`` for this command.
1275
1276 - ..
1277
1278 - ``audio_mixer_t *mix``
1279
1280 - Mixer settings.
1281
1282 Description
1283 ~~~~~~~~~~~
1284
1285 .. attention:: Do **not** use in new drivers!
1286 See: :ref:`legacy_dvb_decoder_notes`
1287
1288 This ioctl lets you adjust the mixer settings of the audio decoder.
1289
1290 Return Value
1291 ~~~~~~~~~~~~
1292
1293 On success 0 is returned, on error -1 and the ``errno`` variable is set
1294 appropriately. The generic error codes are described at the
1295 :ref:`Generic Error Codes <gen-errors>` chapter.
1296
1297
1298 -----
1299
1300
1301 AUDIO_SET_STREAMTYPE
1302 --------------------
1303
1304 Synopsis
1305 ~~~~~~~~
1306
1307 .. c:macro:: AUDIO_SET_STREAMTYPE
1308
1309 .. code-block:: c
1310
1311 int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type)
1312
1313 Arguments
1314 ~~~~~~~~~
1315
1316 .. flat-table::
1317 :header-rows: 0
1318 :stub-columns: 0
1319
1320 - ..
1321
1322 - ``int fd``
1323
1324 - :cspan:`1` File descriptor returned by a previous call
1325 to `open()`_.
1326
1327 - ..
1328
1329 - ``int request``
1330
1331 - Equals ``AUDIO_SET_STREAMTYPE`` for this command.
1332
1333 - ..
1334
1335 - ``int type``
1336
1337 - Stream type.
1338
1339 Description
1340 ~~~~~~~~~~~
1341
1342 .. attention:: Do **not** use in new drivers!
1343 See: :ref:`legacy_dvb_decoder_notes`
1344
1345 This ioctl tells the driver which kind of audio stream to expect. This
1346 is useful if the stream offers several audio sub-streams like LPCM and
1347 AC3.
1348
1349 Stream types defined in ITU-T H.222.0 | ISO/IEC 13818-1 are used.
1350
1351
1352 Return Value
1353 ~~~~~~~~~~~~
1354
1355 On success 0 is returned, on error -1 and the ``errno`` variable is set
1356 appropriately. The generic error codes are described at the
1357 :ref:`Generic Error Codes <gen-errors>` chapter.
1358
1359 .. flat-table::
1360 :header-rows: 0
1361 :stub-columns: 0
1362
1363 - ..
1364
1365 - ``EINVAL``
1366
1367 - Type is not a valid or supported stream type.
1368
1369
1370 -----
1371
1372
1373 AUDIO_BILINGUAL_CHANNEL_SELECT
1374 ------------------------------
1375
1376 Synopsis
1377 ~~~~~~~~
1378
1379 .. c:macro:: AUDIO_BILINGUAL_CHANNEL_SELECT
1380
1381 .. code-block:: c
1382
1383 int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT,
1384 audio_channel_select_t)
1385
1386 Arguments
1387 ~~~~~~~~~
1388
1389 .. flat-table::
1390 :header-rows: 0
1391 :stub-columns: 0
1392
1393 - ..
1394
1395 - ``int fd``
1396
1397 - :cspan:`1` File descriptor returned by a previous call
1398 to `open()`_.
1399
1400 - ..
1401
1402 - ``int request``
1403
1404 - Equals ``AUDIO_BILINGUAL_CHANNEL_SELECT`` for this command.
1405
1406 - ..
1407
1408 - ``audio_channel_select_t ch``
1409
1410 - Select the output format of the audio (mono left/right, stereo).
1411
1412 Description
1413 ~~~~~~~~~~~
1414
1415 .. attention:: Do **not** use in new drivers!
1416 See: :ref:`legacy_dvb_decoder_notes`
1417
1418 This ioctl has been replaced by the V4L2
1419 ``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control
1420 for MPEG decoders controlled through V4L2.
1421
1422 This ioctl call asks the Audio Device to select the requested channel
1423 for bilingual streams if possible.
1424
1425 Return Value
1426 ~~~~~~~~~~~~
1427
1428 On success 0 is returned, on error -1 and the ``errno`` variable is set
1429 appropriately. The generic error codes are described at the
1430 :ref:`Generic Error Codes <gen-errors>` chapter.
1431
1432
1433 -----
1434
1435
1436 open()
1437 ------
1438
1439 Synopsis
1440 ~~~~~~~~
1441
1442 .. code-block:: c
1443
1444 #include <fcntl.h>
1445
1446 .. c:function:: int open(const char *deviceName, int flags)
1447
1448 Arguments
1449 ~~~~~~~~~
1450
1451 .. flat-table::
1452 :header-rows: 0
1453 :stub-columns: 0
1454
1455 - ..
1456
1457 - ``const char *deviceName``
1458
1459 - Name of specific audio device.
1460
1461 - ..
1462
1463 - :rspan:`3` ``int flags``
1464
1465 - :cspan:`1` A bit-wise OR of the following flags:
1466
1467 - ..
1468
1469 - ``O_RDONLY``
1470
1471 - read-only access
1472
1473 - ..
1474
1475 - ``O_RDWR``
1476
1477 - read/write access
1478
1479 - ..
1480
1481 - ``O_NONBLOCK``
1482 - | Open in non-blocking mode
1483 | (blocking mode is the default)
1484
1485 Description
1486 ~~~~~~~~~~~
1487
1488 This system call opens a named audio device (e.g.
1489 ``/dev/dvb/adapter0/audio0``) for subsequent use. When an open() call has
1490 succeeded, the device will be ready for use. The significance of
1491 blocking or non-blocking mode is described in the documentation for
1492 functions where there is a difference. It does not affect the semantics
1493 of the open() call itself. A device opened in blocking mode can later be
1494 put into non-blocking mode (and vice versa) using the F_SETFL command
1495 of the fcntl system call. This is a standard system call, documented in
1496 the Linux manual page for fcntl. Only one user can open the Audio Device
1497 in O_RDWR mode. All other attempts to open the device in this mode will
1498 fail, and an error code will be returned. If the Audio Device is opened
1499 in O_RDONLY mode, the only ioctl call that can be used is
1500 `AUDIO_GET_STATUS`_. All other call will return with an error code.
1501
1502 Return Value
1503 ~~~~~~~~~~~~
1504
1505 .. flat-table::
1506 :header-rows: 0
1507 :stub-columns: 0
1508
1509 - ..
1510
1511 - ``ENODEV``
1512
1513 - Device driver not loaded/available.
1514
1515 - ..
1516
1517 - ``EBUSY``
1518
1519 - Device or resource busy.
1520
1521 - ..
1522
1523 - ``EINVAL``
1524
1525 - Invalid argument.
1526
1527
1528 -----
1529
1530
1531 close()
1532 -------
1533
1534 Synopsis
1535 ~~~~~~~~
1536
1537 .. c:function:: int close(int fd)
1538
1539 Arguments
1540 ~~~~~~~~~
1541
1542 .. flat-table::
1543 :header-rows: 0
1544 :stub-columns: 0
1545
1546 - ..
1547
1548 - ``int fd``
1549
1550 - :cspan:`1` File descriptor returned by a previous call
1551 to `open()`_.
1552
1553 Description
1554 ~~~~~~~~~~~
1555
1556 This system call closes a previously opened audio device.
1557
1558 Return Value
1559 ~~~~~~~~~~~~
1560
1561 .. flat-table::
1562 :header-rows: 0
1563 :stub-columns: 0
1564
1565 - ..
1566
1567 - ``EBADF``
1568
1569 - Fd is not a valid open file descriptor.
1570
1571 -----
1572
1573
1574 write()
1575 -------
1576
1577 Synopsis
1578 ~~~~~~~~
1579
1580 .. code-block:: c
1581
1582 size_t write(int fd, const void *buf, size_t count)
1583
1584 Arguments
1585 ~~~~~~~~~
1586
1587 .. flat-table::
1588 :header-rows: 0
1589 :stub-columns: 0
1590
1591 - ..
1592
1593 - ``int fd``
1594
1595 - :cspan:`1` File descriptor returned by a previous call
1596 to `open()`_.
1597
1598 - ..
1599
1600 - ``void *buf``
1601
1602 - Pointer to the buffer containing the PES data.
1603
1604 - ..
1605
1606 - ``size_t count``
1607
1608 - Size of buf.
1609
1610 Description
1611 ~~~~~~~~~~~
1612
1613 This system call can only be used if ``AUDIO_SOURCE_MEMORY`` is selected
1614 in the ioctl call `AUDIO_SELECT_SOURCE`_. The data provided shall be in
1615 PES format. If ``O_NONBLOCK`` is not specified the function will block
1616 until buffer space is available. The amount of data to be transferred is
1617 implied by count.
1618
1619 Return Value
1620 ~~~~~~~~~~~~
1621
1622 .. flat-table::
1623 :header-rows: 0
1624 :stub-columns: 0
1625
1626 - ..
1627
1628 - ``EPERM``
1629
1630 - :cspan:`1` Mode ``AUDIO_SOURCE_MEMORY`` not selected.
1631
1632 - ..
1633
1634 - ``ENOMEM``
1635
1636 - Attempted to write more data than the internal buffer can hold.
1637
1638 - ..
1639
1640 - ``EBADF``
1641
1642 - Fd is not a valid open file descriptor.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.