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 で変更: 拡張形式が KSDATAFORMAT_SUBTYPE_PCM の場合に、WAVE_FORMAT_EXTENSIBLE ヘッダに対応するようになりました。

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

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

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

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

exception wave.Error

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

Wave_read オブジェクト

class wave.Wave_read

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

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

close()

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

getnchannels()

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

getsampwidth()

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

getframerate()

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

getnframes()

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

getcomptype()

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

getcompname()

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

getparams()

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

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 を返します。

Deprecated since version 3.13, will be removed in version 3.15: The method only existed for compatibility with the aifc module which has been removed in Python 3.13.

getmark(id)

エラーを発生します。

Deprecated since version 3.13, will be removed in version 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

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

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)

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

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

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