The Media Kit Table of Contents     The Media Kit Index

BSoundPlayer

Derived from: (none)

Declared in: be/media/SoundPlayer.h

Library: libmedia.so

Allocation: Constructor only

Summary

 BSoundPlayerクラスは、BSoundオブジェクトまたは指定されたフック関数によって供給されるデータでオーディオバッファを満たすことにより、音声を演奏します。一つのBSoundPlayerは同時に複数の音声を演奏することが出来ます。

 BSoundPlayerは必要なsound player nodeのインスタンスを作成と、time sourceの管理の肝心な部分を処理します。あなたがしなければならないことは、BSoundPlayerを開始し、それに再生する音声を供給するだけです。

 単純な音声再生のために、音声はBSoundクラスを用いて指定されます。しかしながら、もしオンザフライ演奏や音声の変更が必要であれば、あなたはBSoundPlayerの再生用nodeを通過する各々のオーディオバッファを呼び出すフック関数を実装することができます。


Using BSoundPlayer

 一旦、BSoundPlayerオブジェクトのインスタンスを作成すると、あなたは実際に音声を再生する前にそれを始動する必要があります。これはsound player nodeのインスタンスを作成し、それに適切なtime sourceを添付し、time sourceが動作していることを確認します。これはStart()関数を呼び出すことで行われます。

 BSoundPlayerを使い終わり、もし二度とそれを使う予定がないなら、あなたはそれを削除(delete)することができます。また、もしそれを再使用のために置いておきたいなら、あなたはそれをStop()できます。これはsound nodeを削除(delete)し、音声をきれいに片づけます。

 おおよそ、BSoundPlayerを使用するプロセスは、以下のようになります :

   BSoundPlayer player;
   player.Start();
   
   /* use the BSoundPlayer here */
   
   player.Stop();

 あなたは音声が同期しているtime sourceの現在の時刻を、CurrentTime()関数を呼び出すことで見つけだすことができます。

 デフォルトでは、BSoundPlayerで使用される音声フォーマットはBSoundPlayer::B_AUDIO_FLOATで、これは、言うなれば音声が浮動小数点のフォーマット、つまりそれぞれのサンプルが-1.0から1.0の範囲にあるということです。Media Kitは浮動小数点の音声を内部的に使用するため、できる限り浮動小数点の音声を使用することで、フォーマット変換の労力を削減し、アプリケーションの動作を改善させることができるでしょう。しかしながら、もし他のフォーマットを使用したいなら、BSoundPlayerオブジェクトのインスタンスを作成する際に、media_raw_audio_formatによってそれを行います。

 
現在のBeOSのリリースでは、単一のBSoundPlayerを通して再生される全てのBSoundは同じサンプリング周波数である必要があります。この制限は将来なくなるでしょう。差し当たっては、あなたがサポートしたいサンプリング周波数毎に一つのBSoundPlayerのインスタンスを作成して下さい。さらに、音声フォーマットはBSoundPlayer::B_AUDIO_FLOATのみサポートされています。


Playing Sound

 BSoundPlayerオブジェクトは音声を非同期的に演奏し、好きなだけ多くの音声を再生することができます。あなたは音声の再生を開始するために、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 Around

BSoundPlayerを使って音声ファイルを演奏することは非常に簡単です。ここに、指定された音声を再生し、その音声の再生が終了するまで返るのを待つ機構を示します :

   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を通して渡すそれぞれのバッファに一度呼ばれます。あなたの演奏バッファハンドラはその後あなたが望む任意のデータでバッファを満たします。

 
もし演奏バッファ関数を特定するなら、BSoundの再生は動作しません。もし両方が必要なら、複数のBSoundPlayerオブジェクトを使用しなければなりません。


 下記のコードは、三角波を演奏する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(const char *name = NULL,
      void (*PlayBuffer)(void *, void *buffer, size_t size, const media_raw_audio_format &format) = NULL,
      void (*Notifier)(void *, sound_player_notification what, ...) = NULL,
      void *cookie = NULL)

