|
現在のBeOSのリリースでは、単一のBSoundPlayerを通して再生される全てのBSoundは同じサンプリング周波数である必要があります。この制限は将来なくなるでしょう。差し当たっては、あなたがサポートしたいサンプリング周波数毎に一つのBSoundPlayerのインスタンスを作成して下さい。さらに、音声フォーマットはBSoundPlayer::B_AUDIO_FLOATのみサポートされています。
Playing SoundBSoundPlayerオブジェクトは音声を非同期的に演奏し、好きなだけ多くの音声を再生することができます。あなたは音声の再生を開始するために、BSoundのポインタをStartPlaying()に渡します :
play_id id = player->StartPlaying(sound); StartPlaying()は、音声が存在する間、それを参照するのに使用できるID番号を返します。他のBSoundPlayer関数はこのIDを引数として要求します。 あなたは、オプションとして再生を開始する時間を指定することができます :
play_id = player->StartPlaying(sound, 100000); これはperformance timeの100000マイクロ秒に再生を開始します。 IsPlaying()を呼び出すことで、あなたは音声がまだ再生中であるかどうかを確定することができます :
if (player->IsPlaying(id)) {
/* the sound is playing */
}
StopSound()を呼び出すことで、音声を停止させることができます :
player->StopSound(id); そして、WaitForSound()関数は、指定された音声が演奏を終了するまで待ちます :
play_id id = player->StartPlaying(sound); player->WaitForSound(id); 同様に、ボリュームを制御することができます。現在のボリュームを確定するためにVolume()関数を、ボリュームを変更するためにSetVolume()を使用します。ボリュームは浮動小数点数であり、0.0（無音）から1.0（最大ボリューム）の範囲です。現在のボリュームを半分にするコードの断片を示します :
SetVolume(Volume()/2.0);
Example: Let's Play AroundBSoundPlayerを使って音声ファイルを演奏することは非常に簡単です。ここに、指定された音声を再生し、その音声の再生が終了するまで返るのを待つ機構を示します :
void playsound(char *path) {
BSound *sound;
BSoundPlayer player;
entry_ref ref;
BEntry entry(path, true);
BSoundPlayer::play_id id;
if (entry.InitCheck()) == B_OK) {
if (entry.GetRef(&ref) == B_OK) {
sound = new BSound(&ref);
if (sound->InitCheck() == B_OK) {
player.Start();
player.SetVolume(1.0);
id = player.StartPlaying(sound);
sound->ReleaseRef();
player.WaitForSound(id);
}
}
}
}
entry_refは指定された音声ファイルから得られ、その後entry_refから得られたBSoundオブジェクトのインスタンスが作成される。BSoundPlayerオブジェクトは開始され、ボリュームは1.0（フルボリューム）にセットされ、そして音声の再生がStartPlaying()の呼び出しによって開始される。音声の参照カウントは減じられ、最後にBSoundPlayerのWaitForSound()呼び出しが再生の完了まで待機するために用いられます。
Advanced Playbackもしより進んだ再生を行う必要があるなら—例えばオンザフライで生成される音声を演奏する必要があるなら、または再生中の音声にフィルタをかける必要があるなら。 BSoundPlayerオブジェクトのインスタンスを生成する時、またはSetCallbacks()やSetBufferPlayer()を呼び出すことで演奏バッファハンドラ関数を指定するなら、その関数はBSoundPlayerの音声演奏nodeを通して渡すそれぞれのバッファに一度呼ばれます。あなたの演奏バッファハンドラはその後あなたが望む任意のデータでバッファを満たします。
下記のコードは、三角波を演奏するBSoundPlayerをセットアップします。
typedef struct cookie_record {
float value;
float direction;
} cookie_record;
...
cookie_record cookie;
cookie.value = 0.0;
cookie.direction = 1.0;
BSoundPlayer player("wave_player", BufferProc, NULL, &cookie);
player.Start();
player.SetHasData(true);
...
player.Stop();
このコードは、演奏バッファ関数がトラッキングするのに必要な情報を含み、音声を演奏するためにBufferProc()関数を使用する"wave_player"という名前のBSoundPlayerを生成し、我々の作りだしたcookieを使用するrecordとcookieを発行します。 その後、playerが開始されると、音声演奏nodeに演奏すべきデータがあるということを知らせるためにSetHasData()が呼ばれます。これは演奏バッファが呼び出しを開始される原因となります。 一旦再生が終了すると、Stop()関数が再生を停止させるために呼び出されます。 BufferProc()関数はこの様になります :
void BufferProc(void *theCookie, void *buffer, size_t size,
const media_raw_audio_format &format) {
size_t i, j;
float *buf = (float *) buffer;
size_t float_size = size/4;
uint32 channel_count = format.channel_count;
cookie_record *cookie = (cookie_record *) theCookie;
// We>re going to be cheap and only work for floating-point audio
if (format.format != media_raw_audio_format::B_AUDIO_FLOAT) {
return;
}
// Now fill the buffer with sound!
for (i=0; i<float_size; i+=channel_count) {
for (j=0; j<channel_count; j++) {
buf[i+j] = cookie->value;
}
if ((cookie->direction == 1.0) && (cookie->value >= 1.0)) {
cookie->direction = -1.0;
}
else if ((cookie->direction == -1.0) && (cookie->value <= -1.0)) {
cookie->direction = 1.0;
}
cookie->value += cookie->direction*(1.0/64.0);
}
}
この演奏バッファ関数の例では、一時に64分の1ずつ繰り返し、波を1.0から-1.0まで勾配を付けて三角波を生成しています。バッファに保存される次の値と値が変化する方向はcookieのフィールドに保持されます。
Hook Function
Constructor and Destructor
BSoundPlayer()
BSoundPlayerオブジェクトのインスタンスを生成します。引数name は音声演奏nodeに割り当てられる名前を指定します（NULLを指定した場合、一般的な名前が割り当てられます）。引数PlayBufferは再生のためにデータを処理しそれをバッファに挿入するメンバ関数のポインタを指定します。BSoundを演奏するためにBSoundPlayerを使用したい場合は、NULLを指定して下さい。PlayBuffer関数へのパラメータは（列挙すると）:
パラメータNotifierは、再生の開始や停止など興味あるイベントが生じた際に通知を受け取るメンバ関数へのポインタを指定します。デフォルトの通知ハンドラを使用するにはNULLを指定して下さい。通知には3つあります。
cookieパラメータはユーザ自身の目的のために使用できるポインタです。それはもしカスタムのPlayBufferまたはNotifierを使用する際には最も使いやすいものです。 コンストラクタの2番目の形式では、format引数でBSoundPlayerが演奏するオーディオのフォーマットを指定できます。BSoundPlayerが生の（raw）音声ファイル以外演奏できないため、これはmedia_raw_audio_format構造体を用いて指定されます。 コンストラクタの3番目の形式では、音声が演奏されるnodeを指定でき、また音声のフォーマットを指定するのに、古いmedia_raw_audio_formatの代りにmedia_multi_audio_formatを使用できます。 BSoundPlayerオブジェクトを使用する前にInitCheck()を呼び出して下さい。これによって、オブジェクトがうまく生成されたかどうかを知ることができます。InitCheck()がエラーを示すのは、ユーザがサウンドカードをインストールしていない時です。
~BSoundPlayer()
再生を停止するときは、もし音声が演奏されていれば、BSoundPlayerに使用されている全てのBSoundオブジェクトへの参照を開放し、BSoundPlayerによって使用されている全てのメモリを開放して下さい。
Member Functions
BufferPlayer() , SetBufferPlayer()
BufferPlayer()は、デフォルトのplayerが使用されていれば、現在の演奏バッファ関数へのポインタを返します。 SetBufferPlayer()は、演奏バッファ関数を変更します。
Cookie() , SetCookie()
Cookie()は、BSoundPlayerに割り当てられた現在のcookieを返します。 SetCookie()は、BSoundPlayerに割り当てられたcookieを変更します。
CurrentTime() , PerformanceTime()
CurrentTime()は、BSoundPlayerに使用されている音声演奏playerの現在のmedia timeを、PerformanceTime()は現在のperformance timeを返します。 PerformanceTime()は、BSoundPlayerオブジェクトが正しく初期化されていなければB_ERRORを返します。
EventNotifier() , SetEventNotifier()
EventNotifier()は、現在のイベント通知ハンドラ関数へのポインタを返すか、もしデフォルトのplayerが使用されていればNULLを返します。 SetNotifier()はイベント通知ハンドラ関数を変更します。
Format()
BSoundPlayerのフォーマットを返します。音声は常に生の（raw）音声フォーマットであるため、media_raw_audio_format構造体が使用されます。
GetVolumeInfo()
BSoundPlayerのボリューム制御に関する情報を返します。満たされる変数のポインタを渡して下さい（NULLは許可されません）。そしてこれらの値は下記のplayerを記述するために設定されます。
HasData() , SetHasData()
HasData()は、再生のためのサウンドキューがあればtrueを返し、そうでなければfalseを返します。 SetHasData()は、音声再生のスケジュールがあるか否かを指定します。 これらの関数の目的は、BSoundPlayerを最適化することです。もし再生するべきデータキューがなければ、そのパフォーマンスを最適化すると音声演奏nodeは言われます。もしバッファ演奏関数を使用していれば、演奏すべきデータがあることを示すためにSetHasData()を使用しなければなりません。
SetHasData(true);
InitCheck()
BSoundPlayerオブジェクトをコンストラクトした結果の状態（status）コードが返されます。そのオブジェクトをコンストラクトしたときには、この関数を呼びます。もし返された値がB_OK以外であれば、そのオブジェクトを使用すべきではありません。
Latency()
BSoundPlayerのlatencyを返します。
SetCookie() see Cookie()
SetBufferPlayer() see BufferPlayer()
SetCallbacks()
演奏バッファハンドラ関数、イベント通知ハンドラ関数とcookieを全て同時に設定する、ごく小さな操作です。
SetHasData() see HasData()
SetInitError()protected:
InitCheck()によって返される状態（status）コードを設定します。
SetSoundVolume()
指定されたsoundのvolumeを（0.0から1.0の範囲で）設定します。
SetVolumeDB() see VolumeDB()
Start() , Stop()
Start()は、time sourceとsound playerのnodeを開始することでBSoundPlayerをアクティブにします。 Stop()は、player nodeを停止することでBSoundPlayerを非アクティブにします（もしblockがtrueなら、Stop()関数はnodeが停止するまでブロックします）。もしflushがtrueなら、キューの音声は全てメモリから削除されます。 BSoundPlayerが動作している間、演奏バッファ関数は、（もし一つを指定していたなら）BSoundPlayerの再生nodeを通して渡されたそれぞれのバッファから呼び出されます。このフック関数は、オンザフライで音声を生成したり、再生される前にフィルタを通すなど、より高度な音声再生を実装するために使用できます。 RETURN CODES B_OK. 音声の再生が開始された。
StartPlaying() , StopPlaying() , WaitForSound() , IsPlaying()
StartPlaying()は、atTimeによって指定されたperformance timeに指定されたBSoundを再生開始するよう予定を入れます。atTimeが0の場合、音声はただちに（または、もしBSoundPlayerがまだ開始されていなければStart()が呼ばれた後すぐに）再生を開始します。この関数によって返されたplay_idは、後に音声を識別するために使用されます。もしこれが負の値であれば、エラーが生じたということになります（正の値の場合は、下記のリストをご覧下さい）。StartPlaying()の2つ目の形式では、音声が再生される際のボリュームを指定できます。 StopPlaying()は、与えられたidによって指定された音声の演奏を停止します。 WaitForSound()は、指定された音声が演奏を停止するまで待ちます。 IsPlaying()は、指定された音声が演奏中であればtrueを、そうでなければfalseを返します。 RETURN CODES B_OK. エラーなし。
StopPlaying() see StartPlaying()
Volume() , SetVolume()
Volume()は、現在の再生音量を返します。 SetVolume()は、再生音量を変更します。 このボリュームは、BSoundPlayerによって演奏されている全ての音声のボリュームを総合したものです。個々の音声のボリュームを制御する場合は、SetSoundVolume()関数を使用して下さい。
もしボリュームをパーセントによる範囲の代りにデシベルを使って扱いたいなら、VolumeDB()及びSetVolumeDB()を使用することが出来ます。 See also: VolumeDB() and SetVolumeDB()
VolumeDB() , SetVolumeDB()
VolumeDB()は、現在の再生音量をデシベルで返します。 SetVolumeDB()は、デジベルで再生音量を設定します。 このボリュームは、BSoundPlayerによって演奏されている全ての音声のボリュームを総合したものです。個々の音声のボリュームを制御する場合は、SetSoundVolume()関数を使用して下さい。
もしボリュームをデシベルによる範囲の代りにパーセントを使って扱いたいなら、Volume()及びSetVolume()を使用することが出来ます。 Volume()及びSetVolume()もご覧下さい。
Constants
sound_player_notificationDeclared in: <be/media/SoundPlayer.h>
これらの定数は、どんな種類の興味深いイベントが発生したか示すために、イベント通知ハンドラ関数に渡されます。
Defined Types
play_idDeclared in: <be/media/SoundPlayer.h> typedef int32 play_id; BSoundPlayerによって演奏されている特定の音声を識別します。StartPlaying()は、この形式の値を返します。
|
| The Media Kit Table of Contents | The Media Kit Index |
...in lovely HTML...
for BeOS Release 5.
Copyright © 2000 Be, Inc. All rights reserved..