Derived from: (none)
Declared in: be/media/SoundPlayer.h
Library: libmedia.so
Allocation: Constructor only
The BSoundPlayer class plays sound, either from BSound objects or by directly filling audio buffers with data provided by a hook function you specify. A single BSoundPlayer can play multiple sounds at a time.
BSoundPlayer takes care of all the nitty-gritty details of instantiating the necessary sound player node and managing the time source. All you have to do is start up a BSoundPlayer and feed it sounds to play.
For simple audio playback, the sounds are specified using the BSound class. However, if you need to perform on-the-fly generation or alteration of sounds, you can implement a hook function that will be called for each audio buffer passed through the BSoundPlayer's playback node.
Once you've instantiated a BSoundPlayer object, you need to start it up before you can actually play sounds with it. This instantiates the sound player node, attaches it to an appropriate time source, and makes sure the time source is running. This is done by calling the Start() function.
When you're done using the BSoundPlayer, you can delete it if you don't plan to use it again, or, if you want to keep it around for reuse, you can just Stop() it. This deletes the sound node and cleans up the sounds.
In general, the process of using BSoundPlayer looks like this:
BSoundPlayer player; player.Start(); /* use the BSoundPlayer here */ player.Stop();
You can find out the current time of the time source to which sounds are being synchronized by calling the CurrentTime() function.
By default, the audio format used by a BSoundPlayer is BSoundPlayer::B_AUDIO_FLOAT, which is to say that the audio is in floating-point format, where each sample ranges from -1.0 to 1.0. The Media Kit uses floating-point audio internally, so using floating-point audio whenever you can will improve your application's performance by cutting down on format conversions. However, if you want to use another format, you may do so by specifying a media_raw_audio_format when you instantiate the BSoundPlayer object.
|
In BeOS Release 4, all BSounds playing through a single BSoundPlayer must have the same sampling rate. This restriction may be lifted in the future. For the time being, just instantiate one BSoundPlayer for each sampling rate you need to support. |
A BSoundPlayer object plays sounds asynchronously, and can play as many sounds as you like. You start playback of a sound by passing a BSound pointer to StartPlaying():
play_id id = player->StartPlaying(sound);
StartPlaying() returns an ID number you can use to refer to the sound throughout its existence; other BSoundPlayer functions require this ID as an argument.
You can, optionally, specify a time at which to begin playback:
play_id = player->StartPlaying(sound, 100000);
This starts playback at the performance time 100000 microseconds.
You can determine whether or not a sound is still playing by calling IsPlaying():
if (player->IsPlaying(id)) {
/* the sound is playing */
}
You can stop the sound by calling StopSound():
player->StopSound(id);
And the WaitForSound() function waits until the specified sound is finished playing:
play_id id = player->StartPlaying(sound); player->WaitForSound(id);
And you can control the volume as well. Use the Volume() function to determine the current volume, and SetVolume() to change the volume. The volume is a floating-point number, and ranges from 0.0 (silence) to 1.0 (full volume). Here's a code snippet that halves the current volume:
SetVolume(Volume()/2.0);
Playing sound files using BSoundPlayer is very easy. Here's a function that will play a specified sound, waiting until the sound is finished playing before it returns:
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);
}
}
}
}
An entry_ref is obtained for the specified sound file, then a BSound object is instantiated given that entry_ref. A BSoundPlayer object is started, the volume is set to 1.0 (full volume), and then the sound playback is started by calling StartPlaying(). The sound's reference count is decremented, and finally BSoundPlayer's WaitForSound() call is used to wait until playback is complete.
If you have more advanced playback needs--for example, you need to play sounds that are being generated on-the-fly, or if you need to filter the sound you're playing.
If you specify a play buffer handler function, either when instantiating the BSoundPlayer object or by calling SetCallbacks() or SetBufferPlayer(), that function will be called once for each buffer that passes through the BSoundPlayer's sound playing node. Your play buffer handler can then fill the buffer with whatever data you wish.
|
If you specify a play buffer function, BSound playback won't work. If you need to do both, you must use multiple BSoundPlayer objects. |
The following code sets up a BSoundPlayer that will play a triangle wave.
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();
This code establishes a record, cookie, that contains information the play buffer function will need to track, and creates a BSoundPlayer named "wave_player" that will use a function called BufferProc() to play sound, and uses the cookie we've created.
Then the player is started, and SetHasData() is called to let the sound player node know that there's data to be played. This will cause the play buffer function to start being called.
Once playback is over, the Stop() function is called to stop playback.
The BufferProc() function looks like this:
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);
}
}
This example play buffer function generates a triangle wave, ramping the wave up and down from 1.0 to -1.0 and back, over and over again, 1/64th at a time. The next value to store in the buffer and the direction in which the value is changing are kept in the cookie's fields.
|
The buffers your play buffer function receives are empty. Do with them as you please (or do nothing at all). |
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)
Initializes the BSoundPlayer object. The name argument specifies the name to be assigned to the sound player node (if you specify NULL, a generic name will be assigned).
The PlayBuffer argument specifies a pointer to a member function that processes data and inserts it into buffers for playback; specify NULL if you want to use the BSoundPlayer for playing BSounds. The parameters to the PlayBuffer function are (in order):
The Notifier parameter specifies a pointer to a member function that receives notifications when events of interest occur, such as playback starting or stopping. Specify NULL to use the default notification handler. There are three possible notifications:
|
If the callback handlers are members of a class, they must be static members. |
The cookie parameter is a pointer that you can use for your own purposes; it's most useful if you're using a custom PlayBuffer or Notifier.
~BSoundPlayer()
Stops playback, if sound is playing, releases references to any BSound objects that are in use by the BSoundPlayer, and frees all memory used by the BSoundPlayer.
BufferPlayerFunc BufferPlayer(void) const
void SetBufferPlayer(void (*PlayBuffer)(void *, void *buffer, size_t size, const media_raw_audio_format &format))
BufferPlayer() returns a pointer to the current play buffer function, or NULL if the default player is in use.
SetBufferPlayer() lets you change the play buffer function.
void *Cookie(void) const
void SetCookie(void *cookie)
Cookie() returns the current cookie assigned to the BSoundPlayer.
SetCookie() lets you change the cookie assigned to the BSoundPlayer.
bigtime_t CurrentTime(void)
Returns the current performance time of the sound player node being used by the BSoundPlayer.
EventNotifierFunc EventNotifier(void) const
void SetNotifier(void (*Notifier)(void *, sound_player_notification what, ...))
EventNotifier() returns a pointer to the current event notification handler function, or NULL if the default player is in use.
SetNotifier() lets you change the event notification handler function.
bool HasData(void)
void SetHasData(bool hasData)
HasData() returns true if there's sound queued for playback, or false otherwise.
SetHasData() specifies whether or not there's sound scheduled for playback.
The purpose of these functions is to optimize the BSoundPlayer; if there's no data queued for playback, the sound player node is told this, which lets it optimize its performance. If you're using a buffer player function, you must use SetHasData() to indicate that there's data to play:
SetHasData(true);
IsPlaying() see StartPlaying()
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)
Sets the play buffer handler function, the event notification handler function, and the cookie all in one atomic operation.
status_t Start(void)
void Stop(bool block = true,
bool flush = true)
Start() activates the BSoundPlayer by starting the time source and the sound player node. The B_STARTED notification is sent to the BSoundPlayer's notification handler.
Stop() deactivates the BSoundPlayer by stopping the player node (if block is true, the Stop() function blocks until the node is stopped). If flush is true, the queued sounds are all deleted from memory.
While the BSoundPlayer is running, the play buffer function (if you've specified one) will be called for each buffer that passes through the BSoundPlayer's playback node. This hook function can be used to implement code that performs more advanced playback of sound, such as sound that's generated on-the-fly, or is filtered before playback.
RETURN CODES
B_OK. The sound playback was started.
Other errors. As returned by the sound player's StartNode() function.
play_id StartPlaying(BSound *sound, bigtime_t atTime = 0)
status_t StopPlaying(play_id id)
status_t WaitForSound(play_id id)
bool IsPlaying(play_id id)
StartPlaying() schedules the specified BSound to begin playback at the performance time specified by atTime; if atTime is 0, the sound begins playing immediately (or as soon as Start() is called, if the BSoundPlayer hasn't been started yet). The play_id returned by this function is used to identify the sound later. If it's negative, an error occurred (see the list below for possible values).
StopPlaying() stops playing the sound specified by the given id.
WaitForSound() waits until the specified sound stops playing.
IsPlaying() returns true if the specified sound is playing; otherwise, it returns false.
RETURN CODES
B_OK. No error.
B_MEDIA_BAD_FORMAT. The audio isn't in a supported format (StartPlaying()).
B_BAD_VALUE. The specified id doesn't exist (WaitForSound() and IsPlaying()).
float Volume(void)
void SetVolume(float newVolume)
Volume() returns the current playback volume.
SetVolume() changes the playback volume.
|
The volume can range from 0.0 to 1.0, where 0.0 is silent and 1.0 is maximum loudness. |
Declared in: <be/media/SoundPlayer.h>
| Constant | Meaning |
|---|---|
| B_STARTED | The BSoundPlayer has been started via the Start() function. |
| B_STOPPED | The BSoundPlayer's Stop() function has been called. |
| B_SOUND_DONE | A sound has finished playing. |
These constants are passed to event notification handler functions to indicate what sort of interesting event has occurred.
Declared in: <be/media/SoundPlayer.h>
typedef int32 play_id;
Identifies a particular sound that's being played by the BSoundPlayer; StartPlaying() returns values of this type.
The Be Book, in lovely HTML, for BeOS Release 4.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified November 9, 1998.