- merged GNU FDL lincense from NEWSTRUCT branch

- updated from DVB_API_VERSION 3
- various minor fixes/additions
- bumped version number to 1.0.0-pre1 to match wth upcoming
  linuxtv-dvb driver release

1 files changed, 46 insertions, 34 deletions

diff --git a/dvb-spec/dvbapi/audio.tex b/dvb-spec/dvbapi/audio.tex
index 540248463..05c23e56f 100644
--- a/dvb-spec/dvbapi/audio.tex
+++ b/dvb-spec/dvbapi/audio.tex
@@ -1,7 +1,13 @@
 \devsec{DVB Audio Device}
 
 The DVB audio device controls the MPEG2 audio decoder of the DVB hardware.
-It can be accessed through \texttt{/dev/ost/audio}.
+It can be accessed through \texttt{/dev/dvb/adapter0/audio0}.
+Data types and and ioctl definitions can be accessed by including
+\texttt{linux/dvb/video.h} in your application.
+
+Please note that some DVB cards don't have their own
+MPEG decoder, which results in the omission of the audio and video
+device.
 
 
 \devsubsec{Audio Data Types}
@@ -9,16 +15,16 @@ It can be accessed through \texttt{/dev/ost/audio}.
 This section describes the structures, data types and defines used when 
 talking to the audio device.
 
-\devsubsubsec{audioStreamSource\_t}
+\devsubsubsec{audio\_stream\_source\_t}
 \label{audiostreamsource}
 The audio stream source is set through the AUDIO\_SELECT\_SOURCE
 call and can take the following values, depending on whether we are
-replaying from an internal (demuxer) or external (user write) source.
+replaying from an internal (demux) or external (user write) source.
 \begin{verbatim}
 typedef enum {
         AUDIO_SOURCE_DEMUX, 
         AUDIO_SOURCE_MEMORY 
-} audio\_stream_source_t;
+} audio_stream_source_t;
 \end{verbatim}
 AUDIO\_SOURCE\_DEMUX selects the demultiplexer (fed
 either by the frontend or the DVR device) as the source of 
@@ -27,7 +33,7 @@ If AUDIO\_SOURCE\_MEMORY is selected the stream
 comes from the application through the \texttt{write()} 
 system call.
 
-\devsubsubsec{audioPlayState\_t}
+\devsubsubsec{audio\_play\_state\_t}
 The following values can be returned by the AUDIO\_GET\_STATUS call
 representing the state of audio playback.
 \label{audioplaystate}
@@ -36,45 +42,45 @@ typedef enum {
         AUDIO_STOPPED,
         AUDIO_PLAYING,
         AUDIO_PAUSED  
-} audio\_play_state_t;
+} audio_play_state_t;
 \end{verbatim}
 
-\devsubsubsec{audioChannelSelect\_t}
+\devsubsubsec{audio\_channel\_select\_t}
 \label{audiochannelselect}
 The audio channel selected via AUDIO\_CHANNEL\_SELECT is determined by
-the following values. 
+the following values.
 \begin{verbatim}
 typedef enum {
         AUDIO_STEREO,
         AUDIO_MONO_LEFT, 
         AUDIO_MONO_RIGHT, 
-} audio\_channel_select_t;
+} audio_channel_select_t;
 \end{verbatim}
 
-\devsubsubsec{audio\_status\_t}
+\devsubsubsec{struct audio\_status}
 \label{audiostatus}
 The AUDIO\_GET\_STATUS call returns the following structure informing
 about various states of the playback operation.
 \begin{verbatim}
-typedef struct audio\_status { 
+typedef struct audio_status { 
         boolean AV_sync_state;
         boolean mute_state;  
-        audio\_play_state_t play_state;
-        audio\_stream_source_t stream_source; 
-        audio\_channel_select_t channel_select;
+        audio_play_state_t play_state;
+        audio_stream_source_t stream_source; 
+        audio_channel_select_t channel_select;
         boolean bypass_mode;
-} audio\_status_t;
+} audio_status_t;
 \end{verbatim}
 
-\devsubsubsec{audio\_mixer\_t}
+\devsubsubsec{struct audio\_mixer}
 \label{audiomixer}
 The following structure is used by the AUDIO\_SET\_MIXER call to set
 the audio volume.
 \begin{verbatim}
-typedef struct audio\_mixer { 
+typedef struct audio_mixer { 
         unsigned int volume_left;
         unsigned int volume_right;
-} audio\_mixer_t;
+} audio_mixer_t;
 \end{verbatim}
 
 \devsubsubsec{audio encodings}
@@ -94,25 +100,31 @@ the following bits set according to the hardwares capabilities.
 \end{verbatim}
 
 