BSoundPlayer(const media_raw_audio_format * format,
      const char *name = NULL,
      void (*PlayBuffer)(void *, void * buffer, size_t size, const media_raw_audio_format & format) = NULL,
      void (*Notifier)(void *, sound_player_notification what, ...) = NULL,
      void *cookie = NULL)

BSoundPlayer(const media_node & toNode,
      const media_multi_audio_format *format = NULL,
      const char *name = NULL,
      const media_input *input = NULL,
      void (*PlayBuffer)(void *, void * buffer, size_t size, const media_raw_audio_format & format) = NULL,
      void (*Notifier)(void *, sound_player_notification what, ...) = NULL,
      void *cookie = NULL)

 BSoundPlayerオブジェクトのインスタンスを生成します。引数nameは音声演奏nodeに割り当てられる名前を指定します(NULLを指定した場合、一般的な名前が割り当てられます)。

 引数PlayBufferは再生のためにデータを処理しそれをバッファに挿入するメンバ関数のポインタを指定します。BSoundを演奏するためにBSoundPlayerを使用したい場合は、NULLを指定して下さい。PlayBuffer関数へのパラメータは(列挙すると):

  • cookieへのポインタ。

  • 演奏するバッファへのポインタ。

  • バッファのサイズ。

  • バッファのオーディオデータのフォーマット。

 パラメータNotifierは、再生の開始や停止など興味あるイベントが生じた際に通知を受け取るメンバ関数へのポインタを指定します。デフォルトの通知ハンドラを使用するにはNULLを指定して下さい。通知には3つあります。

  • B_STARTED及びB_STOPPEDは、BSoundPlayerが開始または停止させられたことを示します。これらは引数としてBSoundPlayerオブジェクトへのポインタを受け取ります。

  • B_SOUND_DONEは、音声の演奏終了を示します。この場合は、二つの引数を取ります。最初のものは音声の演奏が終了したことを示すplay_idであり、もう一つは音声が全て演奏された場合にtrueを、演奏されなければfalseとなる真偽値を示します。

 
コールバック(callback)ハンドラがクラスのメンバであれば、それらは静的メンバでなければなりません。


 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()

 再生を停止するときは、もし音声が演奏されていれば、BSoundPlayerに使用されている全てのBSoundオブジェクトへの参照を開放し、BSoundPlayerによって使用されている全てのメモリを開放して下さい。


Member Functions


BufferPlayer() , SetBufferPlayer()

                                                         
  

BufferPlayerFunc BufferPlayer(void) const

void SetBufferPlayer(void (*PlayBuffer)(void *, void *buffer, size_t size, const media_raw_audio_format &format))

 BufferPlayer()は、デフォルトのplayerが使用されていれば、現在の演奏バッファ関数へのポインタを返します。

 SetBufferPlayer()は、演奏バッファ関数を変更します。


Cookie() , SetCookie()

                                                         
  

void *Cookie(void) const

void SetCookie(void *cookie)

 Cookie()は、BSoundPlayerに割り当てられた現在のcookieを返します。

 SetCookie()は、BSoundPlayerに割り当てられたcookieを変更します。 


CurrentTime() , PerformanceTime()

                                                         
  

bigtime_t CurrentTime(void)

bigtime_t PerformanceTime(void)

 CurrentTime()は、BSoundPlayerに使用されている音声演奏playerの現在のmedia timeを、PerformanceTime()は現在のperformance timeを返します。

 PerformanceTime()は、BSoundPlayerオブジェクトが正しく初期化されていなければB_ERRORを返します。


EventNotifier() , SetEventNotifier()

                                                         
  

EventNotifierFunc EventNotifier(void) const

void SetNotifier(void (*Notifier)(void *, sound_player_notification what, ...))

 EventNotifier()は、現在のイベント通知ハンドラ関数へのポインタを返すか、もしデフォルトのplayerが使用されていればNULLを返します。

 SetNotifier()はイベント通知ハンドラ関数を変更します。


