The Media Kit: BAudioSubscriber

Derived from: public BSubscriber

Declared in: <media/AudioSubscriber.h>

Overview

BAudioSubscriber objects perform two functions:

Ultimately, the first point is the more interesting of the two: Recording, generating, and manipulating sound data is a bit more amusing than simply setting the volume levels of the hardware devices. But to understand how and what data is received by your BAudioSubscriber objects, and what happens when you broadcast data through an object, you should first understand how the hardware is configured. The next section examines the sound hardware; following that is a description of the sound data that appears in your application.

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 a mute.

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.

• 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 the centerpieces of the BAudioSubscriber class. 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.

To enter the ADC stream you must create a BAudioSubscriber, subscribe to the stream (by passing B_ADC_STREAM as the first argument to Subscribe()), and then call EnterStream(). At that point, your object will begin receiving buffers of ADC-converted data from the Audio Server. The buffers show up as arguments to the object's stream function.

Similarly, the DAC stream universe is broached by subscribing to and entering the B_DAC_STREAM.

If you're unfamiliar with the concepts of subscription, entering a stream, and the stream function, take a break and read the BSubscriber specification.

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

Controlling the Hardware

The BAudioSubscriber class defines a number of functions that control the sound hardware and that query the state of the hardware. Note that you can call these functions without first subscribing to one or the other of the audio streams.

Volume and Mute

To set the volume level of a particular sound device, you use BAudioSubscriber's SetVolume() function. The function takes three arguments:

The device constants are listed below; they correspond to the named control points shown in the hardware diagram:

All volume levels are floating-point numbers in the range [0.0, 1.0], where 0.0 is inaudible, and 1.0 is maximum volume. If you're setting a single-channel device (the speaker), the left channel level is used--the value you pass as the right channel level is ignored. If you want to set one channel of a stereo device but leave the other at its present level, pass the B_NO_CHANGE constant for the no-change channel.

In the example below, a BAudioSubscriber is used to set the volume of the CD-through signal:

   BAudioSubscriber *setter = BAudioSubscriber("setter");
   
   /* Set the right channel of the CD through signal
    * to half the maximum volume, and leave the left channel
    * alone.  
    */
   setter->SetVolume(B_CD_THROUGH, B_NO_CHANGE, 0.5);

To mute a device, you disable it; or, more precisely, you set it to be not enabled. This is done through the EnableDevice() function. As with SetVolume(), the function's first argument is the constant that represents the device you want to control. The second argument is a boolean that states whether you want to enable (TRUE) or disable (FALSE) the device. For example:

   /* Mute the internal speaker. */
   setter->EnableDevice(B_SPEAKER_OUT, FALSE);

The GetVolume() and IsDeviceEnabled() functions retrieve the current volume and enabled state of a given device. (As a convenience, GetVolume() returns volume and enabled status; see the function description for details.)

The MUX and the Mic

To select the analog device that will feed into the MUX, you use the SetADCInput() function (the signal into the MUX goes to the ADC, hence the name of the function). The input devices are represented by these constants:

The ADCInput() function returns the current input device.

The microphone's 20 dB boost is toggled through the BoostMic() function. The state of the boost is retrieved by IsMicBoosted().

Sound Data

Sounds are propagated by the continuous fluctuation of air pressure. This fluctuation is called a sound wave. The digital representation of a sound wave consists of a series of discrete measurements of the instantaneous pressure (or amplitude) of the wave at precise, (typically) equally-spaced points in time. Each measurement is called a sample . There are five attributes that characterize a digital sound sample:

• The size of a single sound sample (the Media Kit expresses this measurement in bytes-per-sample).

• The order of bytes in a multiple-byte sample.

• The number of samples in a "frame" of sound, where each sample in the frame is meant to be played at the same time. For example, a stereo sound would have two samples-per-frame. Samples-per-frame is commonly called the channel count .

• The number of frames that should be played in a second. This is commonly called the sampling rate.

• The mapping from the value of a digital sample to a specific sound wave amplitude. The Media Kit calls this the sample format. Usually, the mapping is linear: When you double the value of a sample, you double the amplitude to which it corresponds.

The Be sound hardware (both the ADC and the DAC) allows the following sound attribute settings:

• Sample size can be one or two bytes-per-sample.

• Byte-ordering is either most-significant-byte first (B_BIG_ENDIAN), or least- significant-byte first (B_LITTLE_ENDIAN).

• The channel count can be one (mono) or two (stereo).

• The sampling rates, expressed as frames-per-second, that are supported by the hardware are: 5510, 6620, 8000, 9600, 11025, 16000, 18900, 22050, 27420, 32000, 33075, 37800, 44100, 48000.

• There are two sample formats: The linear format, represented by the constant B_LINEAR_SAMPLES , can be used with either one- or two-byte samples. The "mu-law" format ( B_MULAW_SAMPLES ) can only be used with one-byte samples. Mu-law is a quasi-exponential mapping that attempts to minimize quantization noise by dedicating more bits, proportionally, to low amplitude values than to high amplitude values.

The ADC and DAC use the same sampling rate. You can set the sampling rate through BAudioSubscriber's SetSamplingRate() function, but you can't specify which device you intend the setting to apply to: It always applies to both.

As for the other sound data parameters (sample size, byte order, channel count, and sample format), the ADC and the DAC maintain independent settings. For example, you can set the DAC to expect two-byte linear samples while the ADC produces one-byte mu-law samples. The functions that set these sound format attributes are SetDACSampleInfo() and SetADCSampleInfo(). Your BAudioSubscriber needn't subscribe before setting the DAC or ADC parameters.

Receiving and Broadcasting Sound Data

