Makes it easy to quickly draw scaled views of the waveform shape of an audio file. More...

#include <juce_AudioThumbnail.h>

Inheritance diagram for juce::AudioThumbnail:

[legend]

Collaboration diagram for juce::AudioThumbnail:

[legend]

Public Member Functions
	AudioThumbnail (int sourceSamplesPerThumbnailSample, AudioFormatManager &formatManagerToUse, AudioThumbnailCache &cacheToUse)
	Creates an audio thumbnail. More...

	~AudioThumbnail () override
	Destructor. More...

void	addBlock (int64 sampleNumberInSource, const AudioBuffer< float > &newData, int startOffsetInBuffer, int numSamples) override
	Adds a block of level data to the thumbnail. More...

void	addChangeListener (ChangeListener *listener)
	Registers a listener to receive change callbacks from this broadcaster. More...

void	clear () override
	Clears and resets the thumbnail. More...

void	dispatchPendingMessages ()
	If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately. More...

void	drawChannel (Graphics &g, const Rectangle< int > &area, double startTimeSeconds, double endTimeSeconds, int channelNum, float verticalZoomFactor) override
	Draws the waveform for a channel. More...

void	drawChannels (Graphics &g, const Rectangle< int > &area, double startTimeSeconds, double endTimeSeconds, float verticalZoomFactor) override
	Draws the waveforms for all channels in the thumbnail. More...

void	getApproximateMinMax (double startTime, double endTime, int channelIndex, float &minValue, float &maxValue) const noexcept override
	Reads the approximate min and max levels from a section of the thumbnail. More...

float	getApproximatePeak () const override
	Returns the highest level in the thumbnail. More...

int64	getHashCode () const override
	Returns the hash code that was set by setSource() or setReader(). More...

int	getNumChannels () const noexcept override
	Returns the number of channels in the file. More...

int64	getNumSamplesFinished () const noexcept override
	Returns the number of samples that have been set in the thumbnail. More...

double	getProportionComplete () const noexcept
	Returns a value between 0 and 1 to indicate the progress towards loading the entire file. More...

double	getTotalLength () const noexcept override
	Returns the length of the audio file, in seconds. More...

bool	isFullyLoaded () const noexcept override
	Returns true if the low res preview is fully generated. More...

bool	loadFrom (InputStream &input) override
	Reloads the low res thumbnail data from an input stream. More...

void	removeAllChangeListeners ()
	Removes all listeners from the list. More...

void	removeChangeListener (ChangeListener *listener)
	Unregisters a listener from the list. More...

void	reset (int numChannels, double sampleRate, int64 totalSamplesInSource=0) override
	Resets the thumbnail, ready for adding data with the specified format. More...

void	saveTo (OutputStream &output) const override
	Saves the low res thumbnail data to an output stream. More...

void	sendChangeMessage ()
	Causes an asynchronous change message to be sent to all the registered listeners. More...

void	sendSynchronousChangeMessage ()
	Sends a synchronous change message to all the registered listeners. More...

void	setReader (AudioFormatReader *newReader, int64 hashCode) override
	Gives the thumbnail an AudioFormatReader to use directly. More...

bool	setSource (InputSource *newSource) override
	Specifies the file or stream that contains the audio file. More...

Private Member Functions
void	callListeners ()

void	clearChannelData ()

void	createChannels (int length)

bool	setDataSource (LevelDataSource *newSource)

void	setLevels (const MinMaxValue const values, int thumbIndex, int numChans, int numValues)

Private Attributes
std::atomic< bool >	anyListeners { false }

ChangeBroadcasterCallback	broadcastCallback

AudioThumbnailCache &	cache

ListenerList< ChangeListener >	changeListeners

OwnedArray< ThumbData >	channels

AudioFormatManager &	formatManagerToUse

CriticalSection	lock

int32	numChannels = 0

int64	numSamplesFinished = 0

double	sampleRate = 0

int32	samplesPerThumbSample = 0

std::unique_ptr< LevelDataSource >	source

int64	totalSamples { 0 }

std::unique_ptr< CachedWindow >	window

Detailed Description

