This is the time-domain representation of a wave-form. More...

#include <WaveForm.h>

Inheritance diagram for AudioDataLib::WaveForm:

Classes
struct	Sample
	A wave-form is simply a list of samples. More...

struct	SampleBounds

Public Types
enum	InterpolationMethod { LINEAR , CUBIC }

enum	TrimSection { BEFORE , AFTER }

Public Member Functions
	WaveForm ()

virtual	~WaveForm ()

virtual double	EvaluateAt (double timeSeconds) const override

uint64_t	GetSizeBytes (const AudioData::Format &format, bool allChannels) const

bool	ConvertFromAudioBuffer (const AudioData::Format &format, const uint8_t *audioBuffer, uint64_t audioBufferSize, uint16_t channel, Error &error)

bool	ConvertToAudioBuffer (const AudioData::Format &format, uint8_t *audioBuffer, uint64_t audioBufferSize, uint16_t channel, Error &error) const

void	Clear ()

void	Copy (const WaveForm *waveForm)

void	AddSample (const Sample &sample)

void	MakeSilence (double samplesPerSecond, double totalSeconds)

void	SumTogether (const std::list< WaveForm * > &waveFormList)

bool	FindTightestSampleBounds (double timeSeconds, SampleBounds &sampleBounds) const

bool	Renormalize ()

void	Scale (double scale)

void	Clamp (double minAmplitude, double maxAmplitude)

bool	Trim (double startTimeSeconds, double stopTimeSeconds, bool rebaseTime, Error &error)

void	QuickTrim (double timeSeconds, TrimSection trimSection)

void	SortSamples ()

uint64_t	PadWithSilence (double desiredDurationSeconds, double sampleRate)

double	AverageSampleRate () const

double	GetStartTime () const

double	GetEndTime () const

double	GetTimespan () const

uint64_t	GetNumSamples () const

double	GetMaxAmplitude () const

double	GetMinAmplitude () const

double	CalcAverageVolume () const

bool	ContainsTime (double timeSeconds) const

InterpolationMethod	GetInterpolationMethod () const

void	SetInterpolateionMethod (InterpolationMethod interpMethod)

const std::vector< Sample > &	GetSampleArray () const

std::vector< Sample > &	GetSampleArray ()

void	Interpolate (const SampleBounds &sampleBounds, double timeSeconds, Sample &interpolatedSample) const

Public Member Functions inherited from AudioDataLib::Function
	Function ()

virtual	~Function ()

virtual double	EvaluateDerivativeAt (double x) const

Protected Member Functions
template<typename T >
void	CopyIntSampleToBuffer (uint8_t *sampleBuffer, double sampleNormalized) const

template<typename T >
void	CopyFloatSampleToBuffer (uint8_t *sampleBuffer, double sampleNormalized) const

template<typename T >
double	CopyIntSampleFromBuffer (const uint8_t *sampleBuffer)

template<typename T >
double	CopyFloatSampleFromBuffer (const uint8_t *sampleBuffer)

Protected Attributes
std::vector< Sample > *	sampleArray

InterpolationMethod	interpMethod

Friends
class	Index

Detailed Description

This is the time-domain representation of a wave-form.

To be more specific, this is a descrete wave-form. Since we represent the wave-form function as a sequence of plots (or samples) in the plane, this form is independent of format and sampling rate. Most math operations performed on wave-forms are done using this class, since it is format-ignostic or free from the considerations and limitations of any particular audio format.

A wave-form, therefore, is just a list of audio samples, each being a time and "amplitude" pair. Most operations assume that the samples are in chronological order.

Member Enumeration Documentation

◆ InterpolationMethod

enum AudioDataLib::WaveForm::InterpolationMethod

Enumerator
LINEAR	Use the line containing two different samples as the means of interpolation.
CUBIC	Use the cubic polynomial fitting four different samples as the means of interpolation. This is more expensive.

◆ TrimSection

enum AudioDataLib::WaveForm::TrimSection

Enumerator
BEFORE	Trim the beginning of the wave-form.
AFTER	Trim the end of the wave-form.

Constructor & Destructor Documentation

◆ WaveForm()

WaveForm::WaveForm ( )

◆ ~WaveForm()

WaveForm::~WaveForm ( )

virtual

Member Function Documentation

◆ AddSample()

void WaveForm::AddSample ( const Sample & sample )

Add a sample to the end of this wave-form's list of samples.

◆ AverageSampleRate()

double WaveForm::AverageSampleRate ( ) const

Calculate and return the average sampling rate of this wave-form. The samples in a wave-form don't necessarily have a uniform distribution, but if they did, then this would return the sampling rate of the wave-form.

◆ CalcAverageVolume()

double WaveForm::CalcAverageVolume ( ) const

This function is not very well defined. I may remove it at some point.

◆ Clamp()

void WaveForm::Clamp	(	double	minAmplitude,
		double	maxAmplitude )

Make sure that all samples are in the given range.

◆ Clear()

void WaveForm::Clear ( )

Remove all samples from this wave-form.

◆ ContainsTime()

bool WaveForm::ContainsTime ( double timeSeconds ) const

