spAudio APIリファレンス

音声入出力

通常，音声入出力の流れは次のようになります．

1. spInitAudio
2. spSetAudioXXXで現在のデバイスに関する情報を設定する
3. spOpenAudioDevice
4. デバイスに関する情報が，必ずしも設定した値と同じとは限らないのでspGetAudioXXXを呼んで必要に応じて値をチェックする
5. 入力の場合はspReadAudioを，出力の場合はspWriteAudioを必要なだけ繰り返し呼ぶ． 入出力をやり直す場合などは，spSyncAudioを呼んでバッファをフラッシュする．
6. spCloseAudioDevice
7. spFreeAudio

spAudio

目的

音声入出力の関数を使用するために必要となります． メモリの確保と解放には，それぞれspInitAudioと spFreeAudio もしくは，それぞれspInitAudioDriverと spFreeAudioDriverを使用して下さい．

データ型

隠蔽されたデータ型です．

関連項目

spInitAudio, spFreeAudio spInitAudioDriver, spFreeAudioDriver

spGetNumAudioDriver, xspGetAudioDriverName

目的

オーディオドライバーの情報を取得します．

書式

#include <sp/spAudio.h> int spGetNumAudioDriver(void); char *xspGetAudioDriverName(int index);

引数

index

0始まりのインデックスを指定します． (spGetNumAudioDriverで返される値-1)までの値が指定できます．

戻り値

spGetNumAudioDriverでは，ドライバーの数が返ります． xspGetAudioDriverNameでは，メモリ確保されたドライバー名が返ります． xspFreeを呼び出してメモリ開放する必要があります．

説明

xspGetAudioDriverNameの戻り値をspInitAudioDriverの引数として使用できます．

関連項目

spInitAudioDriver

spInitAudio, spInitAudioDriver

目的

spAudioのメモリを確保し，音声入出力ドライバーを使用できる状態に初期化します．

書式

#include <sp/spAudio.h> spAudio spInitAudio(void); spAudio spInitAudioDriver(char *driver_name);

引数

driver_name

ドライバー名を指定します．

戻り値

メモリ確保されたspAudioが返ります．

説明

音声入出力に関する関数は，いずれかの関数を呼ばないと使用できません． 同一のドライバーを使用して複数回呼び出すことはできません． spInitAudioDriverを使用して別々のドライバーを使用した場合は， ドライバーや環境によっては，それぞれを独立して使用することができます．

関連項目

spFreeAudio

spFreeAudio, spFreeAudioDriver

目的

spAudioのメモリを解放し，音声入出力ドライバーの使用を停止します．

書式

#include <sp/spAudio.h> void spFreeAudio(spAudio audio); void spFreeAudioDriver(spAudio audio);

引数

audio

spInitAudioのコールにより返された spAudioを指定します．

説明

spInitAudioを呼び出した場合は，spFreeAudioを， spInitAudioDriverを呼び出した場合は， spFreeAudioDriverを呼び出します（実は，現在の実装では両者は同じものですが，将来的に変更の可能性もありますので）．
これらの関数を呼び出した後，再度音声入出力ドライバーを使用する場合には， spInitAudioもしくはspInitAudioDriverを呼び出して再初期化します．

関連項目

spInitAudio

spGetNumAudioDevice, xspGetAudioDeviceName, spSelectAudioDevice

目的

オーディオデバイス情報の取得・設定をします．

書式

#include <sp/spAudio.h> spBool spGetNumAudioDevice(spAudio audio, int *num_device); char *xspGetAudioDeviceName(spAudio audio, int device_index); spBool spSelectAudioDevice(spAudio audio, int device_index);

引数

num_device

デバイス数を受け取る変数のアドレスを指定します．

device_index

0始まりのデバイスのインデックスを指定します． (spGetNumAudioDeviceで返される値-1)までの値が指定できます． 0は，環境等によらず，常にデフォルトのデバイスに相当します．

戻り値

spGetNumAudioDevice，spSelectAudioDeviceについては，エラーが起きた場合は，SP_FALSEが返り，それ以外の場合は，SP_TRUEが返ります．
xspGetAudioDeviceNameでは，メモリ確保されたデバイス名が返ります． xspFreeを呼び出してメモリ開放する必要があります．