Makes it easy to quickly draw scaled views of the waveform shape of an audio file.

To use this class, just create an AudioThumbnail class for the file you want to draw, call setSource to tell it which file or resource to use, then call drawChannel() to draw it.

The class will asynchronously scan the wavefile to create its scaled-down view, so you should make your UI repaint itself as this data comes in. To do this, the AudioThumbnail is a ChangeBroadcaster, and will broadcast a message when its listeners should repaint themselves.

The thumbnail stores an internal low-res version of the wave data, and this can be loaded and saved to avoid having to scan the file again.

See also: AudioThumbnailCache, AudioThumbnailBase

@tags{Audio}

Constructor & Destructor Documentation

◆ AudioThumbnail()

juce::AudioThumbnail::AudioThumbnail	(	int	sourceSamplesPerThumbnailSample,
		AudioFormatManager &	formatManagerToUse,
		AudioThumbnailCache &	cacheToUse
	)

Creates an audio thumbnail.

Parameters

sourceSamplesPerThumbnailSample	when creating a stored, low-res version of the audio data, this is the scale at which it should be done. (This number is the number of original samples that will be averaged for each low-res sample)
formatManagerToUse	the audio format manager that is used to open the file
cacheToUse	an instance of an AudioThumbnailCache - this provides a background thread and storage that is used to by the thumbnail, and the cache object can be shared between multiple thumbnails

◆ ~AudioThumbnail()

juce::AudioThumbnail::~AudioThumbnail ( )

override

Destructor.

Member Function Documentation

◆ addBlock()

void juce::AudioThumbnail::addBlock	(	int64	sampleNumberInSource,
		const AudioBuffer< float > &	newData,
		int	startOffsetInBuffer,
		int	numSamples
	)

overridevirtual

Adds a block of level data to the thumbnail.

Call reset() before using this, to tell the thumbnail about the data format.

Implements juce::AudioFormatWriter::ThreadedWriter::IncomingDataReceiver.

◆ addChangeListener()

void juce::ChangeBroadcaster::addChangeListener ( ChangeListener * listener )

inherited

Registers a listener to receive change callbacks from this broadcaster.

Trying to add a listener that's already on the list will have no effect.

◆ callListeners()

void juce::ChangeBroadcaster::callListeners ( )

privateinherited

◆ clear()

void juce::AudioThumbnail::clear ( )

overridevirtual

Clears and resets the thumbnail.

Implements juce::AudioThumbnailBase.

◆ clearChannelData()

void juce::AudioThumbnail::clearChannelData ( )

private

◆ createChannels()

void juce::AudioThumbnail::createChannels ( int length )

private

◆ dispatchPendingMessages()

void juce::ChangeBroadcaster::dispatchPendingMessages ( )

inherited

If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately.

For thread-safety reasons, you must only call this method on the main message thread.

◆ drawChannel()

void juce::AudioThumbnail::drawChannel	(	Graphics &	g,
		const Rectangle< int > &	area,
		double	startTimeSeconds,
		double	endTimeSeconds,
		int	channelNum,
		float	verticalZoomFactor
	)

overridevirtual

Draws the waveform for a channel.

The waveform will be drawn within the specified rectangle, where startTime and endTime specify the times within the audio file that should be positioned at the left and right edges of the rectangle.

The waveform will be scaled vertically so that a full-volume sample will fill the rectangle vertically, but you can also specify an extra vertical scale factor with the verticalZoomFactor parameter.

Implements juce::AudioThumbnailBase.

◆ drawChannels()

void juce::AudioThumbnail::drawChannels	(	Graphics &	g,
		const Rectangle< int > &	area,
		double	startTimeSeconds,
		double	endTimeSeconds,
		float	verticalZoomFactor
	)

overridevirtual

Draws the waveforms for all channels in the thumbnail.

This will call drawChannel() to render each of the thumbnail's channels, stacked above each other within the specified area.

See also: drawChannel

Implements juce::AudioThumbnailBase.

◆ getApproximateMinMax()

void juce::AudioThumbnail::getApproximateMinMax	(	double	startTime,
		double	endTime,
		int	channelIndex,
		float &	minValue,
		float &	maxValue
	)		const

