# The Media Kit: BADCStream

Derived from: BAbstractBufferStream

Declared in: be/media/AudioStream.h

Library: libmedia.so

## Overview

The BADCStream class represents the sound input stream. Subscribers to this stream receive buffers containing audio data that have been input from external sources (such as microphones or the CD audio player). This stream is available even in the absence of an input source (in which case the buffers your BSubscriber receives will have all zero samples).

Once you've subscribed to this stream, you can process the incoming data by saving it into a sound file, cacheing it into a memory buffer, or you can even alter the data in the buffer to filter incoming sound data. In fact, by using two subscribers (one to a BADCStream object and one to a BDACStream object), you can shunt incoming sound data into the output stream.

The sections on the BSubscriber and BDACStream classes contain additional information on buffer streams, subscribers, and audio formats.

### Controlling the Hardware

The BADCStream class provides several functions that let you control the sound input hardware as well as determine the current state of the hardware. These functions can be used even if you haven't subscribed to the stream yet.

#### Selecting a Source

You can control which of the audio sources you wish to receive data from by using the `SetADCInput()` call. Likewise, you can determine which source is currently being used by calling `ADCInput()`:

       BADCStream stream;
       stream->SetADCInput(B_CD_IN);   // Use CD-ROM audio input

       int32 currentDevice;
       stream->ADCInput(&currentDevice);   // What device is input?

Valid devices are:

- `B_MIC_IN` Microphone input.
- `B_CD_IN` Compact disc input.
- `B_LINE_IN` Line input.

#### The Microphone Boost

There is an optional 20 dB boost available for the microphone input. This can be turned on and off using the `BoostMic()` function. The current status of the boost can be determined using the `IsMicBoosted()` function.

       if (!IsMicBoosted()) {
          stream->BoostMic(true);   // Turn on the 20 dB boost
       }

The above code turns on the boost if it's not already on (in reality, you don't need to check before turning the boost on--just turn it on if you need it, and turn it off if you don't). There is no guaranteed default value for whether or not the microphone is boosted; the Sound preference panel allows users to set the default for the 20 dB boost.

#### Sampling Rate

BADCStream provides two functions for controlling and determining the current sampling rate of the ADC stream.

The `SetSamplingRate()` function is used to change the sampling rate currently in effect on the ADC stream. If you want to sample CD-quality sound, for example, you would issue the following call, assuming that `stream` is a pointer to your BADCStream object:

       stream->SetSamplingRate(44100.0);

You can specify any sampling rate you wish; if the rate you specify isn't supported by the sound hardware of the computer your application is running on, the closest available rate will automatically be selected.

To determine the current sampling rate, use the `SamplingRate()` function:

       float currentRate;
       stream->SamplingRate(&currentRate);

After the above code executes, the `currentRate` variable will contain the current sampling rate.

For more detailed information on sampling rates and sample formats, see the BDACStream class overview.

#### Managing the Buffers

If you wish, you can refine the performance of your software by specifying the size and the number of audio buffers in the ADC stream. The Audio Server provides acceptable defaults for both the size and number of buffers in the stream. However, you can change these settings using the `SetStreamBuffers()` function.

- By decreasing the size and/or number of buffers, you can decrease the maximum latency of the stream (the time it takes for a buffer to get from one end of the stream to the other). However, if you go too far in this direction, you run the risk of falling out of real time.

- By increasing the buffer size and count, you help ensure the real-time integrity of the stream, but you increase its maximum latency.

For instance, if your experiments have determined that your code will work most efficiently with six 4k buffers, you would use the following code to establish the new buffers:

       outStream->SetStreamBuffers(4096, 6);

This specifies that each of the six buffers in the stream should be 4,096 bytes (4k) long. The change affects all applications using the ADC stream. Since your application may not be alone using the stream, you should keep in mind that other applications may use this call as well, so be sure your code can handle buffers that change in size from one invokation of your stream function to the next.

## Constructor and Destructor

### BADCStream()

          BADCStream()

Creates and returns a new BADCStream object, which represents a sound input stream.

After creating a BADCStream, you can use the resulting pointer as the stream parameter for your subscriber's `Subscribe()` call:

       BSubscriber            *subscriber;
       BADCStream            *stream;

       subscriber = new BSubscriber();
       stream = new BADCStream();
       subscriver->Subscribe(stream);

Once you've subscribed to the output stream, you can proceed to enter the stream, at which point your stream function will begin receiving incoming audio buffers.

### ~BADCStream()

          virtual ~BADCStream()

Destroys the BADCStream object. Don't do this if you have a BSubscriber currently subscribed to the stream.

## Member Functions

### ADCInput(), SetADCInput()

          status_t ADCInput(int32 *currentDevice) const

          status_t SetADCInput(int32 newDevice)

These functions get and set the device that provides the sound input for this BADCStream object.

Valid values for device are:

- `B_MIC_IN` Microphone input.
- `B_CD_IN` Compact disc input.
- `B_LINE_IN` Line input.

You don't have to have already subscribed to the stream to use these functions. If an error occurs, `ADCInput()` does not alter the memory at pointed to by currentDevice.

RETURN CODES

- `B_OK`. The operation was a success.
- `B_BAD_REPLY`. Unable to determine or change the input device.
- `B_SERVER_NOT_FOUND`. The Audio Server is not running.

### BoostMic(), IsMicBoosted()

          status_t BoostMic(bool boost)

          bool IsMicBoosted() const

`BoostMic()` enables (if boost is `TRUE`) or disables (if boost is `FALSE`) the 20 dB boost on the microphone signal. `IsMicBoosted()` returns the current state of the boost.

You don't have to already have subscribed to the stream to use these functions.

RETURN CODES

- `B_OK`. The operation was a success.
- `B_BAD_REPLY`. Unable to determine or change the current boost setting.
- `B_SERVER_NOT_FOUND`. The Audio Server is not running.

### SamplingRate(), SetSamplingRate()

          status_t SamplingRate(float *currentRate)

          status_t SetSamplingRate(float newRate)

These functions allow you to get and set the current sampling rate of the stream.

When calling `SetSamplingRate()` to set the current sampling rate, the value you specify will automatically be rounded to the nearest value accepted by the hardware on which your application is running.

You don't have to already have subscribed to the stream to use these functions. If an error occurs, `SamplingRate()` does not alter the memory pointed to by currentRate.

RETURN CODES

- `B_OK`. The operation was a success.
- `B_BAD_REPLY`. Unable to determine or change the current sampling rate.
- `B_SERVER_NOT_FOUND`. The Audio Server is not running.

### SetADCInput() see ADCInput()

### SetSamplingRate() see SamplingRate()

### SetStreamBuffers()

          status_t SetStreamBuffers(size_t bufferSize, int32 bufferCount)

Sets the size in bytes and the number of buffers that are used to transport data through the stream. Although it's up to the server to provide reasonable default values, you can fine-tune the performance of the stream by adjusting these values:

- By decreasing the size and/or number of buffers, you can decrease the maximum latency of the stream (the time it takes for a buffer to get from one end of the stream to the other). However, if you go too far in this direction, you run the risk of falling out of real time.

- By increasing the buffer size and count, you help ensure the real-time integrity of the stream, but you increase its maximum latency.

RETURN CODES

- `B_OK`. The operation was a success.
- `B_BAD_REPLY`. Unable to determine or change the buffer settings.
- `B_SERVER_NOT_FOUND`. The Audio Server is not running.

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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.