22.4. "wave" --- WAVファイルの読み書き
**************************************

**ソースコード:** Lib/wave.py

======================================================================

"wave" モジュールは、WAVサウンドフォーマットへの便利なインターフェイス
を提供するモジュールです。このモジュールは圧縮／展開をサポートしていま
せんが、モノラル／ステレオには対応しています。

"wave" モジュールは、以下の関数と例外を定義しています:

wave.open(file, mode=None)

   *file* が文字列ならその名前のファイルを開き、そうでないなら file
   like オブジェクトとして扱います。 *mode* は以下のうちのいずれかです
   :

   "'rb'"
      読み出しのみのモード。

   "'wb'"
      書き込みのみのモード。

   WAVファイルに対して読み込み／書き込み両方のモードで開くことはできな
   いことに注意して下さい。

   *mode* が "'rb'" の場合 "Wave_read" オブジェクトを返し、 "'wb'" の
   場合 "Wave_write" オブジェクトを返します。 *mode* が省略されていて
   、 file-like オブジェクトが *file* として渡されると、 "file.mode"
   が *mode* のデフォルト値として使われます。

   file like オブジェクトを渡した場合、 wave オブジェクトの "close()"
   メソッドを呼び出してもその file like オブジェクトを close しません
   。 file like オブジェクトの close は呼び出し側の責任になります。

   "open()" 関数は "with" 文とともに使うことができます。 "with" ブロッ
   クが完了する時に、 "Wave_read.close()" または "Wave_write.close()"
   メソッドが呼ばれます。

   バージョン 3.4 で変更: シーク不能なファイルのサポートが追加されまし
   た。

wave.openfp(file, mode)

   "open()" と同義。後方互換性のために残されています。

exception wave.Error

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


22.4.1. Wave_read オブジェクト
==============================

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

Wave_read.close()

   "wave" によって開かれていた場合はストリームを閉じ、このオブジェクト
   のインスタンスを使用できなくします。これはオブジェクトのガベージコ
   レクション時に自動的に呼び出されます。

Wave_read.getnchannels()

   オーディオチャンネル数（モノラルなら "1" 、ステレオなら "2" ）を返
   します。

Wave_read.getsampwidth()

   サンプルサイズをバイト数で返します。

Wave_read.getframerate()

   サンプリングレートを返します。

Wave_read.getnframes()

   オーディオフレーム数を返します。

Wave_read.getcomptype()

   圧縮形式を返します（ "'NONE'" だけがサポートされている形式です）。

Wave_read.getcompname()

   "getcomptype()" を人に判読可能な形にしたものです。通常、 "'NONE'"
   に対して "'not compressed'" が返されます。

Wave_read.getparams()

   "get*()" メソッドが返すのと同じ "(nchannels, sampwidth, framerate,
   nframes, comptype, compname)" の "namedtuple()" を返します。

Wave_read.readframes(n)

   最大 *n* 個のオーディオフレームを読み込んで、 "bytes" オブジェクト
   として返します。

Wave_read.rewind()

   ファイルのポインタをオーディオストリームの先頭に戻します。

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

Wave_read.getmarkers()

   "None" を返します。

Wave_read.getmark(id)

   エラーを発生します。

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

Wave_read.setpos(pos)

   ファイルのポインタを指定した位置に設定します。

Wave_read.tell()

   ファイルの現在のポインタ位置を返します。


22.4.2. Wave_write オブジェクト
===============================

seek 可能な出力ストリームでは、実際に書き込まれたフレーム数を反映する
ように "wave" ヘッダーは自動的にアップデートされます。 seek 不能なスト
リームでは、最初のフレームデータが書き込まれる時には *nframes* の値は
正確でなければなりません。 *nframes* の正確な値は、 "close()" が呼ばれ
る前に書き込まれるフレーム数とともに "setnframes()" または
"setparams()" を呼んで、その後 "writeframesraw()" を利用してフレームデ
ータを書くか、もしくはすべての書き込むべきフレームデータとともに
"writeframes()" を呼び出すことによって達成できます。後者のケースでは、
"writeframes()" はフレームデータを書く前に、データ中のフレームの数を計
算して、それに応じて *nframes* を設定します。

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

バージョン 3.4 で変更: シーク不能なファイルのサポートが追加されました
。

Wave_write.close()

   *nframes* が正しいか確認して、ファイルが "wave" によって開かれてい
   た場合は閉じます。このメソッドはオブジェクトがガベージコレクション
   されるときに呼び出されます。もし出力ストリームがシーク不能で、
   *nframes* が実際に書き込まれたフレームの数と一致しなければ、例外が
   起きます。

Wave_write.setnchannels(n)

   チャンネル数を設定します。

Wave_write.setsampwidth(n)

   サンプルサイズを *n* バイトに設定します。

Wave_write.setframerate(n)

   サンプリングレートを *n* に設定します。

   バージョン 3.2 で変更: 整数ではない値がこのメソッドに入力された場合
   は、直近の整数に丸められます。

Wave_write.setnframes(n)

   フレーム数を *n* に設定します。もし実際に書き込まれたフレームの数と
   異なるなら、これは後で変更されます (出力ストリームがシーク不能なら
   、更新しようとした時にエラーが起きます)。

Wave_write.setcomptype(type, name)

   圧縮形式とその記述を設定します。現在のところ、非圧縮を示す圧縮形式
   "NONE" だけがサポートされています。

Wave_write.setparams(tuple)

   この *tuple* は "(nchannels, sampwidth, framerate, nframes,
   comptype, compname)" でなければならず、その値はそれぞれの "set*()"
   メソッドで有効でなければなりません。すべてのパラメータを設定します
   。

Wave_write.tell()

   ファイルの中の現在位置を返します。 "Wave_read.tell()" と
   "Wave_read.setpos()" メソッドでお断りしたことがこのメソッドにも当て
   はまります。

Wave_write.writeframesraw(data)

   *nframes* の修正なしにオーディオフレームを書き込みます。

   バージョン 3.4 で変更: どのような *bytes-like object* も使用できる
   ようになりました。

Wave_write.writeframes(data)

   出力ストリームが seek 不可能で、 *data* が書き込まれた後でそれ以前
   に *nframes* に設定された値と書き込まれた全フレーム数が一致しなけれ
   ば、エラーを送出します。

   バージョン 3.4 で変更: どのような *bytes-like object* も使用できる
   ようになりました。

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