説明

spSelectAudioDeviceは，デバイスのオープンを行う前に呼ぶ必要があります．

関連項目

spInitAudioDriver

spSetAudioSampleRate, spGetAudioSampleRate

目的

spSetAudioSampleRateは，音声入出力に使用するサンプリング周波数を設定します． spGetAudioSampleRateは，デバイスが使用しているサンプリング周波数を得ます．

書式

#include <sp/spAudio.h> spBool spSetAudioSampleRate(spAudio audio, double samp_rate); spBool spGetAudioSampleRate(spAudio audio, double *samp_rate);

引数

audio

spInitAudioのコールにより返された spAudioを指定します．

samp_rate

サンプリング周波数をヘルツで指定します． spGetAudioSampleRateの場合は値を受け取る変数のアドレスを指定します．

戻り値

エラーが起きた場合は，SP_FALSEが返り，それ以外の場合は，SP_TRUEが返ります．

説明

spSetAudioSampleRateは，デバイスのオープンを行う前に呼んでください． spGetAudioSampleRateは，デバイスのオープン後に，デバイスにおける値を知ることができます． それまでは，単に現在設定されている値を返します．

spSetAudioChannel, spGetAudioChannel

目的

spSetAudioChannelは，音声入出力に使用するチャネル数を設定します． spGetAudioChannelは，デバイスの現在のチャネル数を得ます．

書式

#include <sp/spAudio.h> spBool spSetAudioChannel(spAudio audio, int num_channel); spBool spGetAudioChannel(spAudio audio, int *num_channel);

引数

audio

spInitAudioのコールにより返された spAudioを指定します．

num_channel

チャネル数を指定します． spGetAudioChannelの場合は値を受け取る変数のアドレスを指定します．

戻り値

エラーが起きた場合は，SP_FALSEが返り，それ以外の場合は，SP_TRUEが返ります．

説明

spSetAudioChannelは，デバイスのオープンを行う前に呼んでください． spGetAudioChannelは，デバイスのオープン後に，デバイスにおける値を知ることができます． それまでは，単に現在設定されている値を返します．

spSetAudioBufferSize, spGetAudioBufferSize

目的

spSetAudioBufferSizeは，音声入出力に使用するバッファーのサイズを設定します． spGetAudioBufferSizeは，デバイスの現在のバッファーサイズを得ます．

書式

#include <sp/spAudio.h> spBool spSetAudioBufferSize(spAudio audio, int buffer_size); spBool spGetAudioBufferSize(spAudio audio, int *buffer_size);

引数

audio

spInitAudioのコールにより返された spAudioを指定します．

buffer_size

バッファーのサイズを指定します． spGetAudioBufferSizeの場合は値を受け取る変数のアドレスを指定します．

戻り値

エラーが起きた場合は，SP_FALSEが返り，それ以外の場合は，SP_TRUEが返ります．

説明

spSetAudioBufferSizeは，デバイスのオープンを行う前に呼んでください． spGetAudioBufferSizeは，デバイスのオープン後に，デバイスにおける値を知ることができます． それまでは，単に現在設定されている値を返します．

バッファーサイズの最適値は環境によって異なります． この値が短すぎると音飛びが起こりますし，長すぎると遅延が発生します． 単に再生したり録音したりするだけであれば，8192程度以上を推奨します． また，フルデュプレックスで動作させる場合は，バッファーサイズを短くしないとかなりの遅延が発生するので， 音飛びが発生しない限界まで短くする程度が良いようです．

spSetAudioBlockingMode, spGetAudioBlockingMode

目的

spSetAudioBlockingModeは，音声入力のブロッキングモードを設定します． ノンブロッキングモードにすると，spReadAudioを呼んだ際に， 現在読み込まれている分だけをバッファーにコピーします． spGetAudioBlockingModeは，デバイスの現在のブロッキングモードを得ます．

書式

#include <sp/spAudio.h> spBool spSetAudioBlockingMode(spAudio audio, int block_mode); spBool spGetAudioBlockingMode(spAudio audio, int *block_mode);

