##
1 オーディオデバイスオブジェクト

オーディオデバイスに読み書きできるようになるには、まず 3 つのメソッドを正しい順序で呼び出さねばなりません:

1. `setfmt()` で出力形式を設定し、
2. `channels()` でチャンネル数を設定し、
3. `speed()` でサンプリングレートを設定します。

この代わりに`setparameters()` メソッドを呼び出せば、 三つのオーディオパラメタを一度で設定できます。 `setparameters()` は便利ですが、多くの状況で 柔軟性に欠けるでしょう。

`open()` の返すオーディオデバイスオブジェクトには以下のメ ソッドおよび(読み出し専用の)属性があります:

`close`( | )

  オーディオデバイスを明示的に閉じます。 オーディオデバイスは、読み出しや書き込みが終了したら必ず 閉じねばなりません。閉じたオブジェクトを再度開くことは できません。

`fileno`( | )

  デバイスに関連付けられているファイル記述子を返します。

`read`( | size)

  オーディオ入力から size バイトを読みだし、 Python 文字列型に して返します。多くの Unix デバイスドライバと違い、 ブロックデバイスモード (デフォルト) の OSS オーディオデバイスでは、 要求した量のデータ全体を取り込むまで`read()` がブロックします。

`write`( | data)

  Python 文字列 data の内容をオーディオデバイスに書き込み、 書き込まれたバイト数を返します。オーディオデバイスがブロックモード (デフォルト) の場合、常に文字列データ全体を書き込みます (前述の ように、これは通常のUnix デバイスの振舞いとは異なります)。 デバイスが非ブロックモードの場合、データの一部が書き込まれない ことがあります -- `writeall()` を参照してください。

`writeall`( | data)

  Python文字列のdata全体をオーディオデバイスに書き込みます。 オーディオデバイスがデータを受け取れるようになるまで待機し、 書き込めるだけのデータを書き込むという操作を、data を 全て書き込み終わるまで繰り返します。 デバイスがブロックモード (デフォルト) の場合には、このメソッドは `write()` と同じです。`writeall()` が有用なのは 非ブロックモードだけです。実際に書き込まれたデータの量と渡した データの量は必ず同じになるので、戻り値はありません。

以下のメソッドの各々は `ioctl()` システムコール 一つ一つに対応しています。対応関係ははっきりしています: 例えば、`setfmt()` は `SNDCTL_DSP_SETFMT` ioctl に対応していますし、`sync()` は`SNDCTL_DSP_SYNC` に対応しています (このシンボル名は OSS のドキュメントを参照する 時に助けになるでしょう)。根底にある `ioctl()` が 失敗した場合、これらの関数は全て `IOError` を 送出します。

`nonblock`( | )

  デバイスを非ブロックモードにします。 いったん非ブロックモードにしたら、ブロックモードは戻せません。

`getfmts`( | )

  サウンドカードがサポートしているオーディオ出力形式をビットマスクで 返します。 以下はOSSでサポートされているフォーマットの一部です。

  フォーマット | 説明
  --- | ---

  AFMT_MU_LAW | 対数符号化 (Sun の `.au` 形式や /dev/audio で使われている形式)
  AFMT_A_LAW | 対数符号化
  AFMT_IMA_ADPCM | Interactive Multimedia Association で 定義されている 4:1 圧縮形式
  AFMT_U8 | 符号なし 8 ビットオーディオ
  AFMT_S16_LE | 符号つき 16 ビットオーディオ、リトルエンディアン バイトオーダ (Intelプロセッサで使われている形式)
  AFMT_S16_BE | 符号つき 16 ビットオーディオ、ビッグエンディアン バイトオーダ (68k、PowerPC、Sparcで使われている形式)
  AFMT_S8 | 符号つき 8 ビットオーディオ
  AFMT_U16_LE | 符号なし 16 ビットリトルエンディアンオーディオ
  AFMT_U16_BE | 符号なし 16 ビットビッグエンディアンオーディオ

  オーディオ形式の完全なリストは OSS の文書をひもといてください。 ただ、ほとんどのシステムは、こうした形式のサブセットしかサポートしていません。 古めのデバイスの中には `AFMT_U8` だけしかサポートしていないものがあります。 現在使われている最も一般的な形式は`AFMT_S16_LE`です。