overridevirtualnoexcept

Reads the approximate min and max levels from a section of the thumbnail.

The lowest and highest samples are returned in minValue and maxValue, but obviously because the thumb only stores low-resolution data, these numbers will only be a rough approximation of the true values.

Implements juce::AudioThumbnailBase.

◆ getApproximatePeak()

float juce::AudioThumbnail::getApproximatePeak ( ) const

overridevirtual

Returns the highest level in the thumbnail.

Note that because the thumb only stores low-resolution data, this isn't an accurate representation of the highest value, it's only a rough approximation.

Implements juce::AudioThumbnailBase.

◆ getHashCode()

int64 juce::AudioThumbnail::getHashCode ( ) const

overridevirtual

Returns the hash code that was set by setSource() or setReader().

Implements juce::AudioThumbnailBase.

◆ getNumChannels()

int juce::AudioThumbnail::getNumChannels ( ) const

overridevirtualnoexcept

Returns the number of channels in the file.

Implements juce::AudioThumbnailBase.

◆ getNumSamplesFinished()

int64 juce::AudioThumbnail::getNumSamplesFinished ( ) const

overridevirtualnoexcept

Returns the number of samples that have been set in the thumbnail.

Implements juce::AudioThumbnailBase.

◆ getProportionComplete()

double juce::AudioThumbnail::getProportionComplete ( ) const

noexcept

Returns a value between 0 and 1 to indicate the progress towards loading the entire file.

◆ getTotalLength()

double juce::AudioThumbnail::getTotalLength ( ) const

overridevirtualnoexcept

Returns the length of the audio file, in seconds.

Implements juce::AudioThumbnailBase.

◆ isFullyLoaded()

bool juce::AudioThumbnail::isFullyLoaded ( ) const

overridevirtualnoexcept

Returns true if the low res preview is fully generated.

Implements juce::AudioThumbnailBase.

◆ loadFrom()

bool juce::AudioThumbnail::loadFrom ( InputStream & input )

overridevirtual

Reloads the low res thumbnail data from an input stream.

This is not an audio file stream! It takes a stream of thumbnail data that would previously have been created by the saveTo() method.

See also: saveTo

Implements juce::AudioThumbnailBase.

◆ removeAllChangeListeners()

void juce::ChangeBroadcaster::removeAllChangeListeners ( )

inherited

Removes all listeners from the list.

◆ removeChangeListener()

void juce::ChangeBroadcaster::removeChangeListener ( ChangeListener * listener )

inherited

Unregisters a listener from the list.

If the listener isn't on the list, this won't have any effect.

◆ reset()

void juce::AudioThumbnail::reset	(	int	numChannels,
		double	sampleRate,
		int64	totalSamplesInSource = `0`
	)

overridevirtual

Resets the thumbnail, ready for adding data with the specified format.

If you're going to generate a thumbnail yourself, call this before using addBlock() to add the data.

Implements juce::AudioFormatWriter::ThreadedWriter::IncomingDataReceiver.

◆ saveTo()

void juce::AudioThumbnail::saveTo ( OutputStream & output ) const

overridevirtual

Saves the low res thumbnail data to an output stream.

The data that is written can later be reloaded using loadFrom().

See also: loadFrom

Implements juce::AudioThumbnailBase.

◆ sendChangeMessage()

void juce::ChangeBroadcaster::sendChangeMessage ( )

inherited

Causes an asynchronous change message to be sent to all the registered listeners.

The message will be delivered asynchronously by the main message thread, so this method will return immediately. To call the listeners synchronously use sendSynchronousChangeMessage().

Referenced by juce::SelectedItemSet< SelectableItemType >::changed().

◆ sendSynchronousChangeMessage()

void juce::ChangeBroadcaster::sendSynchronousChangeMessage ( )

inherited

Sends a synchronous change message to all the registered listeners.

This will immediately call all the listeners that are registered. For thread-safety reasons, you must only call this method on the main message thread.

See also: dispatchPendingMessages

Referenced by juce::SelectedItemSet< SelectableItemType >::changed().

