# The Media Kit

|  | The Media Kit is undergoing massive surgery. The current Kit (the one documented here) will be supported in future releases, but work on this Kit has stopped. Look for a new Media Kit in BeOS Release 4.

The Media Kit gives you tools that let you generate, examine, manipulate, and realize (or render) sound data in real-time. It's based on the notion of subscribers that talk to the system wide audio server:

- At the subscriber layer are classes that let you talk directly to the audio server that are provided by the Kit. For each distinct medium there's a distinct server--but there's only one server per medium per computer. Corresponding to each server is a BSubscriber-derived class. Through instances of these classes you can receive and send data to the server.

At the subscriber layer, the Kit provides three classes:

- BSubscriber defines the basic rules to which all subscribers must adhere. If you want to use the subscriber layer, this is where you start to learn about it.

- BADCStream provides access to the ADC stream. This stream let you read sound data coming in from an external source, such as a microphone or CD.

- BDACStream provides access to the DAC stream, which lets you access the sound being sent to the system speaker, headphones, or other sound output devices.

The Kit also provides a BSoundFile class that lets you read from and write to sound files, and global functions that let you play sound files.

### Sound Hardware

The sound hardware consists of a number of physical devices (jacks, converters, and the like), a signal path that routes audio data between these devices, and "control points" along the signal path that let you adjust the format and flow of the audio data. These elements are depicted in the following illustration.

- The four large boxes ("inputs," "converters," "streams," and "outputs") divide the signal path into manageable territories; each territory is examined in separate sections, below.

- The smaller boxes ("MIC," "CD," and so on) are actual or virtual sound devices.

- The long arrowed lines show how the devices are connected. A single line indicates a single channel, a double line means stereo. The arrowhead at the end of each line indicates the direction of the signal.

- The circled arrows show where the software can exhibit gain control over a device. Each control point is labelled as it's known to the Media Kit. Every control point has a volume control and can be individually enabled or disabled.

- Not all hardware has all of these devices. Most Macintosh models, for example, do not have the line in device.

#### Inputs

There are three analog audio input devices:

- The microphone. The microphone jack at the back of the computer accepts a stereo mini-phone (1/8") plug. The analog microphone signal has its own volume control and mute, and also allows a 20 dB boost. The microphone signal then feeds into the input MUX.

- Line-in. The stereo line-in jacks at the back of the computer bring a line-level analog signal into the computer. This signal can be routed directly to the audio output devices, and fed to the MUX. The direct-to-output, or "through," path has its own volume control and mute; this control point is called `B_LINE_IN_THROUGH` by the Kit. This input device is available on all BeBox models, but is not necessarily present on all Macintosh or PC systems.

- CD input. The CD (analog) input has the same features as line-in: The CD signal can be sent through to the output (`B_CD_THROUGH`), and it can be fed to the MUX.

Note that the microphone signal doesn't have a through path.

To bring an analog signal into your application (so you can record it, for example), the signal must pass through the input MUX:

- The MUX is a "mutually exclusive" device that lets you choose a single (analog) input from among the three sources listed above. In other words, you can bring in the microphone signal or the line-in signal or the CD signal, but you can't bring in any two or all of them at the same time. The MUX passes the input signal to its output without conversion to digital representation or other modification.

#### Converters

There are two sound data converters, the analog-to-digital converter (ADC) and the digital-to-analog converter (DAC):

The ADC takes the analog signal that it reads from the MUX and converts it to digital representation. It does this by producing a series of samples, or instantaneous measurements of the signal's amplitude. The ADC control point is called `B_ADC_IN.`

The DAC converts digital sound data into a continuous analog signal. The DAC control point is called `B_DAC_OUT`.

Acting as a sort of "short-circuit" between these two devices is the loopback:

- The loopback path takes the digital signal straight out of the ADC and sends it to the DAC. This path is intended, primarily, to simulate a "through" path for the microphone signal. There's little reason to send the line-in or CD signal down the loopback path since they have actual through paths built in.

#### Streams

The ADC stream and DAC stream are represented in the Media Kit by the BADCStream and BDACStream classes. By subscribing to the ADC stream you can receive the samples that are emitted by the ADC; and by subscribing to the DAC stream, you can send buffers of digital sound data to the DAC.

The process of subscribing to a stream is described in the BSubscriber class.

#### Outputs

The output devices take analog signals and broadcast them to hardware that can turn the signals into sound.

- The output mixer mixes the signal from the DAC with the signals from the line-in and CD through paths. You can control the output of this mix at the `B_MASTER_OUT` control point.

- The mixed signal is presented at the stereo line-out jacks at the back of the computer. This is the same signal that's presented at the headphone jack.

- The stereo signal is mixed to mono (and attenuated by 6 dB) and sent to the abysmal internal speaker. The speaker has its own volume and mute control (`B_SPEAKER_OUT`).

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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.