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

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

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

"wave" モジュールは、Waveform Audio の "WAVE" (または "WAV") ファイル
形式を扱うための便利なインターフェースを提供します。

このモジュールは、非圧縮の PCM と IEEE 浮動小数点の WAV 形式に対応して
います。

バージョン 3.12 で変更: 拡張形式が "KSDATAFORMAT_SUBTYPE_PCM" の場合に
、"WAVE_FORMAT_EXTENSIBLE" ヘッダに対応するようになりました。

バージョン 3.15 で変更: "WAVE_FORMAT_IEEE_FLOAT" ファイルの読み書きに
対応しました。

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

wave.open(file, mode=None)

   If *file* is a string, a *path-like object* or a *bytes-like
   object* open the file by that name, otherwise treat it as a file-
   like object.  *mode* can be:

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

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

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

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

   ファイルライクオブジェクトを渡した場合、wave オブジェクトの
   "close()" メソッドを呼び出しても、そのファイルオブジェクトは閉じま
   せん。 ファイルオブジェクトを閉じるのは呼び出し側の責任です。

   "open()" 関数は "with" 文で使えます。 "with" ブロックが終了すると、
   "Wave_read.close()" または "Wave_write.close()" メソッドが呼び出さ
   れます。

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

   バージョン 3.15 で変更: Added support for *path-like objects* and
   *bytes-like objects*.

exception wave.Error

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

wave.WAVE_FORMAT_PCM

   非圧縮 PCM オーディオの形式コードです。

wave.WAVE_FORMAT_IEEE_FLOAT

   IEEE 浮動小数点オーディオの形式コードです。

   Added in version 3.15.

wave.WAVE_FORMAT_EXTENSIBLE

   WAVE 拡張ヘッダの形式コードです。

   Added in version 3.12.


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

class wave.Wave_read

   WAV ファイルを読み込みます。

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

   close()

      "wave" が開いたストリームであればそのストリームを閉じ、インスタ
      ンスを使用不能にします。 オブジェクトの回収時に自動的に呼び出さ
      れます。

   getnchannels()

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

   getsampwidth()

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

   getframerate()

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

   getnframes()

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

   getformat()

      フレームの形式コードを返します。

      "WAVE_FORMAT_PCM"、"WAVE_FORMAT_IEEE_FLOAT"、
      "WAVE_FORMAT_EXTENSIBLE" のいずれかです。

      Added in version 3.15.

   getcomptype()

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

   getcompname()

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

   getparams()

      "get*()" メソッドの戻り値に相当する、"namedtuple()" の
      "(nchannels, sampwidth, framerate, nframes, comptype, compname)"
      を返します。

   readframes(n)

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

   rewind()

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

   以下の 2 つのメソッドが扱う「位置」は互いに互換性がありますが、それ
   以外の点では実装依存です。

   setpos(pos)

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

   tell()

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


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

class wave.Wave_write

   WAV ファイルを書き込みます。

   "open()" が返す Wave_write オブジェクトです。

   シーク可能な出力ストリームでは、実際に書き込まれたフレーム数を反映
   するように "wave" ヘッダが自動更新されます。 シーク不能なストリーム
   では、最初のフレームデータを書き込む時点で *nframes* の値が正確でな
   ければなりません。 正確な *nframes* を設定する方法は 2 つあります。
   1 つは、"close()" を呼び出すまでに書き込むフレーム数を指定して
   "setnframes()" または "setparams()" を呼び出し、 その後
   "writeframesraw()" でフレームデータを書き込む方法です。 もう 1 つは
   、書き込むすべてのフレームデータを指定して "writeframes()" を呼び出
   す方法です。 後者では、"writeframes()" がフレームデータを書き込む前
   にデータ内のフレーム数を計算し、それに合わせて *nframes* を設定しま
   す。

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

   Wave_write オブジェクトには以下のメソッドがあります:

   close()

      *nframes* が正しい値になるようにし、"wave" が開いたファイルであ
      ればそのファイルを閉じます。 このメソッドはオブジェクトの回収時
      に呼び出されます。 出力ストリームがシーク不能で、*nframes* が実
      際に書き込まれたフレーム数と一致しなければ、例外を送出します。

   setnchannels(n)

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

   getnchannels()

      チャンネル数を返します。

   setsampwidth(n)

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

      "WAVE_FORMAT_IEEE_FLOAT" では、サンプルサイズは 4 バイト (32 ビ
      ット) と 8 バイト (64 ビット) だけに対応しています。

   getsampwidth()

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

   setframerate(n)

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

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

   getframerate()

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

   setnframes(n)

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

   getnframes()

      これまでに書き込んだオーディオフレーム数を返します。

   setcomptype(type, name)

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

   getcomptype()

      圧縮形式 ("'NONE'") を返します。

   getcompname()

      人が読める形の圧縮形式名を返します。

   setformat(format)

      フレームの形式コードを設定します。

      指定できる値は "WAVE_FORMAT_PCM" と "WAVE_FORMAT_IEEE_FLOAT" で
      す。

      "WAVE_FORMAT_IEEE_FLOAT" を設定する場合、サンプルサイズは 4 バイ
      トまたは 8 バイトでなければなりません。

      Added in version 3.15.

   getformat()

      現在のフレームの形式コードを返します。

      Added in version 3.15.

   setparams(tuple)

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

      後方互換性のために、*format* を含まない 6 項目のタプルも受け取れ
      ます。 この場合、形式のデフォルトは "WAVE_FORMAT_PCM" です。

      "format=WAVE_FORMAT_IEEE_FLOAT" の場合、*sampwidth* は 4 または
      8 でなければなりません。

      バージョン 3.15 で変更: *tuple* に省略可能な項目 *format* を追加
      しました。

   getparams()

      現在の出力パラメータを格納した "namedtuple()" の "(nchannels,
      sampwidth, framerate, nframes, comptype, compname)" を返します。

   tell()

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

   writeframesraw(data)

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

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

   writeframes(data)

      オーディオフレームを書き込み、*nframes* が正しい値になるようにし
      ます。 出力ストリームがシーク不能で、*data* の書き込み後の総フレ
      ーム数が事前に設定した *nframes* と一致しない場合は、エラーを送
      出します。

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

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

      "WAVE_FORMAT_IEEE_FLOAT" で出力する場合は、非 PCM 形式に対する
      WAVE 仕様の要件に従って "fact" チャンクを書き込みます。
