JUCE
Public Member Functions | List of all members
AudioThumbnail Class Reference

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

Inheritance diagram for AudioThumbnail:

Public Member Functions

 AudioThumbnail (int sourceSamplesPerThumbnailSample, AudioFormatManager &formatManagerToUse, AudioThumbnailCache &cacheToUse)
 Creates an audio thumbnail. More...
 
 ~AudioThumbnail () override
 Destructor. More...
 
void clear () override
 Clears and resets the thumbnail. More...
 
bool setSource (InputSource *newSource) override
 Specifies the file or stream that contains the audio file. More...
 
void setReader (AudioFormatReader *newReader, int64 hashCode) override
 Gives the thumbnail an AudioFormatReader to use directly. More...
 
void reset (int numChannels, double sampleRate, int64 totalSamplesInSource=0) override
 Resets the thumbnail, ready for adding data with the specified format. More...
 
void addBlock (int64 sampleNumberInSource, const AudioBuffer< float > &newData, int startOffsetInBuffer, int numSamples) override
 Adds a block of level data to the thumbnail. More...
 
bool loadFrom (InputStream &input) override
 Reloads the low res thumbnail data from an input stream. More...
 
void saveTo (OutputStream &output) const override
 Saves the low res thumbnail data to an output stream. More...
 
int getNumChannels () const noexcept override
 Returns the number of channels in the file. More...
 
double getTotalLength () const noexcept override
 Returns the length of the audio file, in seconds. 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...
 
bool isFullyLoaded () const noexcept override
 Returns true if the low res preview is fully generated. More...
 
double getProportionComplete () const noexcept
 Returns a value between 0 and 1 to indicate the progress towards loading the entire file. More...
 
int64 getNumSamplesFinished () const noexcept override
 Returns the number of samples that have been set in the thumbnail. More...
 
float getApproximatePeak () const override
 Returns the highest level 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...
 
int64 getHashCode () const override
 Returns the hash code that was set by setSource() or setReader(). More...
 
- Public Member Functions inherited from AudioThumbnailBase
 AudioThumbnailBase ()=default
 
 ~AudioThumbnailBase () override=default
 
- Public Member Functions inherited from ChangeBroadcaster
 ChangeBroadcaster () noexcept
 Creates an ChangeBroadcaster. More...
 
virtual ~ChangeBroadcaster ()
 Destructor. More...
 
void addChangeListener (ChangeListener *listener)
 Registers a listener to receive change callbacks from this broadcaster. More...
 
void removeChangeListener (ChangeListener *listener)
 Unregisters a listener from the list. More...
 
void removeAllChangeListeners ()
 Removes all listeners from the list. 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 dispatchPendingMessages ()
 If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately. More...
 
- Public Member Functions inherited from AudioFormatWriter::ThreadedWriter::IncomingDataReceiver
 IncomingDataReceiver ()=default
 
virtual ~IncomingDataReceiver ()=default
 

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

Constructor & Destructor Documentation

◆ AudioThumbnail()

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

Creates an audio thumbnail.

Parameters
sourceSamplesPerThumbnailSamplewhen 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)
formatManagerToUsethe audio format manager that is used to open the file
cacheToUsean 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()

AudioThumbnail::~AudioThumbnail ( )
override

Destructor.

Member Function Documentation

◆ clear()

void AudioThumbnail::clear ( )
overridevirtual

Clears and resets the thumbnail.

Implements AudioThumbnailBase.

◆ setSource()

bool AudioThumbnail::setSource ( InputSource newSource)
overridevirtual

Specifies the file or stream that contains the audio file.

For a file, just call

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 AudioThumbnailBase.

◆ setReader()

void 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 AudioThumbnailBase.

◆ reset()

void 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 AudioFormatWriter::ThreadedWriter::IncomingDataReceiver.

◆ addBlock()

void 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 AudioFormatWriter::ThreadedWriter::IncomingDataReceiver.

◆ loadFrom()

bool 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 AudioThumbnailBase.

◆ saveTo()

void 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 AudioThumbnailBase.

◆ getNumChannels()

int AudioThumbnail::getNumChannels ( ) const
overridevirtualnoexcept

Returns the number of channels in the file.

Implements AudioThumbnailBase.

◆ getTotalLength()

double AudioThumbnail::getTotalLength ( ) const
overridevirtualnoexcept

Returns the length of the audio file, in seconds.

Implements AudioThumbnailBase.

◆ drawChannel()

void 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 AudioThumbnailBase.

◆ drawChannels()

void 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 AudioThumbnailBase.

◆ isFullyLoaded()

bool AudioThumbnail::isFullyLoaded ( ) const
overridevirtualnoexcept

Returns true if the low res preview is fully generated.

Implements AudioThumbnailBase.

◆ getProportionComplete()

double AudioThumbnail::getProportionComplete ( ) const
noexcept

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

◆ getNumSamplesFinished()

int64 AudioThumbnail::getNumSamplesFinished ( ) const
overridevirtualnoexcept

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

Implements AudioThumbnailBase.

◆ getApproximatePeak()

float 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 AudioThumbnailBase.

◆ getApproximateMinMax()

void 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 AudioThumbnailBase.

◆ getHashCode()

int64 AudioThumbnail::getHashCode ( ) const
overridevirtual

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

Implements AudioThumbnailBase.


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