The Midi Kit: BSamples

The Midi Kit Table of Contents | The Midi Kit Index

# BSamples

Derived from: (none)

Declared in: be/midi/Samples.h

Library: libmidi.so

###### Summary

The BSamples class lets you add a stream of audio samples into the General MIDI mix. The main functionality of the class (such as how you define the sound you want to play, whether it should repeat, what speed it should play at, and so on) is embedded in the `Start()` function; the class' other functions control and fine-tune the sound as it's playing. To learn how to use a BSamples object, go to the `Start()` function.

Theoretically, you can create and play (at the same time) as many BSamples as you want. In practice, you are limited to the sample voice limit set through BSynth's `SetVoiceLimits()` function; by default the limit is set to four.

## Constructor and Destructor

### BSamples()

`BSamples(`void`) `

Creates a new, empty BSamples object. Also constructs a BSynth object and assigns the object to the app-wide `be_synth` variable (if the object doesn't already exist). To initialize and use the BSamples object, invoke its `Start()` function.

Currently, the "samples only" synth mode (B_SAMPLES_ONLY) is broken. Unfortunately, this is the mode used by the BSamples constructor if it has to create a `be_synth` object. The easiest way around this bug is to construct a BMidiSynth or BMidiSynthFile object. If you don't need the object, you can immediately destroy it; the fix is effected by the object's construction.

### ~BSamples()

virtual`` `~BSamples() `

Stops the object's playback, calls the "exit hook" function (as set by `Start()`), and destroys the object.

## Member Functions

### EnableReverb()

void`EnableReverb(`bool reverb`) `

If reverb is true, the object's sound data is sent through the synthesizer's reverberator. To set the reverberation depth (for all reverberated sound), use `BSynth::SetReverb()`.

### IsPlaying() see Stop()

### Pause() see Stop()

### Placement() see SetSamplingRate()

### Resume() see Stop()

### SamplingRate() see SetSamplingRate()

### SetPlacement() see SetSamplingRate()

### SetSamplingRate() , SamplingRate() , SetPlacement() , Placement() , SetVolume() , Volume()

void `SetSamplingRate(`double samplingRate`) `
double `SamplingRate(`void`)` const
void `SetPlacement(`double stereoPan`) `
double `Placement(`void`)` const
void `SetVolume(`double volume`) `
double `Volume(`void`)` const

These functions set parameters of the sound data. They can be called while the sound is playing. For details of what these parameters mean, and the values that they accept, see the descriptions of the samplingRate, stereoPan, and volume arguments of the `Start()` function.

### SetVolume() see SetSamplingRate()

### Start() , sample_loop_hook , sample_exit_hook

void `Start(`void *samples, int32 frameCount, int16 sampleSize, int16 channelCount, double samplingRate, int32 loopStart, int32 loopEnd, double volume, double stereoPan, int32 hookArg, sample_loop_hook loopHook, sample_exit_hook exitHook`) `
typedef bool (*`sample_loop_hook`)(int32 arg)
typedef void (*`sample_exit_hook`)(int32 arg)

`Start()` passes in a buffer of audio samples that are immediately played. The playback is performed by the synthesizer in its BSubscriber thread; the `Start()` function itself returns immediately.

The audio data is assumed to be little-endian linear; other parameters of the data (sample size, channel count, etc.) are variable and are declared in the function's arguments. The arguments are:

- samples is a pointer to the data itself.

- frameCount is the number of frames of audio data in the buffer.

- sampleSize is the size of a single sample, in bytes. Currently, the synthesizer only accepts 1- and 2-byte samples.

- channelCount is the number of channels of data (1 or 2).

- samplingRate is the rate at which you want to the data played back, expressed as frames-per-second; for example, if your sound data was sampled at 44.1kHz and you want to play it back at its "native" pitch, you would set samplingRate to 44100.0. The range of valid sampling rate values is [0, ~65 kHz]. The sampling rate is independent of the data's channel count and sample size, and is independent of `be_synth`'s sampling rate. You can change the object's sampling rate on the fly through `SetSamplingRate()`.

- loopStart and loopEnd specify the first and last frames that are in the "loop section." The loop section can be any valid section of frames within the sound data (i.e. [0, frameCount - 1] inclusive). Everything up to the beginning of the loop section is the "attack section"; everything after the loop section is the "release section." When the sound is played, the attack section is heard, then the loop section is repeated until the object is told to `Stop()`, or until the "loop hook" function (defined below) returns `false`, at which point the release section is played. If you don't want the sound to loop, set these loop... arguments to 0.

| Currently, the release section is automatically faded out over a brief period of time. If your release section is designed to do a slow fade (for example) you probably won't hear it.

- volume is an amplitude scalar for this sound. The volume can also be set through `SetVolume()`.

- stereoPan locates the sound stereophonically, where -1.0 is hard left, 0.0 is center, and 1.0 is hard right. Notice that if this is a stereo sound, a stereoPan value of (say) -1.0 completely attenuates the right channel—it doesn't "move" the right channel into the left channel.

- hookArg is an arbitrary value that's passed to the loopHook and exitHook functions.

- loopHook is a hook function that's called each time the loop section is about to repeat. If the function returns `true`, the loop is, indeed, repeated. If it returns `false`, the release section is played and the sound stops. If you don't supply a loopHook, the loop is automatically repeated.

- exitHook is called when the sound is all done playing, regardless of how it stopped (whether through `Stop()`, a hookFunc return of `false`, or because the BSamples object was deleted).

### Stop() , Pause() , Resume() , IsPaused() , IsPlaying()

virtual void `Stop(`void`) `
void `Pause(`void`) `
void `Resume(`void`) `
bool `IsPlaying(`void`)` const
bool `IsPaused(`void`)` const

`Stop()` tells the object to stop playing its sound data, and invokes the exit function, as set through `Start()`.

`Pause()` suspends playback and `Resume()` resumes it from where it was paused.

| `Pause()` and `Resume()` are backwards. To pause a sound, call `Resume()`. To resume it, call `Pause()`. Sorry about that.

`IsPlaying()` returns `true` if the object is currently playing (paused or not).

`IsPaused()` returns `true` if the sound is currently paused.

| `IsPaused()` returns `true` if you've called`Pause()`. Thus, since `Pause()` and `Resume()` are backwards, the sense of `IsPaused()` is also backwards.

### Volume() see SetSamplingRate()

The Midi Kit Table of Contents | The Midi Kit Index

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

Copyright © 2000 Be, Inc. All rights reserved..