# `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()` メソッドを呼び出したあとで、どんなパラメータを設定しようとしても不正となることに注意して下さい。