A BAudioSubscriber object receives buffers of sound data from one of the Audio Server's two buffer streams:

• The buffers that flow through the ADC stream are filled with sound data that's been brought into the computer, passed through the MUX, and converted by the ADC. Data buffers that are received by your objects will already be filled with this data. Although it's not forbidden, you usually don't modify the data in the ADC stream's buffers. BAudioSubscribers that enter the ADC stream do so, typically, to record or examine the data that they find there.

• The buffers that flow through the DAC stream are ultimately dumped into the DAC. The DAC stream's buffers are zeroed at the start of their journey; if a BAudioSubscriber wants to broadcast a sound, it enters the DAC stream and adds its sound data into the buffers as they flow past.

The ADC stream isn't automatically connected to the DAC stream. If you want to grab data from the ADC and send it to the DAC, you have to subscribe to both streams through two separate BAudioSubscriber objects, and then coordinate the hand off of data from the ADC subscriber to the DAC subscriber.

Constructor and Destructor

BAudioSubscriber()

      BAudioSubscriber(const char *name)

Creates and returns a new BAudioSubscriber object. The object is given the name that you pass as name; the name is provided as a convenience and needn't be unique.

After creating a BAudioSubscriber, you typically do the following (in this order):

• Subscribe the object to one of the Audio Server's streams (either B_ADC_STREAM or B_DAC_STREAM) by calling Subscribe().

See also: BSubscriber::Subscribe() , BSubscriber::EnterStream()

~BAudioSubscriber()

      virtual ~BAudioSubscriber(void)

Destroys the BAudioSubscriber.

Member Functions

ADCInput(), SetADCInput()

      long ADCInput(void)
      long SetADCInput(long device)

These functions get and set the device that feeds into the MUX (and so to the ADC, hence the name). Valid device constants are:

You don't need to be subscribed to the ADC stream in order to call these functions.

BoostMic(), IsMicBoosted()

      long BoostMic(bool boost)
      bool IsMicBoosted(void)

BoostMic() enables or disables the 20 dB boost on the microphone signal. IsMicBoosted() returns the state of the boost.

GetADCSampleInfo(), GetDACSampleInfo(), SamplingRate()

      long GetADCSampleInfo(long *bytesPerSample,
         long *channelCount,
         long *byteOrder,
         long *sampleFormat)
      long GetDACSampleInfo(long *bytesPerSample,
         long *channelCount,
         long *byteOrder,
         long *sampleFormat)
      long SamplingRate(void)

These functions return the values of the various sound data parameters. GetADC... returns (by reference) the sound parameters that are used in the ADC stream. GetDAC... does the same for the DAC stream. SamplingRate() returns the sampling rate directly; the sampling rate is held in common by the two streams.

See the description of SetADCSampleInfo() for a list of parameter values that you can expect to see.

See also: SetADCSampleInfo()

GetDACSampleInfo() see GetADCSampleInfo()

SetADCSampleInfo(), SetDACSampleInfo(), SetSamplingRate()

      long SetADCSampleInfo(long bytesPerSample,
         long channelCount,
         long byteOrder,
         long sampleFormat)
      long SetDACSampleInfo(long bytesPerSample,
         long channelCount,
         long byteOrder,
         long sampleFormat)
      long SetSamplingRate(long samplingRate)

These functions set the values of the sound data attributes used by (respectively) the ADC stream (SetADC...), DAC stream (SetDAC...), and both streams ( SetSamplingRate()). The arguments to the SetADC... and SetDAC... functions are:

• bytesPerSample is the size of a single sound sample measured in bytes. Acceptable values are 1 and 2.

• channelCount is the number of samples in a "frame" of sound. Acceptable values are 1(mono) and 2 (stereo).

• byteOrder is the order of bytes in a multiple-byte sample. The ordering is either B_BIG_ENDIAN or B_LITTLE_ENDIAN .

• sampleFormat is the data format of a single sample. Linear format (B_LINEAR_SAMPLES ) can be used for one- or two-byte samples; mu-law format (B_MULAW_SAMPLES) can be used for 1-byte samples.

The SetSamplingRate() function sets the sampling rate for both the ADC stream and the DAC stream:

• The following sampling rates are supported by the sound hardware: 5510, 6620, 8000, 9600, 11025, 16000, 18900, 22050, 27420, 32000, 33075, 37800, 44100, 48000.

These functions don't flinch at wildly inappropriate parameter settings. The values of the arguments that you pass in are always rounded to the nearest acceptable value for the particular parameter.

See also: GetADCSampleInfo()

SetDACSampleInfo() see SetADCSampleInfo()

SetVolume(), GetVolume() , EnableDevice(), IsDeviceEnabled()

      long SetVolume(long device, 
         float leftVolume, 
         float rightVolume)
      long GetVolume(long device,
         float *leftVolume, 
         float *rightVolume, 
         bool isEnabled)

      long EnableDevice(long device, bool enable)
      bool IsDeviceEnabled(long device)

These functions set and return (by reference) the left and right volume levels, and the enabled status of the device that's identified by the first argument. Valid device constants are:

Volume values are floating-point numbers that are clipped within the range [0.0, 1.0]. Across this range, the amplitude of a sound waveform is increased logarithmically; this results, perceptually, in a linear increase in volume.

Note that the speaker is monophonic; when you set or retrieve the volume of the B_SPEAKER_OUT device, only the leftVolume argument is used.

You needn't be subscribed to call these functions.

The Be Book, HTML Edition, for Developer Release 8 of the Be Operating System.

Copyright © 1996 Be, Inc. All rights reserved.

Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.

Last modified September 6, 1996.