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

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

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

"wave" モジュールは、WAVサウンドフォーマットへの便利なインターフェイス
を提供するモジュールです。このモジュールは圧縮／展開をサポートしていま
せんが、モノラル／ステレオには対応しています。

"wave" モジュールは、以下の関数と例外を定義しています:

wave.open(file[, mode])

   *file* が文字列ならその名前のファイルを開き、そうでないならシーク可
   能な file like オブジェクトとして扱います。 *mode* は以下のうちのい
   ずれかです。

   "'r'", "'rb'"
      読み込みのみのモード。

   "'w'", "'wb'"
      書き込みのみのモード。

   WAVファイルに対して読み込み／書き込み両方のモードで開くことはできな
   いことに注意して下さい。

   "'r'" と "'rb'" の *mode* は "Wave_read" オブジェクトを返し、 "'w'"
   と "'wb'" の *mode* は "Wave_write" オブジェクトを返します。 *mode*
   が省略されていて、ファイルのようなオブジェクトが *file* として渡さ
   れると、 "file.mode" が *mode* のデフォルト値として使われます（必要
   であれば、さらにフラグ "'b'" が付け加えられます）。

   file like オブジェクトを渡した場合、 wave オブジェクトの "close()"
   メソッドを呼び出してもその file like オブジェクトを close しません
   。 file like オブジェクトの close は呼び出し側の責任になります。

wave.openfp(file, mode)

   "open()" と同義。後方互換性のために残されています。

exception wave.Error

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


21.5.1. 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)" のタプルを返します。

Wave_read.readframes(n)

   現在のポインタから *n* 個のオーディオフレームの値を読み込んで、バイ
   トごとに文字に変換して文字列を返します。

Wave_read.rewind()

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

以下の2つのメソッドは "aifc" モジュールとの互換性のために定義されてお
り、何も面白いことはしません。

Wave_read.getmarkers()

   "None" を返します。

Wave_read.getmark(id)

   エラーを発生します。

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

Wave_read.setpos(pos)

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

Wave_read.tell()

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


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

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

Wave_write.close()

   *nframes* が正しいか確認して、ファイルが "wave" によって開かれてい
   た場合は閉じます。このメソッドはオブジェクトがガベージコレクション
   されるときに呼び出されます。

Wave_write.setnchannels(n)

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

Wave_write.setsampwidth(n)

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

Wave_write.setframerate(n)

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

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* の修正なしにオーディオフレームを書き込みます。

Wave_write.writeframes(data)

   オーディオフレームを書き込んで *nframes* を修正します。

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