-\devsubsubsec{audio karaoke}
+\devsubsubsec{struct audio\_karaoke}
 \label{audiokaraoke}
 The ioctl AUDIO\_SET\_KARAOKE uses the following format:
 \begin{verbatim}
 typedef
-struct audio\_karaoke{         /* if Vocal1 or Vocal2 are non-zero, they get mixed  */
-        int vocal1;          /* into left and right t at 70% each */
-        int vocal2;          /* if both, Vocal1 and Vocal2 are non-zero, Vocal1 gets  */
-        int melody;          /* mixed into the left channel and */
-                             /* Vocal2 into the right channel at 100% each. */
-                             /* if Melody is non-zero, the melody channel gets mixed  */                             /* into left and right  */
-} audio\_karaoke_t;
+struct audio_karaoke{
+        int vocal1;  
+        int vocal2;  
+        int melody;  
+} audio_karaoke_t;
 \end{verbatim}
 
+If Vocal1 or Vocal2 are non-zero, they get mixed
+into left and right t at 70\% each.
+If both, Vocal1 and Vocal2 are non-zero, Vocal1 gets
+mixed into the left channel and
+Vocal2 into the right channel at 100\% each.
+Ff Melody is non-zero, the melody channel gets mixed
+into left and right.
+
 \devsubsubsec{audio attributes}
 \label{aattrib}
 The following attributes can be set by a call to AUDIO\_SET\_ATTRIBUTES:
 \begin{verbatim}
-typedef uint16_t audio\_attributes_t;
+typedef uint16_t audio_attributes_t;
 /*   bits: descr. */
 /*   15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, */
 /*   12    multichannel extension */
@@ -130,7 +142,7 @@ typedef uint16_t audio\_attributes_t;
 
 \function{open()}{
   int open(const char *deviceName, int flags);}{
-  This system call opens a named audio device (e.g. /dev/ost/audio) for subsequent
+  This system call opens a named audio device (e.g. /dev/dvb/adapter0/audio0) for subsequent
   use. When an open() call has succeeded, the device will be ready for use.
   The significance of blocking or non-blocking mode is described in the 
   documentation for functions where there is a difference. It does not affect 
@@ -225,7 +237,7 @@ typedef uint16_t audio\_attributes_t;
 
 \ifunction{AUDIO\_SELECT\_SOURCE}{
   int ioctl(int fd, int request = AUDIO\_SELECT\_SOURCE, 
-  audioStreamSource\_t source);}{
+  audio\_stream\_source\_t source);}{
   This ioctl call informs the audio device which source shall be used for the 
   input data. The possible sources are demux or memory. 
   If AUDIO\_SOURCE\_MEMORY 
@@ -233,7 +245,7 @@ typedef uint16_t audio\_attributes_t;
   }{
   int fd & File descriptor returned by a previous call to open().\\
   int request & Equals AUDIO\_SELECT\_SOURCE for this command.\\
-  audioStreamSource\_t source& Indicates the source that shall be used for the
+  audio\_stream\_source\_t source& Indicates the source that shall be used for the
   Audio stream.
   }{
   EBADF&      fd is not a valid open file descriptor.\\
@@ -295,13 +307,13 @@ typedef uint16_t audio\_attributes_t;
 
 \ifunction{AUDIO\_CHANNEL\_SELECT}{
   int ioctl(int fd, int request = AUDIO\_CHANNEL\_SELECT, 
-  audioChannelSelect\_t);}{
+  audio\_channel\_select\_t);}{
   This ioctl call asks the Audio Device to select the requested channel 
   if possible.
   }{
   int fd & File descriptor returned by a previous call to open().\\
   int request & Equals AUDIO\_CHANNEL\_SELECT for this command.\\
-  audioChannelSelect\_t ch &
+  audio\_channel\_select\_t ch &
   Select the output format of the audio (mono left/right, stereo).
   }{
   EBADF&      fd is not a valid open file descriptor.\\
@@ -412,13 +424,13 @@ typedef uint16_t audio\_attributes_t;
 }
 
 \ifunction{AUDIO\_SET\_ATTRIBUTES}{
-  int ioctl(fd, int request = AUDIO\_SET\_ATTRIBUTES, audioAttributes\_t attr );}{
+  int ioctl(fd, int request = AUDIO\_SET\_ATTRIBUTES, audio\_attributes\_t attr );}{
   This ioctl is intended for DVD playback and allows you to set
   certain information about the audio stream.
   }{
   int fd      & File descriptor returned by a previous call to open().\\
   int request & Equals AUDIO\_SET\_ATTRIBUTES for this command.\\
-  iaudioAttributes\_t attr & audio attributes according to section \ref{aattrib}\\
+  audio\_attributes\_t attr & audio attributes according to section \ref{aattrib}\\
   }{
   EBADF& fd is not a valid open file descriptor \\
   EINVAL& attr is not a valid or supported attribute setting.\\