% Documentations stolen and LaTeX'ed from comments in file.
\section{\module{wave} ---
         WAVファイルの読み書き}
\declaremodule{standard}{wave}
\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
\modulesynopsis{
WAVサウンドフォーマットへのインターフェイス}

\module{wave}モジュールは、WAVサウンドフォーマットへの便利なインター
フェイスを提供するモジュールです。

このモジュールは圧縮／展開をサポートしていませんが、モノラル／ステレオ
には対応しています。

\module{wave}モジュールは、以下の関数と例外を定義しています。

\begin{funcdesc}{open}{file\optional{, mode}}
\var{file}が文字列ならその名前のファイルを開き、そうでないならファイル
のようにシーク可能なオブジェクトとして扱います。\var{mode}は以下のうち
のいずれかです。

\begin{description}
        \item[\code{'r'}, \code{'rb'}] 　読み込みのみのモード。
        \item[\code{'w'}, \code{'wb'}] 　書き込みのみのモード。
\end{description}
WAVファイルに対して読み込み／書き込み両方のモードで開くことはできない
ことに注意して下さい。
\code{'r'}と\code{'rb'}の\var{mode}は\class{Wave_read}オブジェクトを
返し、\code{'w'}と\code{'wb'}の\var{mode}は\class{Wave_write}オブジェク
トを返します。
\var{mode}が省略されていて、ファイルのようなオブジェクトが\var{file}とし
て渡されると、\code{\var{file}.mode}が\var{mode}のデフォルト値として使わ
れます（必要であれば、さらにフラグ\character{b}が付け加えられます）。
\end{funcdesc}

\begin{funcdesc}{openfp}{file, mode}
\function{open()}と同義。後方互換性のために残されています。
\end{funcdesc}

\begin{excdesc}{Error}
WAVの仕様を犯したり、実装の欠陥に遭遇して何か実行不可能となった時に発生
するエラー。
\end{excdesc}

\subsection{Wave_read オブジェクト \label{Wave-read-objects}}

\function{open()}によって返されるWave_readオブジェクトには、以下のメソッ
ドがあります：

\begin{methoddesc}[Wave_read]{close}{}
ストリームを閉じ、このオブジェクトのインスタンスを使用できなくします。
これはオブジェクトのガベージコレクション時に自動的に呼び出されます。
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getnchannels}{}
オーディオチャンネル数（モノラルなら\code{1}、ステレオなら\code{2}）を返
します。
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getsampwidth}{}
サンプルサイズをバイト数で返します。
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getframerate}{}
サンプリングレートを返します。
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getnframes}{}
オーディオフレーム数を返します。
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getcomptype}{}
圧縮形式を返します（\code{'NONE'}だけがサポートされている形式です）。
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getcompname}{}
\method{getcomptype()}を人に判読可能な形にしたものです。
通常、\code{'NONE'}に対して\code{'not compressed'}が返されます。

\end{methoddesc}

\begin{methoddesc}[Wave_read]{getparams}{}
\method{get*()}メソッドが返すのと同じ\code{(\var{nchannels}, 
\var{sampwidth}, \var{framerate},
\var{nframes}, \var{comptype}, \var{compname})}のタプルを返します。
\end{methoddesc}

\begin{methoddesc}[Wave_read]{readframes}{n}
現在のポインタから\var{n}個のオーディオフレームの値を読み込んで、バイト
ごとに文字に変換して文字列を返します。
\end{methoddesc}

\begin{methoddesc}[Wave_read]{rewind}{}
ファイルのポインタをオーディオストリームの先頭に戻します。
\end{methoddesc}

以下の2つのメソッドは\refmodule{aifc}モジュールとの互換性のために定義さ
れていますが、何も面白いことはしません。

\begin{methoddesc}[Wave_read]{getmarkers}{}
\code{None}を返します。
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getmark}{id}
エラーを発生します。
\end{methoddesc}

以下の2つのメソッドは共通の``位置''を定義しています。``位置''は他の関数
とは独立して実装されています。

\begin{methoddesc}[Wave_read]{setpos}{pos}
ファイルのポインタを指定した位置に設定します。
\end{methoddesc}

\begin{methoddesc}[Wave_read]{tell}{}
ファイルの現在のポインタ位置を返します。
\end{methoddesc}

\subsection{Wave_write オブジェクト \label{Wave-write-objects}}

\function{open()}によって返されるWave_writeオブジェクトには、以下のメ
ソッドがあります：

\begin{methoddesc}[Wave_write]{close}{}
\var{nframes}が正しいか確認して、ファイルを閉じます。
このメソッドはオブジェクトの削除時に呼び出されます。
\end{methoddesc}

\begin{methoddesc}[Wave_write]{setnchannels}{n}
チャンネル数を設定します。
\end{methoddesc}

\begin{methoddesc}[Wave_write]{setsampwidth}{n}
サンプルサイズを\var{n}バイトに設定します。
\end{methoddesc}

\begin{methoddesc}[Wave_write]{setframerate}{n}
サンプリングレートを\var{n}に設定します。
\end{methoddesc}

\begin{methoddesc}[Wave_write]{setnframes}{n}
フレーム数を\var{n}に設定します。あとからフレームが書き込まれるとフレー
ム数は変更されます。
\end{methoddesc}

\begin{methoddesc}[Wave_write]{setcomptype}{type, name}
圧縮形式とその記述を設定します。
\end{methoddesc}

\begin{methoddesc}[Wave_write]{setparams}{tuple}
\var{tuple}は\code{(\var{nchannels}, \var{sampwidth},
\var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}
で、それぞれ\method{set*()}のメソッドの値にふさわしいものでなければなり
ません。全ての変数を設定します。
\end{methoddesc}

\begin{methoddesc}[Wave_write]{tell}{}
ファイルの中の現在位置を返します。\method{Wave_read.tell()}と
\method{Wave_read.setpos()}メソッドでお断りしたことがこのメソッドにも当
てはまります。
\end{methoddesc}

\begin{methoddesc}[Wave_write]{writeframesraw}{data}
\var{nframes}の修正なしにオーディオフレームを書き込みます。
\end{methoddesc}

\begin{methoddesc}[Wave_write]{writeframes}{data}
オーディオフレームを書き込んで\var{nframes}を修正します。
\end{methoddesc}

\method{writeframes()}や\method{writeframesraw()}メソッドを呼び出したあ
とで、どんなパラメータを設定しようとしても不正となることに注意して下さ
い。そうすると\exception{wave.Error}を発生します。