引数

audio

spInitAudioのコールにより返された spAudioを指定します．

block_mode

モードを指定します．SP_AUDIO_BLOCKINGかSP_AUDIO_NONBLOCKINGのいずれかを指定します． spGetAudioBlockingModeの場合は値を受け取る変数のアドレスを指定します．

戻り値

エラーが起きた場合は，SP_FALSEが返り，それ以外の場合は，SP_TRUEが返ります．

説明

spSetAudioBlockingModeは，デバイスのオープンを行う前に呼んでください． デフォルトはブロックする設定になっています． なお，環境によっては，ブロッキングモードの設定を全くサポートしていません．

spSetAudioSampleBit, spGetAudioSampleBit

目的

spSetAudioSampleBitは，音声入出力に使用するbits/sampleを設定します． spGetAudioSampleBitは，デバイスの現在のbits/sampleを得ます．

書式

#include <sp/spAudio.h> spBool spSetAudioSampleBit(spAudio audio, int samp_bit); spBool spGetAudioSampleBit(spAudio audio, int *samp_bit);

引数

audio

spInitAudioのコールにより返された spAudioを指定します．

samp_bit

bits/sampleを指定します． spGetAudioSampleBitの場合は値を受け取る変数のアドレスを指定します．

戻り値

エラーが起きた場合は，SP_FALSEが返り，それ以外の場合は，SP_TRUEが返ります．

説明

spSetAudioSampleBitは，デバイスのオープンを行う前に呼んでください． spGetAudioSampleBitは，デバイスのオープン後に，デバイスにおける値を知ることができます． それまでは，単に現在設定されている値を返します．

現在は，16bit，24bit，32bitがサポートされています． 24bitと32bitの場合は16bitへ変換して再生します．

spOpenAudioDevice

目的

オーディオデバイスを開きます．

書式

#include <sp/spAudio.h> spBool spOpenAudioDevice(spAudio audio, char *mode);

引数

audio

spInitAudioのコールにより返された spAudioを指定します．

mode

開くモードを指定します．モードには，読み込みの"r"と，書き込みの "w"があります．環境によっては，読み込みのみを行うモードの"ro"と， 書き込みのみを行う"wo"が有効になります． これらを使用した場合，フルデュプレックスは使用できなくなりますが（環境によっては使用できます）， 音質が向上する場合があります（LinuxのOSSでは顕著な場合がありました）．

戻り値

エラーが起きた場合は，SP_FALSEが返り，それ以外の場合は，SP_TRUEが返ります．

説明

フルデュプレックスで開く場合は，読み込みモードと書き込みモードで1回づつ開いてください． この場合の開く順番は，読み込みモードを先に開くことを推奨します（将来的にはこの制約はなくなる可能性があります）． 使用している環境がフルデュプレックスに対応していない場合は，2番目のオープンに失敗します．

spCloseAudioDevice

目的

オーディオデバイスを閉じます．

書式

#include <sp/spAudio.h> spBool spCloseAudioDevice(spAudio audio);

引数

audio

spInitAudioのコールにより返された spAudioを指定します．

戻り値

エラーが起きた場合は，SP_FALSEが返り，それ以外の場合は，SP_TRUEが返ります．

spReadAudio, spReadAudioDouble, spReadAudioDoubleWeighted

目的

オーディオデバイスから，データを読み込みます．

書式

#include <sp/spAudio.h> long spReadAudio(spAudio audio, char *data, long length); long spReadAudioDouble(spAudio audio, double *ddata, long length); long spReadAudioDoubleWeighted(spAudio audio, double *ddata, long length, double weight);

引数

audio

spInitAudioのコールにより返された spAudioを指定します．

data

データを読み込むバッファーを指定します．メモリはあらかじめ確保しておいてください．

バッファーの型は，デバイスで使用するbits/sampleの値に応じて変えてください． 16bitまでの場合はshort型，32bitまではlong型のポインタ（メモリ確保したもの）もしくは配列を使用します．

ddata

データを読み込むdouble型のバッファーを指定します．メモリはあらかじめ確保しておいてください．

