Document the sndhdr module.

Document that the whatsound module is obsolete.

1 files changed, 52 insertions, 0 deletions

diff --git a/Doc/lib/libsndhdr.tex b/Doc/lib/libsndhdr.tex
new file mode 100644
index 0000000..7d83440
--- /dev/null
+++ b/Doc/lib/libsndhdr.tex
@@ -0,0 +1,52 @@
+\section{\module{sndhdr} ---
+         Determine type of sound file.}
+
+\declaremodule{standard}{sndhdr}
+\modulesynopsis{Determine type of a sound file.}
+\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+% Based on comments in the module source file.
+
+
+The \module{sndhdr} provides utility functions which attempt to
+determine the type of sound data which is in a file.  When these
+functions are able to determine what type of sound data is stored in a
+file, they return a tuple \code{(\var{type}, \var{sampling_rate},
+\var{channels}, \var{frames}, \var{bits_per_sample})}.  The value for
+\var{type} indicates the data type and will be one of the strings
+\code{'aifc'}, \code{'aiff'}, \code{'au'}, \code{'hcom'},
+\code{'sndr'}, \code{'sndt'}, \code{'voc'}, \code{'wav'},
+\code{'8svx'}, \code{'sb'}, \code{'ub'}, or \code{'ul'}.  The
+\var{sampling_rate} will be either the actual value or \code{0} if
+unknown or difficult to decode.  Similarly, \var{channels} will be
+either the number of channels or \code{0} if it cannot be determined
+or if the value is difficult to decode.  The value for \var{frames}
+will be either the number of frames or \code{-1}.  The last item in
+the tuple, \var{bits_per_sample}, will either be the sample size in
+bits or \code{'A'} for A-LAW\index{A-LAW} or \code{'U'} for
+u-LAW\index{u-LAW}.
+
+
+\begin{funcdesc}{what}{filename}
+  Determines the type of sound data stored in the file \var{filename}
+  using \function{whathdr()}.  If not successful, \function{whatraw()} 
+  is used.  If neither attempt succeeds, returns \code{None},
+  otherwise it returns a tuple as described above.
+\end{funcdesc}
+
+
+\begin{funcdesc}{whathdr}{filename}
+  Determines the type of sound data stored in a file based on the file 
+  header.  The name of the file is given by \var{filename}.  This
+  function returns a tuple as described above on success, or
+  \code{None}.
+\end{funcdesc}
+
+
+\begin{funcdesc}{whatraw}{filename}
+  Determines the type of raw sound data stored in a file without a
+  header.  The name of the file is given by \var{filename}.  This
+  function returns a tuple as described above on success, or
+  \code{None}.
+
+  This requires the \program{whatsound} program to work.
+\end{funcdesc}