# `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 で変更: シーク不能なファイルのサポートが追加されました。

exception `wave.``Error`

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

## 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`()

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

## 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` を発生します。