-
Notifications
You must be signed in to change notification settings - Fork 45
SampleEvent
A SampleEvent is a direct subclass of BaseAudioEvent and describes an AudioEvent whose source comes from an external source, i.e. a recording made from another source in the application, or the contents of an external file, etc. For instance : a SampleEvent can hold the contents of a recording of a snare drum, to be played back as part of a drum machine.
Additionally, a SampleEvent can also have its own playback range relative to its own buffered content. This means that while the regular eventStart, eventEnd and eventLength-properties are used to describe the events duration and position to the Sequencer, the internal playback range will allow the event to playback snippets of its own sample buffer contents relative to the Sequencer s request.
For instance : you have a sample of a spoken sentence : "I love this engine" and you only want to play back the word "love". You set the internal range start and end to the corresponding positions where the word "love" occurs in the buffer, and listen in awe how only this smaller range of the buffer is played back by the Sequencer, omitting the remainder of the buffer. If you set setLoopeable() to true, this range is now repeated continuously. Note you can alter the values for the buffer range (as well as the loopeable state!) in realtime, creating great glitchy effects. You can see this inner range as an internal sequencer on top of the engine's sequencer.
The Instrument associated with a SampleEvent is the SampledInstrument.
SampleEvent( BaseInstrument* aInstrument );
Constructs a new SampleEvent and invokes its protected init-method. aInstrument is the SamplerInstrument the event instance belongs to.
~SampleEvent();
Invokes removeFromSequencer-method. Note that base BaseAudioEvent destructor is also invoked.
bool isLoopeable()
void setLoopeable( bool value, int crossfadeInMilliseconds )
Enable / disable looping for this event instance. When true, as soon as this SampleEvents sample buffer has been played back in its entirety, the playback will continue from the beginning of the sample. Note that for sequenced events, the event length must be increased in order to have an audible loop (by default, the event length/duration of a SampleEvent is equal to that of its source AudioBuffer and will thus only play once. In order to hear looping, the length must be increased accordingly). Parameter crossfadeInMilliseconds can be used to apply optional cross fading to the samples at the end/beginning of the loop region, where the value corresponds to a total crossfade time in milliseconds. This can be used if the loop points of your sample do not occur at a zero crossing (e.g. when the amplitude of the sample is at 0.0) to prevent popping upon looping. It is recommended to choose zero crossing regions when specifying your sample's loop region and have crossfade be specified as 0 (so none is applied).
int getLoopStartOffset()
void setLoopStartOffset( int value )
When looping, you can define the offset at which the loop should occur. This offset is relative to the size of the SampleEvents source AudioBuffer. This defaults to 0 to start looping from the beginning. This can be used to artificially "lengthen" notes (for instance: a sample of a plucked string where the transient of the pluck is only played once after which the loop occurs at the sustain phase). When using alternate playback rates, this value is scaled automatically to reflect the transformed offset. As such the value provided here should always be relative to the raw source buffer. For best results, define the loop start offset at a zero crossing point to avoid popping (also see setLoopeable())
int getLoopEndOffset()
void setLoopEndOffset( int value )
When looping, you can also define the offset at which playback should end. This offset is relative to the size of the SampleEvents source AudioBuffer. This defaults to the last sample available in the source buffer (so the sample is played in full). This can be used to cut off unwanted content from the sample, without using custom buffer ranges. Alternate playback rate and zero crossing rules are the same as for the loops start offset.
int getReadPointer()
Retrieves the offset of the SampleEvent internal "playback-head position" when the SampleEvent is loopeable. For instance: if the events duration lasts for 500 samples, but the buffer is only 300 samples long, this pointer will read from the beginning of the buffer for another 200 samples. Used internally.
int getBufferRangeStart()
Gets the start offset of the SampleEvents custom playback range.
setBufferRangeStart( int value )
Sets the start offset of the SampleEvents custom playback range to value.
int getBufferRangeEnd()
Gets the end offset of the SampleEvents custom playback range. In case the _playbackRate of the event is unequal to 1.f this will automatically return the appropriate value to make up for the altered duration.
setBufferRangeEnd( int value )
Sets the end offset of the SampleEvents custom playback range to value. This value cannot exceed the full length of the events _buffer (note: the length of an events AudioBuffer does not have to equal the eventLength-property!). The value passed here is relative to the _original sample regardless of current _playbackRate.
int getBufferRangeLength()
Gets the total length of the buffer range, this can only be set by using setBufferRangeEnd().
int getPlaybackPosition()
Returns the offset of a SampleEvents current "playback-head position", when it is playing back as a live event (e.g. after having been triggered using play()).
unsigned int getSampleRate()
Returns the sample rate (in Hz) associated with the sample assigned to this event (see setSample()).
void setSample( AudioBuffer* sampleBuffer )
Overloaded function that will automatically pass the sample rate of the engine to its overloaded twin. This will imply that no resampling will occur when playing back the sample, see Pitch shifting and resampling samples.
void setSample( AudioBuffer* sampleBuffer, unsigned int sampleRate )
Sets the contents of given sampleBuffer as the _buffer for the SampleEvent instance. By default this will set the internal buffer range playback equal to the eventStart, eventEnd and eventLength values for 1:1 playback of the source buffer content. When replacing an existing sample, the buffer ranges will also be set to the full sample range.
When given sampleRate (in Hz) is different to the engine's configured sample rate, the playback rate of the event adjusted accordingly to ensure that the sample will play back at its original pitch and length.
If inherited protected property _destroyableBuffer is set to true, the incoming sampleBuffer is cloned and unique to the SampleEvent (it will be destroyed by the base destructor upon deletion of the SampleEvent). If it set to false, the SampleEvents _buffer will be a pointer to the sampleBuffer. This can be used to conserve memory when sharing samples between events (for instance : re-using the same drum snare-sample between SampleEvents).
You can repeatedly call this method to update the contents of the SampleEvent instance. Previous buffers will be deleted (or not) relating to the value of _destroyableBuffer. It is recommended to let the SampleManager handle the allocation and deallocation of samples (especially as a single sample can be reused across multiple events).
float getPlaybackRate()
Returns the playback speed at which this SampleEvents contents will be rendered by the audio engine.
void setPlaybackRate( float value )
You can think of an adjusted playback rate as the "playback head" of the SampleEvent moving at a different speed than the engine, resulting in pitch shifting and time stretching results similar to those experienced by slowing down a tape recording by pressing your finger against the reel. A default playback rate of 1.f will be assigned upon construction.
By increasing this value above 1, the playback rate will increase, which will lead to the pitch of the sample shifting up as well as its duration to decrease accordingly. By setting a playback rate below 1, this will lower the pitch of the sample as well as increase its duration. Also see Pitch shifting and resampling samples. This method is automatically invoked when setting a sample with a sample rate different to the engine (see setSample()). NOTE: Adjusting playback rate will update the values of base methods getEventLength() and getEventEnd() accordingly to reflect the changes in altered duration, the same goes for looping events with extended duration or when using custom loop start and end offsets, all these values will be scaled to ratio. Therefor there is no need to multiply by the playback rate in any of the range based setters.
bool getBufferForRange( AudioBuffer* buffer, int readPos )
Mix in the contents of the SampleEvents buffer starting at given readPos, returns boolean value whether or not something was written to given buffer.
init( BaseInstrument* instrument )
Pre-initializes instance properties.
void cacheFades()
Caches the values when crossfading loopeable events.
bool _loopeable
int _loopStartOffset
int _loopEndOffset
int _crossfadeMs
int _crossfadeStart
int _crossfadeEnd
Describe the loopeable state and optional range of the event.
int _bufferRangeStart
int _bufferRangeEnd
int _bufferRangeLength
Hold the values of the public getters / setters described above. Note _bufferRangeLength is calculated internally by the bufferRangeStart / bufferRangeEnd-setters.
float _playbackRate;
The speed at which the events sample should be read, defaults to 1.f. See setPlaybackRate().
BaseInstrument* _instrument
The SampledInstrument the event belongs to.