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

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

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

The "wave" module provides a convenient interface to the Waveform
Audio "WAVE" (or "WAV") file format. Only uncompressed PCM encoded
wave files are supported.

バージョン 3.12 で変更: Support for "WAVE_FORMAT_EXTENSIBLE" headers
was added, provided that the extended format is
"KSDATAFORMAT_SUBTYPE_PCM".

The "wave" module defines the following function and exception:

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* のデフォルト値として使われます。

   If you pass in a file-like object, the wave object will not close
   it when its "close()" method is called; it is the caller's
   responsibility to close the file object.

   The "open()" function may be used in a "with" statement.  When the
   "with" block completes, the "Wave_read.close()" or
   "Wave_write.close()" method is called.

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

exception wave.Error

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


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

class wave.Wave_read

   Read a WAV file.

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

   close()

      Close the stream if it was opened by "wave", and make the
      instance unusable.  This is called automatically on object
      collection.

   getnchannels()

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

   getsampwidth()

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

   getframerate()

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

   getnframes()

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

   getcomptype()

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

   getcompname()

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

   getparams()

      Returns a "namedtuple()" "(nchannels, sampwidth, framerate,
      nframes, comptype, compname)", equivalent to output of the
      "get*()" methods.

   readframes(n)

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

   rewind()

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

   The following two methods are defined for compatibility with the
   old "aifc" module, and don't do anything interesting.

   getmarkers()

      "None" を返します。

      バージョン 3.13 で非推奨、バージョン 3.15 で削除予定: The method
      only existed for compatibility with the "aifc" module which has
      been removed in Python 3.13.

   getmark(id)

      エラーを発生します。

      バージョン 3.13 で非推奨、バージョン 3.15 で削除予定: The method
      only existed for compatibility with the "aifc" module which has
      been removed in Python 3.13.

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

   setpos(pos)

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

   tell()

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


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

class wave.Wave_write

   Write a WAV file.

   Wave_write objects, as returned by "open()".

   For seekable output streams, the "wave" header will automatically
   be updated to reflect the number of frames actually written.  For
   unseekable streams, the *nframes* value must be accurate when the
   first frame data is written.  An accurate *nframes* value can be
   achieved either by calling "setnframes()" or "setparams()" with the
   number of frames that will be written before "close()" is called
   and then using "writeframesraw()" to write the frame data, or by
   calling "writeframes()" with all of the frame data to be written.
   In the latter case "writeframes()" will calculate the number of
   frames in the data and set *nframes* accordingly before writing the
   frame data.

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

   Wave_write objects have the following methods:

   close()

      Make sure *nframes* is correct, and close the file if it was
      opened by "wave".  This method is called upon object collection.
      It will raise an exception if the output stream is not seekable
      and *nframes* does not match the number of frames actually
      written.

   setnchannels(n)

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

   getnchannels()

      Return the number of channels.

   setsampwidth(n)

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

   getsampwidth()

      Return the sample width in bytes.

   setframerate(n)

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

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

   getframerate()

      Return the frame rate.

   setnframes(n)

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

   getnframes()

      Return the number of audio frames written so far.

   setcomptype(type, name)

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

   getcomptype()

      Return the compression type ("'NONE'").

   getcompname()

      Return the human-readable compression type name.

   setparams(tuple)

      The *tuple* should be "(nchannels, sampwidth, framerate,
      nframes, comptype, compname)", with values valid for the
      "set*()" methods.  Sets all parameters.

   getparams()

      Return a "namedtuple()" "(nchannels, sampwidth, framerate,
      nframes, comptype, compname)" containing the current output
      parameters.

   tell()

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

   writeframesraw(data)

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

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

   writeframes(data)

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

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

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