# 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.

- If you want the sound to play all by itself, set willMix to `FALSE`. If you don't care if it gets mixed with other sounds, set it to `TRUE`.

- If you want your sound to play immediately (whether or not you're willing to mix), set willWait to `FALSE`. If you're willing to wait for the sound playback resources to become available, set willWait to `TRUE`.

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.