Return true if and only if the given time is within this wave-form's time-span.

◆ ConvertFromAudioBuffer()

bool WaveForm::ConvertFromAudioBuffer	(	const AudioData::Format &	format,
		const uint8_t *	audioBuffer,
		uint64_t	audioBufferSize,
		uint16_t	channel,
		Error &	error )

Read the given raw audio data in the given format and generate from it a wave-form in the cartesian coordinate plane.

Parameters

[in]	format	This is the format of the given audio data.
[in]	audioBuffer	This is a buffer containing the raw audio data, presumably in the given format.
[in]	audioBufferSize	This is the size in bytes of the given audio buffer.
[in]	channel	This is which channel of the audio buffer to read as this wave-form.
[out]	error	This will contain detailed error information if false is returned.

Returns: True is returned on success; false otherwise.

◆ ConvertToAudioBuffer()

bool WaveForm::ConvertToAudioBuffer	(	const AudioData::Format &	format,
		uint8_t *	audioBuffer,
		uint64_t	audioBufferSize,
		uint16_t	channel,
		Error &	error ) const

Write this wave-form into the given audio buffer in the given format.

Parameters

[in]	format	This is the format in which to write the audio data.
[out]	audioBuffer	This is where to write the raw audio data in the given format.
[in]	audioBufferSize	This is the size of the given audio buffer in bytes.
[in]	channel	This is the channel of the audio buffer to write as this wave-form.
[out]	error	This will contain detailed error information if false is returned.

Returns: True is returned on success; false otherwise.

◆ Copy()

void WaveForm::Copy ( const WaveForm * waveForm )

Make this wave-form a copy of the given wave-form.

◆ CopyFloatSampleFromBuffer()

template<typename T >

double AudioDataLib::WaveForm::CopyFloatSampleFromBuffer ( const uint8_t * sampleBuffer )

inlineprotected

◆ CopyFloatSampleToBuffer()

template<typename T >

void AudioDataLib::WaveForm::CopyFloatSampleToBuffer	(	uint8_t *	sampleBuffer,
		double	sampleNormalized ) const

inlineprotected

◆ CopyIntSampleFromBuffer()

template<typename T >

double AudioDataLib::WaveForm::CopyIntSampleFromBuffer ( const uint8_t * sampleBuffer )

inlineprotected

◆ CopyIntSampleToBuffer()

template<typename T >

void AudioDataLib::WaveForm::CopyIntSampleToBuffer	(	uint8_t *	sampleBuffer,
		double	sampleNormalized ) const

inlineprotected

◆ EvaluateAt()

double WaveForm::EvaluateAt ( double timeSeconds ) const

overridevirtual

Return the amplitude of the wave-form at the given time (in seconds.) Note that this has O(log N) time-complexity, which is usually reasonably, but clearly not as fast as O(1), which can be achieved with raw audio data.

Implements AudioDataLib::Function.

◆ FindTightestSampleBounds()

bool WaveForm::FindTightestSampleBounds	(	double	timeSeconds,
		SampleBounds &	sampleBounds ) const

Find the pair of adjacent samples that bounds the given time. This is an O(log N) operation, where N is the number of samples in the wave-form.

◆ GetEndTime()

double WaveForm::GetEndTime ( ) const

Return the time location of the last sample in this wave-form's list of samples.

◆ GetInterpolationMethod()

InterpolationMethod AudioDataLib::WaveForm::GetInterpolationMethod ( ) const

inline

Return the interpolation method being used to evaluate this wave-form at any particular time within its time-span.

◆ GetMaxAmplitude()

double WaveForm::GetMaxAmplitude ( ) const

Find and return the most positive amplitude found in this wave-form's list of samples.

◆ GetMinAmplitude()

double WaveForm::GetMinAmplitude ( ) const

Find and return the most negative amplitude found in this wave-form's list of samples.

◆ GetNumSamples()

uint64_t WaveForm::GetNumSamples ( ) const

Return the number of samples in this wave-form's list of samples.

◆ GetSampleArray() [1/2]

std::vector< Sample > & AudioDataLib::WaveForm::GetSampleArray ( )

inline

Get read/write access to this wave-form's sample array.

◆ GetSampleArray() [2/2]

const std::vector< Sample > & AudioDataLib::WaveForm::GetSampleArray ( ) const

inline

Get read-only access to this wave-form's sample array.

◆ GetSizeBytes()

uint64_t WaveForm::GetSizeBytes	(	const AudioData::Format &	format,
		bool	allChannels ) const

Return the number of bytes required to represent this wave-form in the given format for 1 or all channels.

Parameters

[in]	format	This is the format of the audio-data you're considering the wave-form being written in.
[in]	allChannels	This is true if you're considering this or a similar wave-form being written to all channels of the audio data.

Returns: This is the number of bytes required to lay down the wave-form in the desired format.

◆ GetStartTime()

double WaveForm::GetStartTime ( ) const

Return the time location of the first sample in this wave-form's list of samples.

◆ GetTimespan()

double WaveForm::GetTimespan ( ) const

Return the difference in time between the first and last sample of this wave-form.

◆ Interpolate()

