| % Documentations stolen and LaTeX'ed from comments in file. |
| \section{\module{wave} --- |
| Read and write WAV files} |
| |
| \declaremodule{standard}{wave} |
| \sectionauthor{Moshe Zadka}{mzadka@geocities.com} |
| \modulesynopsis{Provide an interface to the WAV sound format.} |
| |
| The \module{wave} module provides a convenient interface to the WAV sound |
| format. It does not support compression/decompression, but it does support |
| mono/stereo. |
| |
| The \module{wave} module defines the following function and exception: |
| |
| \begin{funcdesc}{open}{file\optional{, mode}} |
| If \var{file} is a string, open the file by that name, other treat it |
| as a seekable file-like object. \var{mode} can be any of |
| \begin{description} |
| \item[\code{'r'}, \code{'rb'}] Read only mode. |
| \item[\code{'w'}, \code{'wb'}] Write only mode. |
| \end{description} |
| Note that it does not allow read/write WAV files. |
| |
| A \var{mode} of \code{'r'} or \code{'rb'} returns a \class{Wave_read} |
| object, while a \var{mode} of \code{'w'} or \code{'wb'} returns |
| a \class{Wave_write} object. If \var{mode} is omitted and a file-like |
| object is passed as \var{file}, \code{\var{file}.mode} is used as the |
| default value for \var{mode} (the \character{b} flag is still added if |
| necessary). |
| \end{funcdesc} |
| |
| \begin{funcdesc}{openfp}{file, mode} |
| A synonym for \function{open()}, maintained for backwards compatibility. |
| \end{funcdesc} |
| |
| \begin{excdesc}{Error} |
| An error raised when something is impossible because it violates the |
| WAV specification or hits an implementation deficiency. |
| \end{excdesc} |
| |
| |
| \subsection{Wave_read Objects \label{Wave-read-objects}} |
| |
| Wave_read objects, as returned by \function{open()}, have the |
| following methods: |
| |
| \begin{methoddesc}[Wave_read]{close}{} |
| Close the stream, and make the instance unusable. This is |
| called automatically on object collection. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_read]{getnchannels}{} |
| Returns number of audio channels (\code{1} for mono, \code{2} for |
| stereo). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_read]{getsampwidth}{} |
| Returns sample width in bytes. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_read]{getframerate}{} |
| Returns sampling frequency. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_read]{getnframes}{} |
| Returns number of audio frames. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_read]{getcomptype}{} |
| Returns compression type (\code{'NONE'} is the only supported type). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_read]{getcompname}{} |
| Human-readable version of \method{getcomptype()}. |
| Usually \code{'not compressed'} parallels \code{'NONE'}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_read]{getparams}{} |
| Returns a tuple |
| \code{(\var{nchannels}, \var{sampwidth}, \var{framerate}, |
| \var{nframes}, \var{comptype}, \var{compname})}, equivalent to output |
| of the \method{get*()} methods. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_read]{readframes}{n} |
| Reads and returns at most \var{n} frames of audio, as a string of bytes. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_read]{rewind}{} |
| Rewind the file pointer to the beginning of the audio stream. |
| \end{methoddesc} |
| |
| The following two methods are defined for compatibility with the |
| \refmodule{aifc} module, and don't do anything interesting. |
| |
| \begin{methoddesc}[Wave_read]{getmarkers}{} |
| Returns \code{None}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_read]{getmark}{id} |
| Raise an error. |
| \end{methoddesc} |
| |
| The following two methods define a term ``position'' which is compatible |
| between them, and is otherwise implementation dependent. |
| |
| \begin{methoddesc}[Wave_read]{setpos}{pos} |
| Set the file pointer to the specified position. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_read]{tell}{} |
| Return current file pointer position. |
| \end{methoddesc} |
| |
| |
| \subsection{Wave_write Objects \label{Wave-write-objects}} |
| |
| Wave_write objects, as returned by \function{open()}, have the |
| following methods: |
| |
| \begin{methoddesc}[Wave_write]{close}{} |
| Make sure \var{nframes} is correct, and close the file. |
| This method is called upon deletion. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_write]{setnchannels}{n} |
| Set the number of channels. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_write]{setsampwidth}{n} |
| Set the sample width to \var{n} bytes. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_write]{setframerate}{n} |
| Set the frame rate to \var{n}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_write]{setnframes}{n} |
| Set the number of frames to \var{n}. This will be changed later if |
| more frames are written. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_write]{setcomptype}{type, name} |
| Set the compression type and description. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_write]{setparams}{tuple} |
| The \var{tuple} should be \code{(\var{nchannels}, \var{sampwidth}, |
| \var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}, with |
| values valid for the \method{set*()} methods. Sets all parameters. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_write]{tell}{} |
| Return current position in the file, with the same disclaimer for |
| the \method{Wave_read.tell()} and \method{Wave_read.setpos()} |
| methods. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_write]{writeframesraw}{data} |
| Write audio frames, without correcting \var{nframes}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Wave_write]{writeframes}{data} |
| Write audio frames and make sure \var{nframes} is correct. |
| \end{methoddesc} |
| |
| Note that it is invalid to set any parameters after calling |
| \method{writeframes()} or \method{writeframesraw()}, and any attempt |
| to do so will raise \exception{wave.Error}. |