The Media Kit: Global Functions, Constants, and Defined Types


The Media Kit: Global Functions, Constants, and Defined Types

This section lists parts of the Media Kit that aren't contained in classes.


Functions


play_sound()


      sound_handle play_sound(const entry_ref *soundRef,
         bool willMix,
         bool willWait,
         bool background);

play_sound plays the sound file identified by the entry_ref pointed to by the soundRef parameter. The willMix and willWait arguments are used to determine how the function behaves with regard to other sounds.

Note that setting willMix to TRUE doesn't guarantee that your sound will play immediately. If the sound playback resources are claimed for exclusive access by some other process, you'll be blocked, even if you're willing to mix.

The background argument, if TRUE, tells the function to spawn a thread in which to play the sound. In this case, the function returns immediately. If background is FALSE, the sound is played synchronously and play_sound() won't return until the sound has finished.

The sound_handle value that's returned is a token that represents the sound that's being played back, and is only valid if you're playing in the background. You would use this token in a subsequent call to stop_sound() or wait_for_sound(). If the entry_ref doesn't represent a file, or if the sound couldn't be played, for whatever reason, play_sound() returns a negative integer.


stop_sound()


      status_t stop_sound(sound_handle handle);

stop_sound() stops the playback of a sound identified by handle, a value that was returned by a previous call to play_sound(). The return value can be ignored.


wait_for_sound()


      status_t wait_for_sound(sound_handle handle);

Causes the calling thread to block until the sound specified by handle has finished playing. The handle value should be a value returned by a previous call to play_sound(). wait_for_sound() currently always returns B_OK.


Constants


ADC Input Codes

Constant Meaning
B_CD_IN CD player input.
B_LINE_IN Line input.
B_MIC_IN Microphone input.

These constants define the three audio input devices available to BADCStream objects.


Byte Orderings

Constant Meaning
B_BIG_ENDIAN Data is in big-endian format.
B_LITTLE_ENDIAN Data is in little-endian format.

These constants define the two possible byte orderings.


Control Points

Constant Meaning
B_CD_THROUGH CD throughput.
B_LINE_IN_THROUGH Line in throughput.
B_ADC_IN ADC input.
B_LOOPBACK Audio loopback
B_DAC_OUT DAC output
B_MASTER_OUT Master output.
B_SPEAKER_OUT Speaker output.

These constants define the control points in the audio hardware that can be volume-controlled, enabled and disabled.


Sound File Formats

Constant Meaning
B_UNKNOWN_FILE The sound file's format is not known.
B_AIFF_FILE AIFF sound file.
B_WAVE_FILE WAVE sound file.
B_UNIX_FILE UNIX sound file.

These constants define the types of sound files supported by the BSoundFile class.


Sound Sample Formats

Constant Meaning
B_UNDEFINED_SAMPLES Unknown sample format.
B_LINEAR_SAMPLES Samples are linear integers.
B_FLOAT_SAMPLES Samples are floating-point values.
B_MULAW_SAMPLES Samples are in \xb5 Law format.

These constants define the sound sample formats supported by the Media Kit.


Defined Types


sound_handle


      typedef sem_id sound_handle;

A sound_handle is returned by play_sound(), and represents a sound that's playing in the background.






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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.