# `wave` --- WAV ファイルの読み書き

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

The `wave` module provides a convenient interface to the Waveform Audio "WAVE" (or "WAV") file format.

The module supports uncompressed PCM and IEEE floating-point WAV formats.

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

バージョン 3.15 で変更: Support for reading and writing `WAVE_FORMAT_IEEE_FLOAT` files was added.

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

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

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

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

exception wave.Error

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

wave.WAVE_FORMAT_PCM

  Format code for uncompressed PCM audio.

wave.WAVE_FORMAT_IEEE_FLOAT

  Format code for IEEE floating-point audio.

wave.WAVE_FORMAT_EXTENSIBLE

  Format code for WAVE extensible headers.

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

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

  getformat()

    Returns the frame format code.

    This is one of `WAVE_FORMAT_PCM`, `WAVE_FORMAT_IEEE_FLOAT`, or `WAVE_FORMAT_EXTENSIBLE`.

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

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

  以下の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 バイトに設定します。

    For `WAVE_FORMAT_IEEE_FLOAT`, only 4-byte (32-bit) and 8-byte (64-bit) sample widths are supported.

  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.

  setformat(format)

    Set the frame format code.

    Supported values are `WAVE_FORMAT_PCM` and `WAVE_FORMAT_IEEE_FLOAT`.

    When setting `WAVE_FORMAT_IEEE_FLOAT`, the sample width must be 4 or 8 bytes.

  getformat()

    Return the current frame format code.

  setparams(tuple)

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

    For backwards compatibility, a 6-item tuple without format is also accepted and defaults to `WAVE_FORMAT_PCM`.

    For `format=WAVE_FORMAT_IEEE_FLOAT`, sampwidth must be 4 or 8.

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

    For `WAVE_FORMAT_IEEE_FLOAT` output, a `fact` chunk is written as required by the WAVE specification for non-PCM formats.