Format()

                                                         
  

media_raw_audio_format Format(void) const

 BSoundPlayerのフォーマットを返します。音声は常に生の(raw)音声フォーマットであるため、media_raw_audio_format構造体が使用されます。


GetVolumeInfo()

                                                         
  

status_t GetVolumeInfo(media_node *outNode,
      int32 *outParameter,
      float *outMinDB, float *outMaxDB) const

 BSoundPlayerのボリューム制御に関する情報を返します。満たされる変数のポインタを渡して下さい(NULLは許可されません)。そしてこれらの値は下記のplayerを記述するために設定されます。

  • outNodeは、BSoundPlayerのオーディオ出力が管理されるnodeです。

  • outParameterは、ボリューム制御のためのパラメータIDです。

  • outMinDBは、デシベル単位での最小ボリュームです。

  • outMaxDBは、デシベル単位での最大ボリュームです。


HasData() , SetHasData()

                                                         
  

bool HasData(void)

void SetHasData(bool hasData)

 HasData()は、再生のためのサウンドキューがあればtrueを返し、そうでなければfalseを返します。

 SetHasData()は、音声再生のスケジュールがあるか否かを指定します。

 これらの関数の目的は、BSoundPlayerを最適化することです。もし再生するべきデータキューがなければ、そのパフォーマンスを最適化すると音声演奏nodeは言われます。もしバッファ演奏関数を使用していれば、演奏すべきデータがあることを示すためにSetHasData()を使用しなければなりません。

   SetHasData(true);


InitCheck()

                                                         
  

status_t InitCheck(void)

 BSoundPlayerオブジェクトをコンストラクトした結果の状態(status)コードが返されます。そのオブジェクトをコンストラクトしたときには、この関数を呼びます。もし返された値がB_OK以外であれば、そのオブジェクトを使用すべきではありません。


IsPlaying() see StartPlaying()


Latency()

                                                         
  

bigtime_t Latency(void)

BSoundPlayerのlatencyを返します。


PerformanceTime() see CurrentTime()


SetCookie() see Cookie()


SetBufferPlayer() see BufferPlayer()


SetCallbacks()

                                                         
  

void SetCallbacks(void (*PlayBuffer)(void *, void *buffer, size_t size, const media_raw_audio_format &format) = NULL,
      void (*Notifier)(void *, sound_player_notification what, ...) = NULL,
      void *cookie = NULL)

 演奏バッファハンドラ関数、イベント通知ハンドラ関数とcookieを全て同時に設定する、ごく小さな操作です。


SetCookie() see Cookie()


SetHasData() see HasData()


SetInitError()

protected:

                                                         
  

void SetInitError(status_t inError)

 InitCheck()によって返される状態(status)コードを設定します。


SetNotifier() see EventNotifier()


SetSoundVolume()

                                                         
  

status_t SetSoundVolume(play_id sound, float volume)

 指定されたsoundvolumeを(0.0から1.0の範囲で)設定します。


SetVolume() see Volume()


SetVolumeDB() see VolumeDB()


Start() , Stop()

                                                         
  

status_t Start(void)

void Stop(bool block = true,
      bool flush = true)

 Start()は、time sourceとsound playerのnodeを開始することでBSoundPlayerをアクティブにします。

 Stop()は、player nodeを停止することでBSoundPlayerを非アクティブにします(もしblocktrueなら、Stop()関数はnodeが停止するまでブロックします)。もしflushtrueなら、キューの音声は全てメモリから削除されます。

 BSoundPlayerが動作している間、演奏バッファ関数は、(もし一つを指定していたなら)BSoundPlayerの再生nodeを通して渡されたそれぞれのバッファから呼び出されます。このフック関数は、オンザフライで音声を生成したり、再生される前にフィルタを通すなど、より高度な音声再生を実装するために使用できます。

