"sunau" --- Sun AUファイルの読み書き
************************************

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

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

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

"sunau" モジュールは、Sun AUサウンドフォーマットへの便利なインターフェ
ースを提供します。このモジュールは、 "aifc" モジュールや "wave" モジュ
ールと互換性のあるインターフェースを備えています。

オーディオファイルはヘッダとそれに続くデータから構成されます。ヘッダの
フィールドは以下の通りです:

+-----------------+-------------------------------------------------+
| フィールド      | 内容                                            |
|=================|=================================================|
| magic word      | 4バイト文字列 ".snd"。                          |
+-----------------+-------------------------------------------------+
| header size     | infoを含むヘッダのサイズをバイト数で示したもの  |
|                 | 。                                              |
+-----------------+-------------------------------------------------+
| data size       | データの物理サイズをバイト数で示したもの。      |
+-----------------+-------------------------------------------------+
| encoding        | オーディオサンプルのエンコード形式。            |
+-----------------+-------------------------------------------------+
| sample rate     | サンプリングレート。                            |
+-----------------+-------------------------------------------------+
| # of channels   | サンプルのチャンネル数。                        |
+-----------------+-------------------------------------------------+
| info            | オーディオファイルについての説明をASCII文字列で |
|                 | 示したもの（null バイト で埋められます）。      |
+-----------------+-------------------------------------------------+

infoフィールド以外の全てのヘッダフィールドは4バイトの大きさです。ヘッ
ダフィールドはbig-endianでエンコードされた、計32ビットの符合なし整数で
す。

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

sunau.open(file, mode)

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

   "'r'"
      読み出しのみのモード。

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

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

   "'r'" の *mode* は "AU_read" オブジェクトを返し、 "'w'" と "'wb'"
   の *mode* は "AU_write" オブジェクトを返します。

"sunau" モジュールは以下の例外を定義しています:

exception sunau.Error

   Sun AUの仕様や実装に対する不適切な操作により何か実行不可能となった
   時に発生するエラー。

"sunau" モジュールは以下のデータアイテムを定義しています:

sunau.AUDIO_FILE_MAGIC

   big-endianで保存された正規のSun AUファイルは全てこの整数で始まりま
   す。これは文字列 ".snd" を整数に変換したものです。

sunau.AUDIO_FILE_ENCODING_MULAW_8
sunau.AUDIO_FILE_ENCODING_LINEAR_8
sunau.AUDIO_FILE_ENCODING_LINEAR_16
sunau.AUDIO_FILE_ENCODING_LINEAR_24
sunau.AUDIO_FILE_ENCODING_LINEAR_32
sunau.AUDIO_FILE_ENCODING_ALAW_8

   AUヘッダのencodingフィールドの値で、このモジュールでサポートしてい
   るものです。

sunau.AUDIO_FILE_ENCODING_FLOAT
sunau.AUDIO_FILE_ENCODING_DOUBLE
sunau.AUDIO_FILE_ENCODING_ADPCM_G721
sunau.AUDIO_FILE_ENCODING_ADPCM_G722
sunau.AUDIO_FILE_ENCODING_ADPCM_G723_3
sunau.AUDIO_FILE_ENCODING_ADPCM_G723_5

   AUヘッダのencodingフィールドの値のうち既知のものとして追加されてい
   るものですが、このモジュールではサポートされていません。


AU_read オブジェクト
====================

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

AU_read.close()

   ストリームを閉じ、このオブジェクトのインスタンスを使用できなくしま
   す。（これはオブジェクトのガベージコレクション時に自動的に呼び出さ
   れます。）

AU_read.getnchannels()

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

AU_read.getsampwidth()

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

AU_read.getframerate()

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

AU_read.getnframes()

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

AU_read.getcomptype()

   圧縮形式を返します。"'ULAW'", "'ALAW'", "'NONE'" がサポートされてい
   る形式です。

AU_read.getcompname()

   "getcomptype()" を人に判読可能な形にしたものです。上述の形式に対し
   て、それぞれ "'CCITT G.711 u-law'", "'CCITT G.711 A-law'", "'not
   compressed'" がサポートされています。

AU_read.getparams()

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

AU_read.readframes(n)

   *n* 個のオーディオフレームの値を読み込んで、 "bytes" オブジェクトを
   返します。データはlinear形式で返されます。もし元のデータがu-LAW形式
   なら、変換されます。

AU_read.rewind()

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

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

AU_read.setpos(pos)

   ファイルのポインタを指定した位置に設定します。 "tell()" で返される
   値を *pos* として使用しなければなりません。

AU_read.tell()

   ファイルの現在のポインタ位置を返します。返される値はファイルの実際
   の位置に対して何も操作はしません。

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

AU_read.getmarkers()

   "None" を返します。

AU_read.getmark(id)

   エラーを発生します。


AU_write オブジェクト
=====================

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

AU_write.setnchannels(n)

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

AU_write.setsampwidth(n)

   サンプルサイズを（バイト数で）設定します。

   バージョン 3.4 で変更: 24-bit サンプルのサポートが追加されました。

AU_write.setframerate(n)

   フレームレートを設定します。

AU_write.setnframes(n)

   フレーム数を設定します。あとからフレームが書き込まれるとフレーム数
   は変更されます。

AU_write.setcomptype(type, name)

   圧縮形式とその記述を設定します。"'NONE'" と "'ULAW'" だけが、出力時
   にサポートされている形式です。

AU_write.setparams(tuple)

   *tuple* は "(nchannels, sampwidth, framerate, nframes, comptype,
   compname)" で、それぞれ "set*()" のメソッドの値にふさわしいものでな
   ければなりません。全ての変数を設定します。

AU_write.tell()

   ファイルの中の現在位置を返します。 "AU_read.tell()" と
   "AU_read.setpos()" メソッドでお断りしたことがこのメソッドにも当ては
   まります。

AU_write.writeframesraw(data)

   *nframes* の修正なしにオーディオフレームを書き込みます。

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

AU_write.writeframes(data)

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

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

AU_write.close()

   *nframes* が正しいか確認して、ファイルを閉じます。

   このメソッドはオブジェクトの削除時に呼び出されます。

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