`setfmt`( | format)

  現在のオーディオ形式をformatに設定しようと試みます -- formatについては`getfmts()`のリストを参照してください。 実際にデバイスに設定されたオーディオ形式を返します。要求通りの 形式でないこともあります。`AFMT_QUERY` を渡すと 現在デバイスに設定されているオーディオ形式を返します。

`channels`( | num_channels)

  出力チャネル数をnum_channelsに設定します。 1 はモノラル、2 はステレオです。 いくつかのデバイスでは2つより多いチャンネルを持つものもありますし、 ハイエンドなデバイスではモノラルをサポートしないものもあります。 デバイスに設定されたチャンネル数を返します。

`speed`( | samplerate)

  サンプリングレートを1秒あたりsamplerate に設定しようと試み、 実際に設定されたレートを返します。 たいていのサウンドデバイスでは任意のサンプリングレートをサポートしていま せん。 一般的なレートは以下の通りです:

  レート | 説明
  --- | ---
  8000 | /dev/audio のデフォルト
  11025 | 会話音声の録音に使われるレート
  22050 |
  44100 | (サンプルあたり 16 ビットで 2 チャネルの場合) CD 品質のオーディオ
  96000 | (サンプル当たり 24 ビットの場合) DVD 品質のオーディオ

`sync`( | )

  サウンドデバイスがバッファ内の全てのデータを再生し終えるまで待機します。 (デバイスを閉じると暗黙のうちに `sync()` が起こります) OSS の ドキュメント上では、`sync()` を使うよりデバイスを一度閉じて 開き直すよう勧めています。

`reset`( | )

  再生あるいは録音を即座に中止して、デバイスをコマンドを受け取れる状態に 戻します。OSSのドキュメントでは、`reset()` を呼び出した後に 一度デバイスを閉じ、開き直すよう勧めています。

`post`( | )

  ドライバに出力の一時停止 (pause) が起きそうであることを伝え、 ドライバが一時停止をより賢く扱えるようにします。 短いサウンドエフェクトを再生した直後やユーザ入力待ちの前、また ディスク I/O 前などに使うことになるでしょう。

以下のメソッドは、複数の `ioctl` を組み合わせたり、 `ioctl` と単純な計算を組み合わせたりした便宜用メソッドです。

`setparameters`( | format, nchannels, samplerate, [, strict=False])

  主要なオーディオパラメタ、サンプル形式、チャネル数、サンプルレートを 一つのメソッド呼び出しで設定します。 format、nchannels および samplerate には、 それぞれ`setfmt()`、`channels()` および `speed()` と同じやり方で値を設定します。strict の値が真の場合、 `setparameters()` は値が実際に要求通りにデバイスに設定されたか どうか調べ、違っていれば `OSSAudioError` を送出します。 実際にデバイスドライバが設定したパラメタ値を表す (format, nchannels, samplerate) からなるタプルを 返します (`setfmt()`、`channels()` および `speed()` の返す値と同じです)。

  以下に例を示します:

        (fmt, channels, rate) = dsp.setparameters(fmt, channels, rate)

  is equivalent to

        fmt = dsp.setfmt(fmt)
        channels = dsp.channels(channels)
        rate = dsp.rate(channels)

`bufsize`( | )

  ハードウェアのバッファサイズをサンプル数で返します。

`obufcount`( | )

  ハードウェアバッファ上に残っていてまだ再生されていないサンプル数を返します。

`obuffree`( | )

  ブロックを起こさずにハードウェアの再生キューに書き込めるサンプル数を返します。

オーディオデバイスオブジェクトは読み出し専用の属性もサポートしています:

`closed`
  デバイスが閉じられたかどうかを示す真偽値です。

`name`
  デバイスファイルの名前を含む文字列です。

`mode`
  ファイルの I/O モードで、`"r"`, `"rw"`, `"w"` のどれかです。