Add TAL-Reverb-II plugin to test
[juce-lv2.git] / juce / source / src / audio / audio_file_formats / juce_AudioFormatReader.h
blob0636cf13e41bc13b9fadb5d4e0e4b2d6373f4d73
1 /*
2 ==============================================================================
4 This file is part of the JUCE library - "Jules' Utility Class Extensions"
5 Copyright 2004-11 by Raw Material Software Ltd.
7 ------------------------------------------------------------------------------
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.
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.
18 ------------------------------------------------------------------------------
20 To release a closed-source product which uses JUCE, commercial licenses are
21 available: visit www.rawmaterialsoftware.com/juce for more information.
23 ==============================================================================
26 #ifndef __JUCE_AUDIOFORMATREADER_JUCEHEADER__
27 #define __JUCE_AUDIOFORMATREADER_JUCEHEADER__
29 #include "../../io/streams/juce_InputStream.h"
30 #include "../../text/juce_StringPairArray.h"
31 #include "../dsp/juce_AudioDataConverters.h"
32 class AudioFormat;
35 //==============================================================================
36 /**
37 Reads samples from an audio file stream.
39 A subclass that reads a specific type of audio format will be created by
40 an AudioFormat object.
42 @see AudioFormat, AudioFormatWriter
44 class JUCE_API AudioFormatReader
46 protected:
47 //==============================================================================
48 /** Creates an AudioFormatReader object.
50 @param sourceStream the stream to read from - this will be deleted
51 by this object when it is no longer needed. (Some
52 specialised readers might not use this parameter and
53 can leave it as 0).
54 @param formatName the description that will be returned by the getFormatName()
55 method
57 AudioFormatReader (InputStream* sourceStream,
58 const String& formatName);
60 public:
61 /** Destructor. */
62 virtual ~AudioFormatReader();
64 //==============================================================================
65 /** Returns a description of what type of format this is.
67 E.g. "AIFF"
69 const String& getFormatName() const noexcept { return formatName; }
71 //==============================================================================
72 /** Reads samples from the stream.
74 @param destSamples an array of buffers into which the sample data for each
75 channel will be written.
76 If the format is fixed-point, each channel will be written
77 as an array of 32-bit signed integers using the full
78 range -0x80000000 to 0x7fffffff, regardless of the source's
79 bit-depth. If it is a floating-point format, you should cast
80 the resulting array to a (float**) to get the values (in the
81 range -1.0 to 1.0 or beyond)
82 If the format is stereo, then destSamples[0] is the left channel
83 data, and destSamples[1] is the right channel.
84 The numDestChannels parameter indicates how many pointers this array
85 contains, but some of these pointers can be null if you don't want to
86 read data for some of the channels
87 @param numDestChannels the number of array elements in the destChannels array
88 @param startSampleInSource the position in the audio file or stream at which the samples
89 should be read, as a number of samples from the start of the
90 stream. It's ok for this to be beyond the start or end of the
91 available data - any samples that are out-of-range will be returned
92 as zeros.
93 @param numSamplesToRead the number of samples to read. If this is greater than the number
94 of samples that the file or stream contains. the result will be padded
95 with zeros
96 @param fillLeftoverChannelsWithCopies if true, this indicates that if there's no source data available
97 for some of the channels that you pass in, then they should be filled with
98 copies of valid source channels.
99 E.g. if you're reading a mono file and you pass 2 channels to this method, then
100 if fillLeftoverChannelsWithCopies is true, both destination channels will be filled
101 with the same data from the file's single channel. If fillLeftoverChannelsWithCopies
102 was false, then only the first channel would be filled with the file's contents, and
103 the second would be cleared. If there are many channels, e.g. you try to read 4 channels
104 from a stereo file, then the last 3 would all end up with copies of the same data.
105 @returns true if the operation succeeded, false if there was an error. Note
106 that reading sections of data beyond the extent of the stream isn't an
107 error - the reader should just return zeros for these regions
108 @see readMaxLevels
110 bool read (int* const* destSamples,
111 int numDestChannels,
112 int64 startSampleInSource,
113 int numSamplesToRead,
114 bool fillLeftoverChannelsWithCopies);
116 /** Finds the highest and lowest sample levels from a section of the audio stream.
118 This will read a block of samples from the stream, and measure the
119 highest and lowest sample levels from the channels in that section, returning
120 these as normalised floating-point levels.
122 @param startSample the offset into the audio stream to start reading from. It's
123 ok for this to be beyond the start or end of the stream.
124 @param numSamples how many samples to read
125 @param lowestLeft on return, this is the lowest absolute sample from the left channel
126 @param highestLeft on return, this is the highest absolute sample from the left channel
127 @param lowestRight on return, this is the lowest absolute sample from the right
128 channel (if there is one)
129 @param highestRight on return, this is the highest absolute sample from the right
130 channel (if there is one)
131 @see read
133 virtual void readMaxLevels (int64 startSample,
134 int64 numSamples,
135 float& lowestLeft,
136 float& highestLeft,
137 float& lowestRight,
138 float& highestRight);
140 /** Scans the source looking for a sample whose magnitude is in a specified range.
142 This will read from the source, either forwards or backwards between two sample
143 positions, until it finds a sample whose magnitude lies between two specified levels.
145 If it finds a suitable sample, it returns its position; if not, it will return -1.
147 There's also a minimumConsecutiveSamples setting to help avoid spikes or zero-crossing
148 points when you're searching for a continuous range of samples
150 @param startSample the first sample to look at
151 @param numSamplesToSearch the number of samples to scan. If this value is negative,
152 the search will go backwards
153 @param magnitudeRangeMinimum the lowest magnitude (inclusive) that is considered a hit, from 0 to 1.0
154 @param magnitudeRangeMaximum the highest magnitude (inclusive) that is considered a hit, from 0 to 1.0
155 @param minimumConsecutiveSamples if this is > 0, the method will only look for a sequence
156 of this many consecutive samples, all of which lie
157 within the target range. When it finds such a sequence,
158 it returns the position of the first in-range sample
159 it found (i.e. the earliest one if scanning forwards, the
160 latest one if scanning backwards)
162 int64 searchForLevel (int64 startSample,
163 int64 numSamplesToSearch,
164 double magnitudeRangeMinimum,
165 double magnitudeRangeMaximum,
166 int minimumConsecutiveSamples);
168 //==============================================================================
169 /** The sample-rate of the stream. */
170 double sampleRate;
172 /** The number of bits per sample, e.g. 16, 24, 32. */
173 unsigned int bitsPerSample;
175 /** The total number of samples in the audio stream. */
176 int64 lengthInSamples;
178 /** The total number of channels in the audio stream. */
179 unsigned int numChannels;
181 /** Indicates whether the data is floating-point or fixed. */
182 bool usesFloatingPointData;
184 /** A set of metadata values that the reader has pulled out of the stream.
186 Exactly what these values are depends on the format, so you can
187 check out the format implementation code to see what kind of stuff
188 they understand.
190 StringPairArray metadataValues;
192 /** The input stream, for use by subclasses. */
193 InputStream* input;
196 //==============================================================================
197 /** Subclasses must implement this method to perform the low-level read operation.
199 Callers should use read() instead of calling this directly.
201 @param destSamples the array of destination buffers to fill. Some of these
202 pointers may be null
203 @param numDestChannels the number of items in the destSamples array. This
204 value is guaranteed not to be greater than the number of
205 channels that this reader object contains
206 @param startOffsetInDestBuffer the number of samples from the start of the
207 dest data at which to begin writing
208 @param startSampleInFile the number of samples into the source data at which
209 to begin reading. This value is guaranteed to be >= 0.
210 @param numSamples the number of samples to read
212 virtual bool readSamples (int** destSamples,
213 int numDestChannels,
214 int startOffsetInDestBuffer,
215 int64 startSampleInFile,
216 int numSamples) = 0;
219 protected:
220 //==============================================================================
221 /** Used by AudioFormatReader subclasses to copy data to different formats. */
222 template <class DestSampleType, class SourceSampleType, class SourceEndianness>
223 struct ReadHelper
225 typedef AudioData::Pointer <DestSampleType, AudioData::NativeEndian, AudioData::NonInterleaved, AudioData::NonConst> DestType;
226 typedef AudioData::Pointer <SourceSampleType, SourceEndianness, AudioData::Interleaved, AudioData::Const> SourceType;
228 static void read (int** destData, int destOffset, int numDestChannels, const void* sourceData, int numSourceChannels, int numSamples) noexcept
230 for (int i = 0; i < numDestChannels; ++i)
232 if (destData[i] != nullptr)
234 DestType dest (destData[i]);
235 dest += destOffset;
237 if (i < numSourceChannels)
238 dest.convertSamples (SourceType (addBytesToPointer (sourceData, i * SourceType::getBytesPerSample()), numSourceChannels), numSamples);
239 else
240 dest.clearSamples (numSamples);
246 private:
247 String formatName;
249 JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (AudioFormatReader);
253 #endif // __JUCE_AUDIOFORMATREADER_JUCEHEADER__