RETURN CODES

B_OK. 音声の再生が開始された。

  • 他のエラー。sound playerのStartNode()関数から返されるものと同様。


StartPlaying() , StopPlaying() , WaitForSound() , IsPlaying()

                                                         
  

play_id StartPlaying(BSound *sound, bigtime_t atTime = 0)

play_id StartPlaying(BSound *sound, bigtime_t atTime, float withVolume)

status_t StopPlaying(play_id id)

status_t WaitForSound(play_id id)

bool IsPlaying(play_id id)

 StartPlaying()は、atTimeによって指定されたperformance timeに指定されたBSoundを再生開始するよう予定を入れます。atTimeが0の場合、音声はただちに(または、もしBSoundPlayerがまだ開始されていなければStart()が呼ばれた後すぐに)再生を開始します。この関数によって返されたplay_idは、後に音声を識別するために使用されます。もしこれが負の値であれば、エラーが生じたということになります(正の値の場合は、下記のリストをご覧下さい)。StartPlaying()の2つ目の形式では、音声が再生される際のボリュームを指定できます。

 StopPlaying()は、与えられたidによって指定された音声の演奏を停止します。

 WaitForSound()は、指定された音声が演奏を停止するまで待ちます。

 IsPlaying()は、指定された音声が演奏中であればtrueを、そうでなければfalseを返します。

RETURN CODES

B_OK. エラーなし。

  • B_MEDIA_BAD_FORMAT. オーディオがサポートされたフォーマットではない(StartPlaying())。

  • B_BAD_VALUE. 指定されたidが存在していない(WaitForSound()及びIsPlaying())。


StopPlaying() see StartPlaying()


Volume() , SetVolume()

                                                         
  

float Volume(void)

void SetVolume(float newVolume)

Volume()は、現在の再生音量を返します。

SetVolume()は、再生音量を変更します。

 このボリュームは、BSoundPlayerによって演奏されている全ての音声のボリュームを総合したものです。個々の音声のボリュームを制御する場合は、SetSoundVolume()関数を使用して下さい。

 
ボリュームは0.0から1.0までの範囲を取ります。0.0は無音であり、1.0は最も大きな音です。


 もしボリュームをパーセントによる範囲の代りにデシベルを使って扱いたいなら、VolumeDB()及びSetVolumeDB()を使用することが出来ます。

See also: VolumeDB() and SetVolumeDB()


VolumeDB() , SetVolumeDB()

                                                         
  

float VolumeDB(void)

void SetVolumeDV(float newVolumeDB)

 VolumeDB()は、現在の再生音量をデシベルで返します。

 SetVolumeDB()は、デジベルで再生音量を設定します。

 このボリュームは、BSoundPlayerによって演奏されている全ての音声のボリュームを総合したものです。個々の音声のボリュームを制御する場合は、SetSoundVolume()関数を使用して下さい。

 
ボリュームの取りうる範囲は、GetVolumeInfo()を呼び出すことで得られます。


 もしボリュームをデシベルによる範囲の代りにパーセントを使って扱いたいなら、Volume()及びSetVolume()を使用することが出来ます。

Volume()及びSetVolume()もご覧下さい。


WaitForSound() see StartPlaying()


Constants


sound_player_notification

Declared in: <be/media/SoundPlayer.h>

定数 意味
B_STARTED BSoundPlayer は、 Start() 関数経由で開始された。
B_STOPPED BSoundPlayerの Stop() 関数が呼ばれた。
B_SOUND_DONE 音声の演奏が終了した。

 これらの定数は、どんな種類の興味深いイベントが発生したか示すために、イベント通知ハンドラ関数に渡されます。


Defined Types


play_id

Declared in: <be/media/SoundPlayer.h>

   
   
typedef int32 play_id;

 BSoundPlayerによって演奏されている特定の音声を識別します。StartPlaying()は、この形式の値を返します。


The Media Kit Table of Contents     The Media Kit Index


The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..