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)を返します。
- 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チャンクを書き込みます。