SampleManager

When creating an application that is heavy on playing back prerecorded samples, you require a simple way to store and manage all required samples.

MWEngine cannot read samples directly from disk (and likely never will due to performance concerns). Instead, samples need to be loaded into RAM. The benefit here is that they are instantly available for live playback as well as being available for reuse.

For instance: if you need to play the same sample at a fixed interval or simultaneously, you create several SampleEvents as each specifies the unique properties of their playback (e.g. start time/position, duration, etc.). The sample they reference however, is not unique. Each SampleEvent will reference the same sample (using SampleEvent.setSample()) which points to an entry inside the SampleManager. As such, no duplicate contents are allocated in memory.

storing samples

setSample( std::string identifier, AudioBuffer* buffer, unsigned int sampleRate )

By using above method, the audio contents describes in given buffer are stored under key identifier inside the SampleManager. sampleRate is necessary as samples can have different sample rates as the sample rate of the engine. Sample rate is specified in Hz.

accessing samples and their properties

bool hasSample( std::string identifier )

Queries whether a sample has been registered under given identifier.

getSample( std::string identifier )

Retrieves the AudioBuffer registered under given identifier. If no sample has been registered under given identifier, 0 is returned.

int getSampleLength( std::string identifier )

Returns the length (in samples) of the AudioBuffer registered under given identifier. If no sample has been registered under given identifier, 0 is returned.

int getSampleRateForSample( std::string identifier )

Returns the sample rate (in Hz) of the sample registered under given identifier. If no sample has been registered under given identifier, the sample rate of the engine is returned.

cleaning up after yourself

If you no longer need to use a sample inside your application, you are free to remove it from the SampleManager:

removeSample( std::string identifier, bool free)

Where identifier is the unique identifier used to register the sample and free indicates whether to free the memory allocated to hold the sample data (when true).

flushSamples();

Will remove all samples registered inside the SampleManager and free the memory allocated to them.

Be aware that prior to removing a sample, you must ensure that all SampleEvents that referenced said sample, are no longer registered in the Sequencer / have been disposed as otherwise you're waiting for a violent crash to happen.

Using SampleManager in Java

You can use SampleManager to your hearts desire directly from Java, however setting the samples AudioBuffers can be done more easily using the appropriate wrapper methods describes in JavaUtilities