40.1. "sunaudiodev" --- Sun オーディオハードウェアへのアクセス
**************************************************************

バージョン 2.6 で非推奨: "sunaudiodev" モジュールは Python 3 で削除さ
れました。

このモジュールを使うと、Sun のオーディオインターフェースにアクセスでき
ます。 Sun オーディオハードウェアは、1 秒あたり 8k のサンプリングレー
ト、 u-LAW フォーマットでオーディオデータを録音、再生できます。完全な
説明文書はマニュアルページ *audio(7I)* にあります。

モジュール "SUNAUDIODEV" には、このモジュールで使われる定数が定義され
ています。

このモジュールには、以下の変数と関数が定義されています:

exception sunaudiodev.error

   この例外は、全てのエラーについて発生します。引数は誤りを説明する文
   字列です。

sunaudiodev.open(mode)

   この関数はオーディオデバイスを開き、Sun オーディオデバイスのオブジ
   ェクトを返します。こうすることで、オブジェクトが I/O に使用できるよ
   うになります。パラメータ *mode* は次のうちのいずれか一つで、録音の
   みには "'r'" 、再生のみには "'w'" 、録音と再生両方には "'rw'" 、コ
   ントロールデバイスへのアクセスには "'control'" です。レコーダーやプ
   レーヤーには同時に  １つのプロセスしかアクセスが許されていないので
   、必要な動作についてだけデバイスをオープンするのがいい考えです。詳
   しくは *audio(7I)* を参照してください。

   マニュアルページにあるように、このモジュールは環境変数 "AUDIODEV"
   の中のベースオーディオデバイスファイルネームを初めに参照します。見
   つからない場合は "/dev/audio" を参照します。コントロールデバイスに
   ついては、ベースオーディオデバイスに "ctl" を加えて扱われます。


40.1.1. オーディオデバイスオブジェクト
======================================

オーディオデバイスオブジェクトは "open()" で返され、このオブジェクトに
は以下のメソッドが定義されています ("control" オブジェクトは除きます。
これには "getinfo()" 、 "setinfo()" 、 "fileno()" 、 "drain()" だけが
定義されています）:

audio device.close()

   このメソッドはデバイスを明示的に閉じます。オブジェクトを削除しても
   、それを参照しているものがあって、すぐに閉じてくれない場合に便利で
   す。閉じられたデバイスを使うことはできません。

audio device.fileno()

   デバイスに関連づけられたファイルディスクリプタを返します。これは、
   後述の "SIGPOLL" の通知を組み立てるのに使われます。

audio device.drain()

   このメソッドは全ての出力中のプロセスが終了するまで待って、それから
   制御が戻ります。このメソッドの呼び出しはそう必要ではありません：オ
   ブジェクトを削除すると自動的にオーディオデバイスを閉じて、暗黙のう
   ちに吐き出します。

audio device.flush()

   このメソッドは全ての出力中のものを捨て去ります。ユーザの停止命令に
   対する反応の遅れ（1 秒までの音声のバッファリングによって起こります
   ）を避けるのに使われます。

audio device.getinfo()

   このメソッドは入出力のボリューム値などの情報を引き出して、オーディ
   オステータスのオブジェクト形式で返します。このオブジェクトには何も
   メソッドはありませんが、現在のデバイスの状態を示す多くの属性が含ま
   れます。属性の名称と意味は "<sun/audioio.h>" と *audio(7I)* に記載
   があります。メンバー名は相当する C のものとは少し違っています：ステ
   ータスオブジェクトは１つの構造体です。その中の構造体である "play"
   のメンバーには名前の初めに "o_" がついていて、 "record" には "i_"
   がついています。そのため、C のメンバーである "play.sample_rate" は
   "o_sample_rate" として、 "record.gain" は "i_gain" として参照され、
   "monitor_gain" はそのまま "monitor_gain" で参照されます。

audio device.ibufcount()

   このメソッドは録音側でバッファリングされるサンプル数を返します。つ
   まり、プログラムは同じ大きさのサンプルに対する "read()" の呼び出し
   をブロックしません。

audio device.obufcount()

   このメソッドは再生側でバッファリングされるサンプル数を返します。残
   念ながら、この数値はブロックなしに書き込めるサンプル数を調べるのに
   は使えません。というのは、カーネルの出力キューの長さは可変だからで
   す。

audio device.read(size)

   このメソッドはオーディオ入力から *size* のサイズのサンプルを読み込
   んで、Python の文字列として返します。この関数は必要なデータが得られ
   るまで他の操作をブロックします。

audio device.setinfo(status)

   This method sets the audio device status parameters. The *status*
   parameter is a device status object as returned by "getinfo()" and
   possibly modified by the program.

audio device.write(samples)

   パラメータとしてオーディオサンプルを Python 文字列を受け取り、再生
   します。もし十分なバッファの空きがあればすぐに制御が戻り、そうでな
   いならブロックされます。

オーディオデバイスは SIGPOLL を介して様々なイベントの非同期通知に対応
しています。 Python でこれをどのようにしたらできるか、例を挙げます：

   def handle_sigpoll(signum, frame):
       print 'I got a SIGPOLL update'

   import fcntl, signal, STROPTS

   signal.signal(signal.SIGPOLL, handle_sigpoll)
   fcntl.ioctl(audio_obj.fileno(), STROPTS.I_SETSIG, STROPTS.S_MSG)


40.2. "SUNAUDIODEV" --- "sunaudiodev" で使われる定数
****************************************************

バージョン 2.6 で非推奨: "SUNAUDIODEV" モジュールは Python 3 で削除さ
れました。

これは "sunaudiodev" に付随するモジュールで、 "MIN_GAIN" 、 "MAX_GAIN"
、 "SPEAKER" などの便利なシンボル定数を定義しています。定数の名前は C
の include ファイル "<sun/audioio.h>" のものと同じで、初めの文字列
"AUDIO_" を除いたものです。
