BSynth

Derived from: (none)

Declared in: be/midi/Synth.h

Library: libmidi.so

[method summary]

The BeOS includes a General MIDI software synthsizer designed by HeadSpace <etc.> The BSynth class is the interface to the synthesizer itself. Any application that wants to use the synthesizer must include a BSynth object; however, most applications won't need to create the object directly:

For "lightweight" use of the synthesizer--if you just want to play a MIDI file (for example) but don't need to fiddle with the synthesizer's virtual knobs and buttons--you can ignore BSynth and move on to the BMidiSynth, BMidiSynthFile, and BSamples classes. These classes create a BSynth for you.

Constructor and Destructor

BSynth()

      BSynth(void)
      BSynth(synth_mode mode)

Creates a new BSynth object and sets be_synth (the application-wide BSynth pointer) to point to it. The BSynth that be_synth previously pointed to (if any) is deleted. You should follow the constructor with a call to LoadSynthData() to initialize the synthesizer.

The default constructor tries to locate and load the "big" synthesizer. Failing that, it looks for the "little" synthesizer; if it can find neither, the default constructor fails (it doesn't initialize for "samples only").

The synth_mode constructor let's you specify the synthesizer's initialization. Of the six synth_mode constants, four are useful as mode arguments:

• B_BIG_SYNTH. Use the big synthesizer.

• B_LITTLE_SYNTH. Use the little synthesizer.

• B_SAMPLES_ONLY. Don't load a synthesizer, but prepare the object so it can play sampled sounds. You only use this mode if you're only going to use the BSamples object (in other words, if you're not using BMidiSynth or BMidiSynthFile).

• B_DEFAULT_SYNTH. In this mode, the object follows the default initialization path: big synth first, then little synth, then fail.

You can only construct one BSynth object per application. Every application that wants to use the synthesizer must have its own BSynth--you can't "share" another application's be_synth object.

~BSynth()

      ~BSynth()

The destructor stops the synthesizer if it's currently playing anything, frees all synthesis-related storage that the BSynth object allocated, and sets be_synth to point to NULL.

Initializing the Synthesizer

LoadSynthData(), Unload(), SynthMode()

      status_t LoadSynthData(synth_mode mode = B_DEFAULT_SYNTH)
      status_t LoadSynthData(entry_ref *instrument_file)
      status_t Uninit(void)
      synth_mode SynthMode(void)

After you've constructed a BSynth object, you have to initialize the synthesizer by telling it which "instrument" file to load. The instrument file contains descriptions of individual General MIDI instruments. The BSynth object loads the file by copying the entire contents into virtual memory. As individual instruments are needed during a performance, they're locked into RAM. (You can force an instrument to be locked into RAM through BMidiSynth::LoadInstrument().)

Be supplies two instrument files:

There are two ways to load an instrument file:

• You can load it yourself, through LoadSynthData().

• You can let the other MIDI synth classes (BMidiSynth, BMidiSynthFile, and BSamples) load it for you.

Here we describe the do-it-yourself method; see the other classes for details of automatic loading.

LoadSynthData() can be called with a synth_mode constant, or an entry_ref:

• The synth_mode constants represent the Be-supplied instrument files. The constants are described below.

• If you want to use your own instrument file, you initialize the synthesizer by passing an entry_ref that refers to your file.

The synth_mode constants are:

• B_BIG_SYNTH. This represents the "big" instrument file. The instruments in the big file were sampled at 22 kHz, 16-bits.

• B_LITTLE_SYNTH. This is the "little" instrument file. The little instruments are 11 kHz 8-bit data.

• B_DEFAULT_SYNTH. If you specify this mode, the BSynth object first looks for the big file; if the big file is missing or otherwise can't be read, it looks for the little file. If the little file is missing or unreadable, the search fails.

• B_SAMPLES_ONLY. If you want to use the synthesizer to only play sound effects (through a BSamples object), then you won't need an instrument file. In this case, you pass B_SAMPLES_ONLY to LoadSynthData().

• B_NO_SYNTH. This synth_mode constant isn't a valid argument to LoadSynthData().

If the synthesizer is initialized with an instrument file, it will automatically know how to play BSample data.

The big instruments sound better than the small instruments, but they occupy four times more memory.

Any changes to the instrument file that are made after the file is loaded won't be seen by the synthesizer unless you re-load.

The constructors of the other MIDI synthesis classes will call LoadSynthData() automatically if the synthesizer hasn't already been initialized:

• BMidiSynth and BMidiSynthFile initialize with B_DEFAULT_SYNTH.
• BSamples uses B_SAMPLES_ONLY.

These constructor initializations are skipped if the synthesizer is already adequately initialized--they never "downgrade" the synthesizer. See the individual classes for details.

Unload() stops the synthesizer (if it's currently playing), clears the instruments that were loaded into RAM (through the LoadInstruments() function), forgets the instrument file that was used to initialize the synthesizer, and steps out of the audio output mechanism. After you call Unload(), the be_synth object is good for nothing until you re-initialize.

You can re-initialize the synthesizer on the fly without calling Unload() first. In other words, successive LoadSynthData() calls don't require interleaved Unload()s. However, re-initializing while the synthesizer is playing will abort the current MIDI synthesis. BSample output shouldn't be affected (depending on the load on your computer).

SynthMode() returns a synth_mode constant that descibes the synthesizer's current initialization state:

• B_BIG_SYNTH. The synthesizer is using the big instrument file.

• B_LITTLE_SYNTH. The synthesizer is using the little instrument file.

• B_CUSTOM_SYNTH. The synthesizer is using a custom file, something other than the two default files (more accurately, you called LoadSynthData() with an entry_ref that pointed to one of your own instrument files).

• B_SAMPLES_ONLY. The synthesizer is set up to only play BSample data.

• B_NO_SYNTH. The synthesizer is currently uninitialized.

LockInstrument(), UnlockInstrument(), FlushInstruments()

      status_t LockInstrument(uint16 number)
      status_t LockInstrument(midi_axe instrument)
      status_t UnlockInstrument(uint16 number)
      status_t UnlockInstrument(midi_axe instrument)
      status_t FlushInstruments(void)

Normally, instrument data is paged in and out of RAM as needed. If you know which instruments you'll be using, you can tell the synthesizer to lock the instruments into RAM (and do it now!). Locked instruments won't be paged out; when the instrument is unlocked, its data is paged out through the normal course of events.

The LockInstrument() and UnlockInstrument() functions let you designate the target instrument either as a General MIDI instrument number (1 through 128) or as one of the midi_axe constants. See <x> for the complete list of instruments.

Keep in mind that the General MIDI numbers used here correspond to the numbers given in the General MIDI specification. In other words, these numbers start with instrument number 1 (not 0).

The LockInstrument() and UnlockInstrument() return codes are:

FlushInstruments() removes all instruments, locked or not, that are currently in RAM. The instruments aren't thrown away--they'll still reside in virtual memory. Flushing doesn't affect BSample playback (which doesn't rely on instruments).

FlushInstruments() returns:

Setting Sound Parameters

long, SetSamplingRate(long sample_rate);

long, SamplingRate();

long, SetInterpolation(interpolation_mode interp_mode);

interpolation_mode, Interpolation();

void, Unload(void);

bool, IsLoaded(void);

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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified December 23, 1998.