"aifc" --- AIFFおよびAIFCファイルの読み書き
*******************************************

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

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The "aifc"
module is deprecated (see **PEP 594** for details).

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

このモジュールはAIFFとAIFF-Cファイルの読み書きをサポートします。AIFF（
Audio Interchange File Format）はデジタルオーディオサンプルをファイル
に保存するためのフォーマットです。AIFF-CはAIFFの新しいバージョンで、オ
ーディオデータの圧縮に対応しています。

オーディオファイルには、オーディオデータについて記述したパラメータがた
くさん含まれています。サンプリングレートあるいはフレームレートは、1秒
あたりのオーディオサンプル数です。チャンネル数は、モノラル、ステレオ、
4チャンネルかどうかを示します。フレームはそれぞれ、チャンネルごとに一
つのサンプルからなります。サンプルサイズは、一つのサンプルの大きさをバ
イト数で示したものです。したがって、一つのフレームは "nchannels *
samplesize" バイト からなり、1秒間では "nchannels * samplesize *
framerate" バイトで構成されます。

例えば、CD品質のオーディオは2バイト（16ビット）のサンプルサイズを持っ
ていて、2チャンネル（ステレオ）であり、44,100フレーム／秒のフレームレ
ートを持っています。そのため、フレームサイズは4バイト（2*2）で、1秒間
では2*2*44100バイト（176,400バイト）になります。

"aifc" モジュールは以下の関数を定義しています:

aifc.open(file, mode=None)

   AIFFあるいはAIFF-Cファイルを開き、後述するメソッドを持つインスタン
   スを返します。引数 *file* はファイルを示す文字列か、 *file object*
   のいずれかです。 *mode* は、読み込み用に開くときには "'r'" か
   "'rb'" のどちらかでなければならず、書き込み用に開くときには "'w'"
   か "'wb'" のどちらかでなければなりません。もし省略されたら、
   "file.mode" が存在すればそれが使用され、なければ "'rb'" が使われま
   す。書き込み用にこのメソッドを使用するときには、これから全部でどれ
   だけのサンプル数を書き込むのか分からなかったり、 "writeframesraw()"
   と "setnframes()" を使わないなら、ファイルオブジェクトはシーク可能
   でなければなりません。"open()" 関数は "with" 文の中で使われるかもし
   れません。"with" ブロックの実行が終了したら、"close()" メソッドが呼
   び出されます。

   バージョン 3.4 で変更: "with" 構文のサポートが追加されました。

ファイルが "open()" によって読み込み用に開かれたときに返されるオブジェ
クトには、以下のメソッドがあります:

aifc.getnchannels()

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

aifc.getsampwidth()

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

aifc.getframerate()

   サンプリングレート（1秒あたりのオーディオフレーム数）を返します。

aifc.getnframes()

   ファイルの中のオーディオフレーム数を返します。

aifc.getcomptype()

   オーディオファイルで使用されている圧縮形式を示す4バイトの bytes を
   返します。AIFFファイルでは "b'NONE'" が返されます。

aifc.getcompname()

   オーディオファイルの圧縮形式を人に判読可能な形に変換できる bytes で
   返します。AIFFファイルでは "b'not compressed'" が返されます。

aifc.getparams()

   "get*()" メソッドが返すのと同じ "(nchannels, sampwidth, framerate,
   nframes, comptype, compname)" の "namedtuple()" を返します。

aifc.getmarkers()

   オーディオファイルのマーカーのリストを返します。一つのマーカーは三
   つの要素のタプルです。要素の1番目はマークID（整数）、2番目はマーク
   位置のフレーム数をデータの始めから数えた値（整数）、3番目はマークの
   名称（文字列）です。

aifc.getmark(id)

   与えられた *id* のマークの要素を "getmarkers()" で述べたタプルで返
   します。

aifc.readframes(nframes)

   オーディオファイルの次の *nframes* 個のフレームを読み込んで返します
   。返されるデータは、全チャンネルの圧縮されていないサンプルをフレー
   ムごとに文字列にしたものです。

aifc.rewind()

   読み込むポインタをデータの始めに巻き戻します。次に "readframes()"
   を使用すると、データの始めから読み込みます。

aifc.setpos(pos)

   指定したフレーム数の位置にポインタを設定します。

aifc.tell()

   現在のポインタのフレーム位置を返します。

aifc.close()

   AIFFファイルを閉じます。このメソッドを呼び出したあとでは、オブジェ
   クトはもう使用できません。

ファイルが "open()" によって書き込み用に開かれたときに返されるオブジェ
クトには、 "readframes()" と "setpos()" を除く上述の全てのメソッドがあ
ります。さらに以下のメソッドが定義されています。 "get*()" メソッドは、
対応する "set*()" を呼び出したあとでのみ呼び出し可能です。最初に
"writeframes()" あるいは "writeframesraw()" を呼び出す前に、フレーム数
を除く全てのパラメータが設定されていなければなりません。

aifc.aiff()

   AIFFファイルを作ります。デフォルトではAIFF-Cファイルが作られますが
   、ファイル名が "'.aiff'" で終わっていればAIFFファイルが作られます。

aifc.aifc()

   AIFF-Cファイルを作ります。デフォルトではAIFF-Cファイルが作られます
   が、ファイル名が "'.aiff'" で終わっていればAIFFファイルが作られます
   。

aifc.setnchannels(nchannels)

   オーディオファイルのチャンネル数を設定します。

aifc.setsampwidth(width)

   オーディオのサンプルサイズをバイト数で設定します。

aifc.setframerate(rate)

   サンプリングレートを1秒あたりのフレーム数で設定します。

aifc.setnframes(nframes)

   オーディオファイルに書き込まれるフレーム数を設定します。もしこのパ
   ラメータが設定されていなかったり正しくなかったら、ファイルはシーク
   に対応していなければなりません。

aifc.setcomptype(type, name)

   圧縮形式を設定します。もし設定しなければ、オーディオデータは圧縮さ
   れません。AIFFファイルは圧縮できません。name 引数は人間が読める圧縮
   形式の説明を bytes にしたもので、type 引数は4バイトの bytes でなけ
   ればなりません。現在のところ、以下の圧縮形式がサポートされています
   ： "b'NONE'", "b'ULAW'", "b'ALAW'", "b'G722'"。

aifc.setparams(nchannels, sampwidth, framerate, comptype, compname)

   上の全パラメータを一度に設定します。引数はそれぞれのパラメータから
   なるタプルです。つまり、 "setparams()" の引数として、 "getparams()"
   を呼び出した結果を使うことができます。

aifc.setmark(id, pos, name)

   指定したID（1以上）、位置、名称でマークを加えます。このメソッドは、
   "close()" の前ならいつでも呼び出すことができます。

aifc.tell()

   出力ファイルの現在の書き込み位置を返します。 "setmark()" との組み合
   わせで使うと便利です。

aifc.writeframes(data)

   出力ファイルにデータを書き込みます。このメソッドは、オーディオファ
   イルのパラメータを設定したあとでのみ呼び出し可能です。

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

aifc.writeframesraw(data)

   オーディオファイルのヘッダ情報が更新されないことを除いて、
   "writeframes()" と同じです。

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

aifc.close()

   AIFFファイルを閉じます。ファイルのヘッダ情報は、オーディオデータの
   実際のサイズを反映して更新されます。このメソッドを呼び出したあとで
   は、オブジェクトはもう使用できません。
