Loading...
Searching...
No Matches
juce::AudioThumbnail Class Reference

## 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

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

- juce_audio_utils/gui/juce_AudioThumbnail.h

Inheritance diagram for juce::AudioThumbnail:

## Public Member Functions

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

## Constructors and Destructors

## 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 Functions

## clear()

void juce::AudioThumbnail::clear | ( |  | ) |

override virtual

Clears and resets the thumbnail.

Implements juce::AudioThumbnailBase.

## setSource() [1/3]

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

override virtual

Specifies the file or stream that contains the audio file.

For a file, just call

setSource (new FileInputSource (file))
juce::AudioThumbnail::setSource
bool setSource(InputSource *newSource) override
Specifies the file or stream that contains the audio file.
juce::FileInputSource
A type of InputSource that represents a normal file.
Definition juce_FileInputSource.h:47

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.

## setReader()

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

override virtual

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() [2/3]

void juce::AudioThumbnail::setSource | ( | const AudioBuffer< float > * | newSource,
|  | double | sampleRate,
|  | int64 | hashCode )

Sets an AudioBuffer as the source for the thumbnail.

The buffer contents aren't copied and you must ensure that the lifetime of the buffer is valid for as long as the AudioThumbnail uses it as its source. Calling this function will start reading the audio in a background thread (unless the hash code can be looked-up successfully in the thumbnail cache).

## setSource() [3/3]

void juce::AudioThumbnail::setSource | ( | const AudioBuffer< int > * | newSource,
|  | double | sampleRate,
|  | int64 | hashCode )

Same as the other setSource() overload except for int data.

## reset()

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

override virtual

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.

## addBlock()

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

override virtual

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.

## loadFrom()

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

override virtual

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.

## saveTo()

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

override virtual

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.

## getNumChannels()

int juce::AudioThumbnail::getNumChannels | ( |  | ) | const

override virtual noexcept

Returns the number of channels in the file.

Implements juce::AudioThumbnailBase.

## getTotalLength()

double juce::AudioThumbnail::getTotalLength | ( |  | ) | const

override virtual noexcept

Returns the length of the audio file, in seconds.

Implements juce::AudioThumbnailBase.

References getTotalLength().

Referenced by getTotalLength().

## drawChannel()

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

override virtual

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.

References drawChannel().

Referenced by drawChannel().

## drawChannels()

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

override virtual

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.

References drawChannels().

Referenced by drawChannels().

## isFullyLoaded()

bool juce::AudioThumbnail::isFullyLoaded | ( |  | ) | const

override virtual noexcept

Returns true if the low res preview is fully generated.

Implements juce::AudioThumbnailBase.

References isFullyLoaded().

Referenced by isFullyLoaded().

## getProportionComplete()

double juce::AudioThumbnail::getProportionComplete | ( |  | ) | const

noexcept

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

References getProportionComplete().

Referenced by getProportionComplete().

## getNumSamplesFinished()

int64 juce::AudioThumbnail::getNumSamplesFinished | ( |  | ) | const

override virtual noexcept

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

Implements juce::AudioThumbnailBase.

References getNumSamplesFinished().

Referenced by getNumSamplesFinished().

## getApproximatePeak()

float juce::AudioThumbnail::getApproximatePeak | ( |  | ) | const

override virtual

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.

References getApproximatePeak().

Referenced by getApproximatePeak().

## getApproximateMinMax()

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

override virtual noexcept

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.

References getApproximateMinMax().

Referenced by getApproximateMinMax().

## getHashCode()

int64 juce::AudioThumbnail::getHashCode | ( |  | ) | const

override virtual

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

Implements juce::AudioThumbnailBase.

References getHashCode().

Referenced by getHashCode().

### Purchase

Get JUCE

### Discover

What's New in JUCE Features

### Learn

Documentaion Tutorials Made with JUCE Resources

### Support

JUCE Forum Newsletter Archive

### About

Contact Us JUCE Legal JUCE Licensing FAQ

### Events

Audio Developer Conference
© Raw Material Software Limited