PsychPortAudio('Open')

pahandle = PsychPortAudio('Open' [, deviceid][, mode][, reqlatencyclass][, freq][, channels][, buffersize][, suggestedLatency][, selectchannels][, specialFlags=0]);

PortAudio のデバイスを開いて初期化します。返り値は、そのデバイスを扱うためのハンドル(pahandle)です。

すべてのパラメーター(引数)はオプションで、適切なデフォルトの値が決まっています。

'deviceid' PortAudioでサポートされた様々な論理オーディオデバイスの中から選択します。デフォルトはシステム(パソコン)がデフォルトとして選択したものです。

異なったデバイスIDでも、物理的には同じデバイスを意味していることがありますが、低次のサウンドシステムでの扱われ方は異なっています。

(例えばWindowsでは5つぐらいの異なったサウンドシステムがあります)

'mode' 操作方法の種類を表します。デフォルトは1で、音(聴覚刺激)の再生(playback)のみです。

モード2は録音(capture)。

モード3は録音と再生を同時に。 (full duplex とも呼ばれます) 信頼性が低いので注意すること。Matlabがフリーズするかも。

モード3がうまく機能しないときは、モード7というのもあります。これは full duplex デバイスでのみ機能して、入力と出力のチャンネルを同じ数だけ使っている必要があります。またこのモードでは、キャプチャした音をそのままダイレクトに、最小のlatencyで、プログラムに変更を加えることなく、スピーカーにフィードバックしますが、この間キャプチャはできず(パソコンに保存できないということ?)時間制御もできません。

モード8は、マスターデバイス(?)を指定する場合です。マスターデバイスは、再生や録音時に直接使われることはありません。代わりに、マスターデバイスに付随した様々なスレーブデバイスを作成することができます。スレーブデバイスのそれぞれは、マスタースレーブのチャンネルを経由して、独立する形で、再生・録音することが可能です。これはサウンドカードの仮想化ということです。より詳しくは、PsychPortAudio('OpenSlave?') をご覧ください。

'reqlatencyclass' PsychPortAudio が、音が再生されるまでにかかる時間(latency)をなるべく短くするため、時間制御を確実に行うためにどれぐらい無茶をするか(aggressive)を決めるためのものです。言い換えれば [latency] vs [システムの負荷と他のアプリへの影響] のトレードオフです。

0は、latency のことは考慮しません。これはどんな状況下でも適切に動作します。(訳注 実験には不向きでしょう)

1は(デフォルト)latencyがなるべく低くなるようにしつつも、それなりの信頼性を保ち、他のアプリにも影響を与えません。

2は、他のアプリに悪影響を与えるかもしれませんが、オーディオデバイスをフルコントロールします。

3は、2とほぼ同じですが、最もアグレッシブな設定です(?)

4は、3とほぼ同じですが、デバイスが厳しい条件を満たさないと失敗してしまいます。

(PsychPortAudioTimingTestのなかで次のような記述があり、'reqlatencyclass' は2がよいようです
% Request latency mode 2, which used to be the best one in our measurement:
% classes 3 and 4 didn't yield any improvements, sometimes they even caused
% problems.)

'freq' は、再生・録音時のサンプリングレートです。単位はHz。

デフォルトは、latency のモードに依存します。

'channels' 使用するチャンネル数を指定します。デフォルトは2でステレオを意味します。

再生と録音を同時に行いたいときは、2つの要素のベクトルを与えます。それぞれが出力チャンネルと、入力チャンネルを表します。

1番目の要素は、再生チャンネルです。2番目の要素はキャプチャ(録音)チャンネルです。

例えば、[2, 1] は、2つの再生チャンネル(ステレオ)と1つの録音チャンネルを意味します。

マルチチャンネルのサウンドカードを使うときの引数 'selectchannels' も参照してください。

'buffersize' は内部のオーディオバッファー(音のデータを保存する場所)のサイズと数を指定します。

この値が小さいほど、latencyが低くなりますが、システムへの負荷は大きくなります。

(PsychPortAudioTimingTestではゼロになっています)

'suggestedLatency' latencyを秒単位で指定します。

PortAudioは、出力時のlatencyを小さくするために、デバイス内部プロパティと同様に、サンプリングレート、'suggestedLatency' 、バッファーサイズに依存して内部のパラメーターを決定します。

基本的には'suggestedLatency' を指定する必要はなく(Best left alone はそういう意味?)、自動調整がうまく行かない場合のみ、手動でこの値を指定して下さい。

'selectchannels' 論理チャンネルを、デバイス(物理)チャンネルにマッピングする行列です。

もし、サウンドカードの複数あるチャンネルのうちのいくつかだけを使用したい場合(例えば、16チャンネルのサウンドカードで、2つの再生チャンネルのみを使う場合)、'channels' を2にします。

'selectchannels' は、16チャンネルのうちどの2チャンネルを再生用に使いたいかを選択することができます。

'selectchannels' は、再生または録音のための、行ベクトル(列数は'channels' で指定した値)です。

full-duplex mode では2行の行列(列数は'channels' の最大値。再生チャンネルと録音チャンネルの大きいほう?)になり、1行目が再生チャンネルのマッピング、2行目がキャプチャチャンネルのマッピングを表します。

いずれの場合でも、i 列の数字は、どの物理デバイスチャンネルがi 番目のPsychPortAudioチャンネルの再生(または録音)に使われるかを決定します。

物理デバイスチャンネルの番号付けはゼロから始まる(1からではない)ので注意すること。

例:再生と同時に録音を行い、かつ'channels' は2に設定してあるとき(すなわち、再生チャンネル数2、録音チャンネル数2)

'selectchannels' が [0, 6 ; 12, 14] であるならば、デバイスチャンネル0と6から音が出て、デバイスチャンネ12と14からの音を録音する。

チャンネルの選択は、ASIOサウンドカードに対応したWindowsでのみ可能。それ以外の環境ではパラメーターは無視されます。

'specialFlags' については理解不足のため、原文をそのまま記載しておきます。

'specialFlags' Optional flags: Default to zero, can be or'ed or added together with the following flags/settings:

1 = Never prime output stream. By default the output stream is primed. Don't bother if you don't know what this means.

2 = Always clamp audio data to the valid -1.0 to 1.0 range. Clamping is enabled by default.

4 = Never clamp audio data.

8 = Always dither output audio data. By default, dithering is enabled in normal

mode, and disabled in low-latency mode. Dithering adds a stochastic noise

pattern to the least significant bit of each output sample to reduce the impact

of audio quantization artifacts. Dithering can improve signal to noise ratio and

quality of output sound, but it is more compute intense and it could change very

low-level properties of the audio signal, because what you hear is not exactly

what you specified.

16 = Never dither audio data, not even in normal mode.