デバイスで使用するbits/sampleの値によらず，データの振幅の範囲は-1.0〜1.0の範囲となります． spReadAudioDoubleWeightedでは，それをさらにweight倍したデータが得られます．

length

バッファーの長さ（読み込むブロックの数）を指定します．バッファーのサイズではありません． 配列で考えると，要素の数に相当します．

weight

データの振幅値を何倍するかを指定します．

戻り値

エラーが起きた場合は，-1が返り，それ以外の場合は，読み込んだデータの長さが返ります．

説明

この関数は，spOpenAudioDevice を"r"モード（読み込み）でコールした場合のみに使用して下さい． それ以外の場合の動作は，保証されません．

通常は，読み込みが指定した長さに到達するまでこの関数は返りません．

spWriteAudio, spWriteAudioDouble, spWriteAudioDoubleWeighted

目的

オーディオデバイスに，データを書き込みます．

書式

#include <sp/spAudio.h> long spWriteAudio(spAudio audio, char *data, long length); long spWriteAudioDouble(spAudio audio, double *ddata, long length); long spWriteAudioDoubleWeighted(spAudio audio, double *ddata, long length, double weight);

引数

audio

spInitAudioのコールにより返された spAudioを指定します．

data

データの入ったバッファーを指定します．

バッファーの型は，デバイスで使用するbits/sampleの値に応じて変えてください． 16bitまでの場合はshort型，32bitまではlong型のポインタ（メモリ確保したもの）もしくは配列を使用します．

ddata

データの入ったdouble型のバッファーを指定します．

デバイスで使用するbits/sampleの値によらず，データの振幅の範囲は-1.0〜1.0の範囲が想定されています． spWriteAudioDoubleWeightedでは，そのデータをさらにweight倍した後にデバイスに渡します．

length

バッファーの長さ（読み込むブロックの数）を指定します．バッファーのサイズではありません． 配列で考えると，要素の数に相当します．

weight

データの振幅値を何倍してデバイスに渡すかを指定します．

戻り値

エラーが起きた場合は，-1が返り，それ以外の場合は，書き込んだデータの長さが返ります．

説明

この関数は，spOpenAudioDevice を"w"モード（書き込み）でコールした場合のみに使用して下さい． それ以外の場合の動作は，保証されません．

書き込みは非同期で行われるため，指定した長さまで到達する前に関数から返ってきます． どの程度の速さで関数から返ってくるかは，環境によって異なります．

lengthが小さいときにこの関数を繰り返し呼ぶと，環境によってはデッドロックに陥ります（応答しなくなります）． 繰り返し呼ぶ場合は，ある程度の長さになるようにプログラムを組む必要があります． 例えば，ループ再生を行う場合などは，ループ区間が短い場合には，lengthが極めて小さくなる場合があります． その場合には，ある程度の長さのバッファを用意しておき，バッファの中身が適当な長さに到達したらspWriteAudioを呼ぶ，といった実装にして下さい．

spStopAudio

目的

オーディオデバイスを停止します．

書式

#include <sp/spAudio.h> spBool spStopAudio(spAudio audio);

引数

audio

spInitAudioのコールにより返された spAudioを指定します．

戻り値

エラーが起きた場合は，SP_FALSEが返り，それ以外の場合は，SP_TRUEが返ります．

説明

この関数を呼び出すと，現在の処理を可能な限り即座に停止します． OSによって，若干動作が異なる可能性があります． 環境によっては，一度読み書きを開始すると，内部的に負荷のかかる処理をし続ける場合があります． その場合にも，この関数を呼び出すと負荷が減ります．

spSyncAudio

目的

オーディオデバイスをフラッシュします．

書式

#include <sp/spAudio.h> spBool spSyncAudio(spAudio audio);

引数

audio

spInitAudioのコールにより返された spAudioを指定します．

戻り値

エラーが起きた場合は，SP_FALSEが返り，それ以外の場合は，SP_TRUEが返ります．

説明

OSによって，若干動作が異なる可能性があります．

Last modified: "2024-06-20 14:53:42 hideki"