juce/source/src/audio/audio_file_formats/juce_AudioThumbnail.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_AUDIOTHUMBNAIL_JUCEHEADER__
  27 #define __JUCE_AUDIOTHUMBNAIL_JUCEHEADER__
  28
  29 #include "../../threads/juce_TimeSliceThread.h"
  30 #include "../../io/streams/juce_InputSource.h"
  31 #include "../../io/streams/juce_OutputStream.h"
  32 #include "../../events/juce_ChangeBroadcaster.h"
  33 #include "../../events/juce_Timer.h"
  34 #include "../../gui/graphics/contexts/juce_Graphics.h"
  35 #include "juce_AudioFormatReader.h"
  36 #include "juce_AudioFormatManager.h"
  37
  38 class AudioThumbnailCache;
  39
  40
  41 //==============================================================================
  42 /**
  43     Makes it easy to quickly draw scaled views of the waveform shape of an
  44     audio file.
  45
  46     To use this class, just create an AudioThumbNail class for the file you want
  47     to draw, call setSource to tell it which file or resource to use, then call
  48     drawChannel() to draw it.
  49
  50     The class will asynchronously scan the wavefile to create its scaled-down view,
  51     so you should make your UI repaint itself as this data comes in. To do this, the
  52     AudioThumbnail is a ChangeBroadcaster, and will broadcast a message when its
  53     listeners should repaint themselves.
  54
  55     The thumbnail stores an internal low-res version of the wave data, and this can
  56     be loaded and saved to avoid having to scan the file again.
  57
  58     @see AudioThumbnailCache
  59 */
  60 class JUCE_API  AudioThumbnail    : public ChangeBroadcaster
  61 {
  62 public:
  63     //==============================================================================
  64     /** Creates an audio thumbnail.
  65
  66         @param sourceSamplesPerThumbnailSample  when creating a stored, low-res version
  67                         of the audio data, this is the scale at which it should be done. (This
  68                         number is the number of original samples that will be averaged for each
  69                         low-res sample)
  70         @param formatManagerToUse   the audio format manager that is used to open the file
  71         @param cacheToUse   an instance of an AudioThumbnailCache - this provides a background
  72                             thread and storage that is used to by the thumbnail, and the cache
  73                             object can be shared between multiple thumbnails
  74     */
  75     AudioThumbnail (int sourceSamplesPerThumbnailSample,
  76                     AudioFormatManager& formatManagerToUse,
  77                     AudioThumbnailCache& cacheToUse);
  78
  79     /** Destructor. */
  80     ~AudioThumbnail();
  81
  82     //==============================================================================
  83     /** Clears and resets the thumbnail. */
  84     void clear();
  85
  86     /** Specifies the file or stream that contains the audio file.
  87
  88         For a file, just call
  89         @code
  90         setSource (new FileInputSource (file))
  91         @endcode
  92
  93         You can pass a zero in here to clear the thumbnail.
  94         The source that is passed in will be deleted by this object when it is no longer needed.
  95         @returns true if the source could be opened as a valid audio file, false if this failed for
  96         some reason.
  97     */
  98     bool setSource (InputSource* newSource);
  99
 100     /** Gives the thumbnail an AudioFormatReader to use directly.
 101         This will start parsing the audio in a background thread (unless the hash code
 102         can be looked-up successfully in the thumbnail cache). Note that the reader
 103         object will be held by the thumbnail and deleted later when no longer needed.
 104         The thumbnail will actually keep hold of this reader until you clear the thumbnail
 105         or change the input source, so the file will be held open for all this time. If
 106         you don't want the thumbnail to keep a file handle open continuously, you
 107         should use the setSource() method instead, which will only open the file when
 108         it needs to.
 109     */
 110     void setReader (AudioFormatReader* newReader, int64 hashCode);
 111
 112     /** Resets the thumbnail, ready for adding data with the specified format.
 113         If you're going to generate a thumbnail yourself, call this before using addBlock()
 114         to add the data.
 115     */
 116     void reset (int numChannels, double sampleRate, int64 totalSamplesInSource = 0);
 117
 118     /** Adds a block of level data to the thumbnail.
 119         Call reset() before using this, to tell the thumbnail about the data format.
 120     */
 121     void addBlock (int64 sampleNumberInSource, const AudioSampleBuffer& newData,
 122                    int startOffsetInBuffer, int numSamples);
 123
 124     //==============================================================================
 125     /** Reloads the low res thumbnail data from an input stream.
 126
 127         This is not an audio file stream! It takes a stream of thumbnail data that would
 128         previously have been created by the saveTo() method.
 129         @see saveTo
 130     */
 131     void loadFrom (InputStream& input);
 132
 133     /** Saves the low res thumbnail data to an output stream.
 134
 135         The data that is written can later be reloaded using loadFrom().
 136         @see loadFrom
 137     */
 138     void saveTo (OutputStream& output) const;
 139
 140     //==============================================================================
 141     /** Returns the number of channels in the file. */
 142     int getNumChannels() const noexcept;
 143
 144     /** Returns the length of the audio file, in seconds. */
 145     double getTotalLength() const noexcept;
 146
 147     /** Draws the waveform for a channel.
 148
 149         The waveform will be drawn within  the specified rectangle, where startTime
 150         and endTime specify the times within the audio file that should be positioned
 151         at the left and right edges of the rectangle.
 152
 153         The waveform will be scaled vertically so that a full-volume sample will fill
 154         the rectangle vertically, but you can also specify an extra vertical scale factor
 155         with the verticalZoomFactor parameter.
 156     */
 157     void drawChannel (Graphics& g,
 158                       const Rectangle<int>& area,
 159                       double startTimeSeconds,
 160                       double endTimeSeconds,
 161                       int channelNum,
 162                       float verticalZoomFactor);
 163
 164     /** Draws the waveforms for all channels in the thumbnail.
 165
 166         This will call drawChannel() to render each of the thumbnail's channels, stacked
 167         above each other within the specified area.
 168
 169         @see drawChannel
 170     */
 171     void drawChannels (Graphics& g,
 172                        const Rectangle<int>& area,
 173                        double startTimeSeconds,
 174                        double endTimeSeconds,
 175                        float verticalZoomFactor);
 176
 177     /** Returns true if the low res preview is fully generated. */
 178     bool isFullyLoaded() const noexcept;
 179
 180     /** Returns the number of samples that have been set in the thumbnail. */
 181     int64 getNumSamplesFinished() const noexcept;
 182
 183     /** Returns the highest level in the thumbnail.
 184         Note that because the thumb only stores low-resolution data, this isn't
 185         an accurate representation of the highest value, it's only a rough approximation.
 186     */
 187     float getApproximatePeak() const;
 188
 189     /** Reads the approximate min and max levels from a section of the thumbnail.
 190         The lowest and highest samples are returned in minValue and maxValue, but obviously
 191         because the thumb only stores low-resolution data, these numbers will only be a rough
 192         approximation of the true values.
 193     */
 194     void getApproximateMinMax (double startTime, double endTime, int channelIndex,
 195                                float& minValue, float& maxValue) const noexcept;
 196
 197     /** Returns the hash code that was set by setSource() or setReader(). */
 198     int64 getHashCode() const;
 199
 200    #ifndef DOXYGEN
 201     class LevelDataSource;  // (this is only public to avoid a VC6 bug)
 202    #endif
 203
 204 private:
 205     //==============================================================================
 206     AudioFormatManager& formatManagerToUse;
 207     AudioThumbnailCache& cache;
 208
 209     struct MinMaxValue;
 210     class ThumbData;
 211     class CachedWindow;
 212
 213     friend class LevelDataSource;
 214     friend class ScopedPointer<LevelDataSource>;
 215     friend class ThumbData;
 216     friend class OwnedArray<ThumbData>;
 217     friend class CachedWindow;
 218     friend class ScopedPointer<CachedWindow>;
 219
 220     ScopedPointer<LevelDataSource> source;
 221     ScopedPointer<CachedWindow> window;
 222     OwnedArray<ThumbData> channels;
 223
 224     int32 samplesPerThumbSample;
 225     int64 totalSamples, numSamplesFinished;
 226     int32 numChannels;
 227     double sampleRate;
 228     CriticalSection lock;
 229
 230     void clearChannelData();
 231     bool setDataSource (LevelDataSource* newSource);
 232     void setLevels (const MinMaxValue* const* values, int thumbIndex, int numChans, int numValues);
 233     void createChannels (int length);
 234
 235     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (AudioThumbnail);
 236 };
 237
 238
 239 #endif   // __JUCE_AUDIOTHUMBNAIL_JUCEHEADER__