◆ setDataSource()

bool juce::AudioThumbnail::setDataSource ( LevelDataSource * newSource )

private

◆ setLevels()

void juce::AudioThumbnail::setLevels	(	const MinMaxValue const	values,
		int	thumbIndex,
		int	numChans,
		int	numValues
	)

private

◆ setReader()

void juce::AudioThumbnail::setReader	(	AudioFormatReader *	newReader,
		int64	hashCode
	)

overridevirtual

Gives the thumbnail an AudioFormatReader to use directly.

This will start parsing the audio in a background thread (unless the hash code can be looked-up successfully in the thumbnail cache). Note that the reader object will be held by the thumbnail and deleted later when no longer needed. The thumbnail will actually keep hold of this reader until you clear the thumbnail or change the input source, so the file will be held open for all this time. If you don't want the thumbnail to keep a file handle open continuously, you should use the setSource() method instead, which will only open the file when it needs to.

Implements juce::AudioThumbnailBase.

◆ setSource()

bool juce::AudioThumbnail::setSource ( InputSource * newSource )

overridevirtual

Specifies the file or stream that contains the audio file.

For a file, just call

setSource (new FileInputSource (file))

You can pass a nullptr in here to clear the thumbnail. The source that is passed in will be deleted by this object when it is no longer needed.

Returns: true if the source could be opened as a valid audio file, false if this failed for some reason.

Implements juce::AudioThumbnailBase.

Member Data Documentation

◆ anyListeners

std::atomic<bool> juce::ChangeBroadcaster::anyListeners { false }

privateinherited

◆ broadcastCallback

ChangeBroadcasterCallback juce::ChangeBroadcaster::broadcastCallback

privateinherited

◆ cache

AudioThumbnailCache& juce::AudioThumbnail::cache

private

◆ changeListeners

ListenerList<ChangeListener> juce::ChangeBroadcaster::changeListeners

privateinherited

◆ channels

OwnedArray<ThumbData> juce::AudioThumbnail::channels

private

◆ formatManagerToUse

AudioFormatManager& juce::AudioThumbnail::formatManagerToUse

private

◆ lock

CriticalSection juce::AudioThumbnail::lock

private

◆ numChannels

int32 juce::AudioThumbnail::numChannels = 0

private

◆ numSamplesFinished

int64 juce::AudioThumbnail::numSamplesFinished = 0

private

◆ sampleRate

double juce::AudioThumbnail::sampleRate = 0

private

◆ samplesPerThumbSample

int32 juce::AudioThumbnail::samplesPerThumbSample = 0

private

◆ source

std::unique_ptr<LevelDataSource> juce::AudioThumbnail::source

private

◆ totalSamples

int64 juce::AudioThumbnail::totalSamples { 0 }

private

◆ window

std::unique_ptr<CachedWindow> juce::AudioThumbnail::window

private

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

juce_AudioThumbnail.h

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ AudioThumbnail()

◆ ~AudioThumbnail()

Member Function Documentation

◆ addBlock()

◆ addChangeListener()

◆ callListeners()

◆ clear()

◆ clearChannelData()

◆ createChannels()

◆ dispatchPendingMessages()

◆ drawChannel()

◆ drawChannels()

◆ getApproximateMinMax()

◆ getApproximatePeak()

◆ getHashCode()

◆ getNumChannels()

◆ getNumSamplesFinished()

◆ getProportionComplete()

◆ getTotalLength()

◆ isFullyLoaded()

◆ loadFrom()

◆ removeAllChangeListeners()

◆ removeChangeListener()

◆ reset()

◆ saveTo()

◆ sendChangeMessage()

◆ sendSynchronousChangeMessage()

◆ setDataSource()

◆ setLevels()

◆ setReader()

◆ setSource()

Member Data Documentation

◆ anyListeners

◆ broadcastCallback

◆ cache

◆ changeListeners

◆ channels

◆ formatManagerToUse

◆ lock

◆ numChannels

◆ numSamplesFinished

◆ sampleRate

◆ samplesPerThumbSample

◆ source

◆ totalSamples

◆ window