void WaveForm::Interpolate	(	const SampleBounds &	sampleBounds,
		double	timeSeconds,
		Sample &	interpolatedSample ) const

Evaluate this wave-form at the given time, between the two given samples, using the set interpolation method. This function is typically used internally by the EvaluateAt method. Note that the given time is typically somewhere in the time-span between the two given samples, but this is not a requirement. Also, the two given samples are typically adjacent, but this is also not a requirement.

Parameters

[in]	sampleBounds	This is the pair of sample between which to perform the interpolation.
[in]	timeSeconds	This is the time (in seconds) where the wave-form function is to be evaluated.
[out]	interpolatedSample	This is the sample calculated as an interpolation between the two given samples.

◆ MakeSilence()

void WaveForm::MakeSilence	(	double	samplesPerSecond,
		double	totalSeconds )

Make this wave-form a flat light representing silence for the given time period.

Parameters

[in]	samplesPerSecond	This is the sampling rate, combined with the period, needed to determine how many samples to generate.
[in]	totalSeconds	This is the desired duration (or time period) of silence to generate.

◆ PadWithSilence()

uint64_t WaveForm::PadWithSilence	(	double	desiredDurationSeconds,
		double	sampleRate )

Add some silence to the end of this wave-form.

Parameters

[in]	desiredDurationSeconds	This is the amount of silence to add in seconds.
[in]	sampleRate	This, combined with the duration, indicates how many samples to add.

Returns: The number of samples added is returned.

◆ QuickTrim()

void WaveForm::QuickTrim	(	double	timeSeconds,
		TrimSection	trimSection )

Try to perform a trim that's sometimes faster than that perfomed by the Trim function.

Parameters

[in]	timeSeconds	This is the point at which everything is trimmed before or after.
[in]	trimeSecion	This indicates whether everything is trimmed before or after the given time point.

◆ Renormalize()

bool WaveForm::Renormalize ( )

Find the sample with the maximum amplitude and then divide this out from all the samples.

◆ Scale()

void WaveForm::Scale ( double scale )

Scale all samples by the given scale. This does not change the timing of the samples.

◆ SetInterpolateionMethod()

void AudioDataLib::WaveForm::SetInterpolateionMethod ( InterpolationMethod interpMethod )

inline

Set the interpolation method used to evaluate this wave-form at any particular time within its time-span.

◆ SortSamples()

void WaveForm::SortSamples ( )

Make sure all samples in the wave-form's list of such is sorted chronologically.

◆ SumTogether()

void WaveForm::SumTogether ( const std::list< WaveForm * > & waveFormList )

Make this wave-form the sum of the given list of wave-forms. A minimum amount of silence will be padded to all given wave-forms so that the resulting wave-form is of the length of the largest given wave-form. The average sampling rate of all the wave-forms is used.

◆ Trim()

bool WaveForm::Trim	(	double	startTimeSeconds,
		double	stopTimeSeconds,
		bool	rebaseTime,
		Error &	error )

Trim the beginning and end of this wave-form.

Parameters

[in]	startTimeSeconds	Remove everything up to this time.
[in]	stopTimeSeconds	Remove everything after this time.
[in]	rebaseTime	If true, once the trim has occurred, shift the wave-form back so that it starts at origin.
[out]	error	This will contain detailed error information if false is returned.

Returns: False is returned if an error occurrs; true otherwise.

Friends And Related Symbol Documentation

◆ Index

friend class Index

friend

Member Data Documentation

◆ interpMethod

InterpolationMethod AudioDataLib::WaveForm::interpMethod

protected

◆ sampleArray

std::vector<Sample>* AudioDataLib::WaveForm::sampleArray

protected

The documentation for this class was generated from the following files:

Source/Library/WaveForm.h
Source/Library/WaveForm.cpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ InterpolationMethod

◆ TrimSection

Constructor & Destructor Documentation

◆ WaveForm()

◆ ~WaveForm()

Member Function Documentation

◆ AddSample()

◆ AverageSampleRate()

◆ CalcAverageVolume()

◆ Clamp()

◆ Clear()

◆ ContainsTime()

◆ ConvertFromAudioBuffer()

◆ ConvertToAudioBuffer()

◆ Copy()

◆ CopyFloatSampleFromBuffer()

◆ CopyFloatSampleToBuffer()

◆ CopyIntSampleFromBuffer()

◆ CopyIntSampleToBuffer()

◆ EvaluateAt()

◆ FindTightestSampleBounds()

◆ GetEndTime()

◆ GetInterpolationMethod()

◆ GetMaxAmplitude()

◆ GetMinAmplitude()

◆ GetNumSamples()

◆ GetSampleArray() [1/2]

◆ GetSampleArray() [2/2]

◆ GetSizeBytes()

◆ GetStartTime()

◆ GetTimespan()

◆ Interpolate()

◆ MakeSilence()

◆ PadWithSilence()

◆ QuickTrim()

◆ Renormalize()

◆ Scale()

◆ SetInterpolateionMethod()

◆ SortSamples()

◆ SumTogether()

◆ Trim()

Friends And Related Symbol Documentation

◆ Index

Member Data Documentation

◆ interpMethod

◆ sampleArray