BSoundPlayer¶

Constructor and Destructor¶

BTimeSource()

BSoundPlayer::BTimeSource(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::BTimeSource(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::BTimeSource(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)

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

Pointer to the cookie.
Pointer to the buffer to play.
Size of the buffer.
Format of the audio data in the buffer.

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:

Constant	Description
`B_STARTED`and`B_STOPPED`	Indicate that the BSoundPlayer was started or stopped. These receive a pointer to the BSoundPlayer object as an argument.
`B_SOUND_DONE`	Indicates that a sound has finished playing. In this case, there are two arguments: the first is a play_id indicating which sound finished playing, and the other is a boolean which is true if the sound played at all, and false if the sound never played.

Note

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.

The second form of the constructor lets you specify in the format argument the format of the audio that the BSoundPlayer will perform. Since BSoundPlayer can only play raw sound formats, this is specified using the media_raw_audio_format structure.

The third form of the constructor lets you specify a node through which the sound should be played, and also uses a media_multi_audio_format to specify the sound’s format, instead of the older media_raw_audio_format.

You should call InitCheck() before using your BSoundPlayer object; this will let you determine whether or not the object was successfully constructed. One situation in which InitCheck() might indicate an error is if the user doesn’t have a sound card installed.

~BSoundPlayer()

BSoundPlayer::~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.

Member Functions¶

BufferPlayer(), SetBufferPlayer()

BufferPlayerFunc BSoundPlayer::BufferPlayer() const

void BSoundPlayer::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.

Cookie(), SetCookie()

void *BSoundPlayer::Cookie() const

void BSoundPlayer::SetCookie(void *cookie)

Cookie() returns the current cookie assigned to the BSoundPlayer.

SetCookie() lets you change the cookie assigned to the BSoundPlayer.

CurrentTime(), PerformanceTime()

bigtime_t BSoundPlayer::CurrentTime()

bigtime_t BSoundPlayer::PerformanceTime()

CurrentTime() returns the current media time, and PerformanceTime() returns the current performance time of the sound player node being used by the BSoundPlayer.

PerformanceTime() will return B_ERROR if the BSoundPlayer object hasn’t been properly initialized.

EventNotifier()

EventNotifierFunc BSoundPlayer::EventNotifier() const

void BSoundPlayer::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.

Format()

media_raw_audio_format BSoundPlayer::Format() const

Returns the BSoundPlayer’s format. Since the sound is always a raw sound format, the media_raw_audio_format structure is used.

EventNotifier()

EventNotifierFunc BSoundPlayer::EventNotifier(media_node *outNode, int32 *outParameter, float *outMinDB, float *outMaxDB) const

Returns information about the BSoundPlayer’s volume control. Pass pointers to variables to be filled (NULL is not permitted), and on return these values will be set to describe the player as follows:

Parameter	Description
outNode	Is the node to which the BSoundPlayer’s audio output will be directed.
outParameter	Is the parameter ID for the volume control.
outMinDB	Is the minimum volume in decibels.
outMaxDB	Is the maximum volume in decibels.

HasData(), SetHasData()

bool BSoundPlayer::HasData()

void BSoundPlayer::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);

InitCheck()

status_t BSoundPlayer::InitCheck()

Returns the status code resulting from constructing the BSoundPlayer object. You should call this after constructing the object; if the returned value is anything other than B_OK, you shouldn’t use the object.

Latency()

bigtime_t BSoundPlayer::Latency()

Returns the BSoundPlayer’s latency.

SetCallbacks()

void BSoundPlayer::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.

SetInitError()

void BSoundPlayer::SetInitError(status_t inError)

Sets the status code that will be returned by InitCheck().

SetSoundVolume()

status_t BSoundPlayer::SetSoundVolume(play_id sound, float volume)

Sets the volume (from 0.0 to 1.0) of the specified sound.

Start(), Stop()

status_t BSoundPlayer::Start()

void BSoundPlayer::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 Code	Description
`B_OK`	The sound playback was started.
Other errors.	As returned by the BMediaRoster’s `StartNode()` function.

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

play_id BSoundPlayer::StartPlaying(BSound *sound, bigtime_t atTime = 0)
play_id BSoundPlayer::StartPlaying(BSound *sound, bigtime_t atTime, float withVolume)

status_t BSoundPlayer::StopPlaying(play_id id)

status_t BSoundPlayer::WaitForSound(play_id id)

bool BSoundPlayer::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). The second form of StartPlaying() lets you specify a volume at which the sound should play.

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.

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

Volume(), SetVolume()

float BSoundPlayer::Volume()

void BSoundPlayer::SetVolume(float newVolume)

Volume() returns the current playback volume.

SetVolume() changes the playback volume.

This volume is the overall volume of all the sounds being played by the BSoundPlayer.To control the volumes of individual sounds, use the SetSoundVolume() function.

Note

The volume can range from 0.0 to 1.0, where 0.0 is silent and 1.0 is maximum loudness.

If you’d rather handle the volume using decibels instead of the percentage range, you can use the VolumeDB() and SetVolumeDB() functions.

VolumeDB(), SetVolumeDB()

float BSoundPlayer::VolumeDB()

void BSoundPlayer::SetVolumeDB(float newVolume)

VolumeDB() returns the current playback volume in decibels.

SetVolumeDB() sets the playback volume, in decibels.

This volume is the overall volume of all the sounds being played by the BSoundPlayer. To control the volumes of individual sounds, use the SetSoundVolume() function.

Note

The possible range of volumes can be obtained by calling GetVolumeInfo().

If you’d rather handle the volume using a percentage range instead of decibels, you can use the Volume() and SetVolume() functions.

Constants¶

sound_player_notification¶

Constant	Description
`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.

Defined Types¶

play_id¶

typedef int32 play_id;

Identifies a particular sound that’s being played by the BSoundPlayer; StartPlaying() returns values of this type.