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